[ home ]

Running OpenBSD 7.5 on your laptop is really hard (not)

5th April 2024: OpenBSD 7.5 has been released. I worked through all the steps in this page using a fresh install.

Follow the steps in this page to install OpenBSD 7.5 and configure an xfce desktop and Firefox on a Thinkpad T61 laptop (intel graphics, 500Gb mechanical hard drive and 4Gb RAM) with legacy BIOS enabled. I used the amd64 version of the install.img image. It is best to avoid laptops with nVidia based graphics with OpenBSD.

Each section of this guide links to the appropriate section of the OpenBSD FAQ and the relevant man pages. At the time of writing, the online man pages for OpenBSD 7.5 have not been generated, so the links in this page lead to the man pages for the current development version.

I hope that the resulting tour around the documentation will help you to explore OpenBSD in more detail on your own. Remember to read man afterboot before working through the later steps.

I'm assuming that you have installed a Linux distribution before and are familiar with the command line. You will need to edit configuration files in some of the steps. I'm also assuming that you can dedicate a laptop solely to OpenBSD. I use old 'refurbished' Thinkpads which are cheap to buy in the UK.

Install OpenBSD using FAQ

Check that your laptop's video adapter and WiFi card are supported in the the Pre-Installation Checklist. My Thinkpad T61 has supported video but needs firmware for the WiFi card. Use dd on linux to write install.img to a USB stick.

Before starting the installation you need to think up


You need to select non-default options at four stages in the installation...

Reboot into the graphical log-in screen and type your username and password.

Prepare to visit 2001!

Default Graphical session with fvwm

The OpenBSD base includes an ancient version of fvwm as the default window manager. You can do most of the rest of the configuration from here.

You should see an xterm window at the top left of the screen with the foo $ prompt and possibly very small fonts.

The following steps might help

Now would be a good time to read the system mail and man afterboot

foo$ mail
foo$ man afterboot

Editing configuration files on OpenBSD

You will need to create and edit a small number of configuration files.

OpenBSD comes with three command line editors (ed, mg and vi) and one graphical editor (xedit). I find the emacs-like mg to be the easiest to just use. The following default keyboard shortcuts will get you going

Connect to wired network

The ifconfig command provides networking from the command line including bringing up interfaces. OpenBSD interfaces are named after the driver in use and my T61 has one ethernet card that uses the em driver, so ifconfig sees that card as the em0 interface.

foo$ su -
foo# ifconfig em0                                                       
em0: flags=8802<BROADCAST,SIMPLEX,MULTICAST> mtu 1500
    lladdr 54:ee:75:1a:a5:b2
    index 1 priority 0 llprio 3
    media: Ethernet autoselect (none)
    status: no carrier

To start the interface and request an IP address type...

foo# ifconfig em0 up
foo# ifconfig em0 inet autoconf

I like to use ping to check the connection...

foo# ping bbc.co.uk
ping: Warning: bbc.co.uk has multiple addresses; using
PING bbc.co.uk ( 56 data bytes
64 bytes from icmp_seq=0 ttl=55 time=52.276 ms

Install any firmware and update base

You can install the firmware. Become root (I always use su - so I have a login session) and use the fw_firmware command...

foo$ su -
foo# fw_update
fw_update: added intel,inteldrm,wpi; updated none; kept none

The wpi package contains the firmware that the Thinkpad T61 WiFi card needs.

Next use syspatch to update the OpenBSD base. The example below is from OpenBSD 7.5.

foo# syspatch
Get/Verify syspatch75-001_xserver... 100% |*************|  4308 KB    00:01    
Installing patch 001_xserver
Errata can be reviewed under /var/syspatch

Then you can reboot to use the new kernel...

foo# reboot

Connect to home wifi

This old Thinkpad T61 has an intel wifi card that uses the wpi driver.

For my home network with wpa2 authentication I used echo to populate /etc/hostname.wpi0 as follows...

foo# echo "join mywifi wpakey mypassword" >> /etc/hostname.wpi0
foo# echo "inet autoconf" >> /etc/hostname.wpi0
foo# echo "inet6 autoconf" >> /etc/hostname.wpi0

I enable both ip4 and ip6 on my home connection, it does not seem to make a lot of difference.

Then restart networking to bring the wifi up.

foo# sh /etc/netstart
WARNING: /etc/hostname.wpi0 is insecure, fixing permissions.

I usually check the connection is working using the ping command

foo# ping bbc.co.uk
ping: Warning: bbc.co.uk has multiple addresses; using
PING bbc.co.uk ( 56 data bytes
64 bytes from icmp_seq=0 ttl=53 time=52.342 ms
64 bytes from icmp_seq=1 ttl=53 time=126.758 ms
64 bytes from icmp_seq=2 ttl=53 time=44.035 ms
^C  [ Ctrl-C to stop the pinging ]
--- bbc.co.uk ping statistics ---
3 packets transmitted, 3 packets received, 0.0% packet loss

To connect to a coffee shop WiFi from the command line I used the following commands...

foo# ifconfig wpi0 up
foo# ifconfig wpi0 scan
[big list of wifi connections - you can pick the one for the cafe
and then copy/paste the ssid into the join command ]
foo# ifconfig wpi0 join cafewifiname [wpakey key-if-there-is-one]
foo# ifconfig wpi0 inet autoconf

Install software additional to OpenBSD base (packages)

The OpenBSD base is released as a single coherent operating system. It includes very little desktop application software. You can use binary packages provided or ported by volunteers to install extra software.

The example below shows how to install w3m the text mode Web browser

foo# pkg_add w3m
quirks-7.14 signed on 2024-04-06T12:55:16Z
Ambiguous: choose package for w3m
a       0: 
        1: w3m-0.5.3pl20230121p1
        2: w3m-0.5.3pl20230121p1-image
Your choice: 1
w3m-0.5.3pl20230121p1:boehm-gc-8.2.4: ok
w3m-0.5.3pl20230121p1: ok

Two points to note...

You can find out about any package using the pkg_info command. See the FAQ and man page.

Power management

OpenBSD uses the apmd daemon to provide automatic frequency scaling to save battery and reduce processor temperatures. From OpenBSD 7.1 the behaviour of the automatic (apmd -A) setting when on mains power has changed. You install the obsdfreqd package to provide fan and cpu speed control instead.

Daemons are enabled, started and stopped using the rcctl command as root. The command writes lines to the /etc/rc.conf.local file.

Install obsdfreqd from packages...

foo# pkg_add obsdfreqd
quirks-6.121 signed on 2023-03-26T10:10:23Z
obsdfreqd-1.1.1: ok
The following new rcscripts were installed: /etc/rc.d/obsdfreqd
See rcctl(8) for details.

Enable and start apmd and obsdfreqd as root...

foo# rcctl set ampd status on
foo# rcctl set apmd flags -L
foo# rcctl start apmd
foo# rcctl enable obsdfreqd
foo# rcctl start obsdfreqd  

You can suspend to RAM using the zzz command. Some laptops will suspend when you close the lid and resume when you open the lid.

User mounting of external drives

External drives are numbered sd1, sd2 instead of the familiar sdb, sdc in Linux. Letters are used to show partitions so a USB stick that is seen as sdb1 on Linux would be sd1i on OpenBSD.

To check the drive number for an external drive, plug it in and then run dmesg or dmesg | tail and look for a drive number in the last few lines.

OpenBSD does not provide automounting of external storage. Instead you can use the mount and umount commands as root. Support for ntfs drives (most external hard drives) is provided by installing the ntfs_3g package. The ntfs-3g command is run in place of mount when using an ntfs drive.

You can run these commands as an ordinary user by setting up a /etc/doas.conf file.

First install ntfs_3g package as root...

foo# pkg_add ntfs_3g
quirks-7.14 signed on 2024-04-06T12:55:16Z
ntfs_3g-2022.10.3:e2fsprogs-1.46.2p1: ok
ntfs_3g-2022.10.3: ok

Then as root create /etc/doas.conf as below...

foo# mg /etc/doas.conf

Add the following lines where USER is your user name

permit nopass USER as root cmd mount
permit nopass USER as root cmd umount
permit nopass USER as root cmd ntfs-3g

To mount an external USB stick you have to

To find the disk label I just use dmesg...

foo$ dmesg | grep sd1
sd1 at scsibus4 targ 1 lun 0: <Kingston, DataTraveler 2.0, 1.00> removable   serial.loadsanumbers
sd1: 3852MB, 512 bytes/sector, 7888896 sectors

Then to actually mount the drive...

foo$ mkdir usb
foo$ doas mount /dev/sd1i ~/usb
foo$ ls usb

Once mounted you can use file commands such as cp and ls as usual or run a graphical file manager like thunar. When you have finished with the drive you can unmount the drive using...

foo$ doas umount ~/usb
foo$ ls usb

Mounting an external ntfs formatted hard drive works the same way but using the ntfs-3g command in place of mount...

foo$ doas ntfs-3g /dev/sd1i ~/wd
foo$ ls wd
Backup_T61 software music
foo$ doas umount ~/wd
foo$ ls wd

Once xfce is installed you can use the xfce-mount panel applet within xfce to access these commands with the mouse. See later.

Allow users to shutdown and reboot

You could add lines to /etc/doas.conf to allow you to shutdown from your normal user account.

But you can also add your user account to the _shutdown group. The _shutdown group is a recent innovation. Previously, you would add your user to the operator group. Using group permissions in this way has the advantage that xfce can then be shutdown or rebooted using the Applications menu.

foo# usermod -G _shutdown username
foo# groups username
username wheel _shutdown

You have to restart a login session to see the new group membership...

$ su - user
$ groups
user wheel _shutdown

Then you can shutdown using...

foo$ shutdown -ph now

The reboot command does not work from the command line...

foo$ reboot
reboot: Operation not permitted

...but you can reboot from the xfce logout screen.

Increase memory limits for programs

I think that this section is now redundant. The default settings (your user is assigned to the 'staff' login class and the :datasize-max=infinity:\ setting in the staff stanza of the login.conf file) appear to mean that your applications have access to all the memory without altering any sessions. On my Thinkpad X201 with 4Gb RAM I was able to run Firefox with plugins disabled (no add blocker) and 8 tabs open with heavy Web pages and a YouTube video playing. Firefox was using a couple of GB of RAM. No problems other than the fan noise!

OpenBSD imposes a maximum memory limit on each program. The size of that limit depends on your user account login class. By default your user account has the staff login class

First check that your user has the staff login class using the vipw command. This command will allow you to edit the passwd.master file. This file is very carefully protected and so you have to edit the file using the vipw command, which invokes the vi editor.

foo# vipw

Scroll down the file untill you reach your username, or use the vi search /username to jump to that line. The line should look something like this...

myuser:BIG LONG STRING HASH:1000:1000:staff:0:0:myuser:/home/myuser:/bin/ksh

As you can see myuser is in the staff login class by default. If there is a different class name there you can change the login class by placing the cursor on the first character of whatever the word is using the arrows, and then pressing cw (change word). Then type 'staff' and press ESC. Finally save changes by SHIFT-: and typing x.

Then you can edit the /etc/login.conf file so that the staff stanza looks like this...

# Staff have fewer restrictions and can login even when nologins are set.

This Thinkpad T61 has 4Gb of RAM. I chose 3072 Mb as the limit more or less at random. Web browsers are notoriously demanding of memory.

OpenBSD is quite strict about the behaviour of programs. Applications sometimes crash and leave a core file in the user's home named something like appname.core. You can just delete these core files.

Edit /etc/X11/xenodm/Xsetup_0 to stop the beep and xconsole

OpenBSD's fork of Xorg is called xenocara. The graphical login screen is provided by xenodm, a fork of xdm. By default a new X session loads the Xconsole. The beeps can get annoying as well. Edit the file /etc/X11/xenodm/Xsetup_0 as follows to restore order...

foo# mg /etc/X11/xenodm/Xsetup_0

Comment out the line (line 9 on my version) that reads

${exec_prefix}/bin/xconsole -geometry 480x130-0-0...

by putting a # in front. Then add the line to switch off the bell...

${exec_prefix}/bin/xset b off

then save.

Choices of desktop and software

You could install Firefox, Chromium (or Iridium) and (say) xpdf as the system stands and have basic functionality with fvwm. You could explore the other window managers in the OpenBSD base install, cwm or the very basic twm.

For a more graphical approach, you can install the Gnome, Xfce or KDE desktop environment, or a lighter desktop such as LXQt or Lumina. I use Xfce as it is familiar to me and allows graphical management of external USB sticks using the xfce4-mount panel applet.

The port maintainer for a larger package often puts useful information in a pkg-readme. You can get a list of them as follows...

foo$ ls /usr/local/share/doc/pkg-readmes

For example, the Firefox pkg-readme shows that Firefox now has pledge and unveil support. That means that Firefox can only save or load files to one directory at ~/Downloads. There are instructions for changing this behaviour.

Install xfce, Firefox and a pdf reader

First install Firefox and xpdf

foo# pkg_add firefox xpdf lohit-fonts-2.5.3p2 zh-fonts-arphicttf-2.11p4.tgz

This will take some time as Firefox has a lot of dependencies. In OpenBSD 7.5 you will be given a choice of xpdf3 or xpdf version 4. I prefer the old motif based xpdf3 personally but the more recent version using GTK3 has more UI features. The two font packages provide Asian and Indian continent fonts to avoid those square place holders in Web pages.

Installing a full Xfce desktop requires a few steps

First install the all the packages. This will take some time because of the dependencies. Then skim the pkg-readme for Xfce...

foo# pkg_add xfce xfce-extras xfce4-power-manager upower
foo# less /usr/local/share/doc/pkg-readmes/xfce

Then make a file at ~/.xsession like this

foo$ cat ~/.xsession

To use the xfce power manager, I found it necessary to enable and start the messagebus daemon

foo# rcctl enable messagebus
foo# rcctl start messagebus

The xfce panel battery icon will then tell you the battery time remaining.

Now you can exit from .fvwm and login to a 'first run' Xfce session.

You could then reboot using the Xfce Application menu logout buttons as a test.

Using xfce4-mount panel applet to mount and unmount external drives

You need to configure the panel plugin as follows...

Add an icon for the plugin to the XFCE4 panel by right-clicking on the panel and selecting Panel | Add New Items and searching for mount.

Right click over the xfce4-mount icon and select Properties | File Systems tab. Add the pattern /dev/sd0* to the Exclude specified file systems textbox so the local drive is not listed.

Right-click on the xfce4-mount icon, and select Preferences | Commands and write the following in the Custom Commands textboxes, after ensuring that the Custom Commands checkbox was ticked

 doas mount %m
 doas umount %m

Now to ensure that a USB stick is listed in the xfce4-mount-popup list, you have to add a line for the device to /etc/fstab...

foo# echo "/dev/sd1i /home/keith/usb msdos rw,noauto 0 0" >> /etc/fstab

Using an fstab entry like this means that only one vfat formatted USB thumb drive will be listed and available with mouse clicks.

Installing with whole drive encryption

See OpenBSD FAQ - Disk Setup - Full Disk Encryption for background detail.

Since OpenBSD 7.4 the installer has offered the option of setting up an encrypted 'soft raid' partition to hold the operating system, user data and swap.

Disk numbering: The hard drive I am installing to is recognised as sd0, the USB stick with the installation sets is recognised as sd1 and the installer creates a softraid device as sd2. After rebooting into the new installation the softraid device is renumbered as sd1.

Below is a sample dialogue of an installation using an encrypted hard drive unlocked with a pass phrase. Starting from the disk section of the installer dialogue. My choices are in BLOCK CAPS after each prompt.

Available disks are: sd0, sd1, sd2
Which disk is root disk? [sd0] RETURN TO ACCEPT DEFAULT
Encrypt the root disk with a (p)assphrase or (k)eydisk? p RETURN
(W)hole disk MBR, whole disk (G)PT, (O)penBSD area or (E)dit? w RETURN
Retype passphrase: MY PASS PHRASE RETURN
Use (w)hole disk MBR, whole disk (G)PT, or (E)dit? [whole] RETURN

Then I continued with the normal autoformat which results in a number of partitions in the disklabel with default sizes.

History of this page

This page has been improved by feedback from people who have used it to install and explore OpenBSD. Suggestions and experiences welcome.

[ 5.5 | 6.2 | 6.3 | 6.4 | 6.5 | 6.6 | 6.7 | 6.8 | 7.0 | 7.1 | 7.2 | 7.3]

Keith Burnett
Last modified: Wed May 15 19:27:14 BST 2024