[ home ]

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

19th October 2023: OpenBSD 7.4 has arrived. Install works as below except that you add your user to the new _shutdown group to be able to shutdown instead of the operator group.

Follow the steps in this page to install OpenBSD 7.3 and configure an xfce desktop and Firefox on a laptop. I used a Thinkpad L440 (intel graphics and 8Gb 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. 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.

Install OpenBSD using FAQ

Check that your laptop's video adapter and WiFi card are supported in the the Pre-Installation Checklist. My Thinkpad L440 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!

Alternate install with encrypted hard drive

April 12th: This section is not well-tested and is based on a single quick trial. I will update this in a few days.

The OpenBSD 7.3 installer has a new question asking if you want to encrypt the main disk. If you answer [yes] to that question you will be prompted for a passphrase to unlock the disk. Then the installer will create the softraid device but not mount it. Finally you will be asked to specify which disk to install the package sets to.

Drive numbering during installation on this laptop...

The installer asks which disk to use to install OpenBSD to and on this laptop the default was sd1 which is the USB stick. I had to change the default to sd2 and proceed with the installation.

Once you reboot...

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 L440 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,iwm,vmm; updated none; kept none

The iwm package contains the firmware that the Thinkpad L440 WiFi card needs.

Next use syspatch to update the OpenBSD base. The example below is from OpenBSD 7.2 as there are no errata for OpenBSD 7.3 yet.

foo# syspatch
Get/Verify syspatch72-001_x509.tgz 100% |***************| 14494 KB    00:07  
Get/Verify syspatch72-012_acme.tgz 100% |***************| 40197       00:00    
Installing patch 012_acme
Relinking to create unique kernel... done; reboot to load the new kernel
Errata can be reviewed under /var/syspatch

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

foo# reboot

Connect to home wifi

You can connect to WiFi in two ways, using an ifconfig command line as root, or setting up a hostname.if file to connect at boot up. Using a /etc/hostname.if file makes sense for a home connection. You create the file as root.

The Thinkpad L440 uses the iwm WiFi driver and so the hostname.iwm0 file looks like this...

foo# cat /etc/hostname.iwm0
           join WIFINAME wpakey PASSWORD
           inet autoconf

You can use /etc/netstart as root to start up the connection for the first time (because hostname.iwm0 contains your WiFi password, OpenBSD sets it to 640 permissions)...

foo# ifconfig iwm0 up
foo# sh /etc/netstart 
WARNING: /etc/hostname.iwm0 is insecure, fixing permissions.
foo# ping bbc.co.uk   
ping: Warning: bbc.co.uk has multiple addresses; using
PING bbc.co.uk ( 56 data bytes

The Networking FAQ 'Configuring a Wireless Adapter' section has example commands for connecting to coffee shop WiFi networks.

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-6.121 signed on 2023-03-26T10:10:23Z
quirks-6.121: ok
Ambiguous: choose package for w3m
a       0: 
        1: w3m-0.5.3pl20230121
        2: w3m-0.5.3pl20230121-image
Your choice: 1
w3m-0.5.3pl20230121:libiconv-1.17: ok
w3m-0.5.3pl20230121:gettext-runtime-0.21.1: ok
w3m-0.5.3pl20230121:boehm-gc-8.0.4p0: ok
w3m-0.5.3pl20230121: 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 enable apmd
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-6.121 signed on 2023-03-26T10:10:23Z
ntfs_3g-2022.5.17p0:e2fsprogs-1.46.2p0: ok
ntfs_3g-2022.5.17p0: 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_L440 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 operator group. That has the advantage that xfce can then be shutdown or rebooted using the Applications menu.

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

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

$ su - user password: $ groups user wheel operator

Then you can shutdown using...

foo$ shutdown -ph now

Or reboot using

foo$ reboot

Increase memory limits for programs

OpenBSD imposes a maximum memory limit on each program. The size of that limit depends on your user account login class. You can add your user account to the staff user group and then change the limit for staff in the /etc/login.conf file.

First add your user to the staff group

foo$ su -
foo# usermod -G staff username

Then 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.
    :datasize-cur=6144M:\    [increased from 1512M]

This Thinkpad L440 has 8Gb of RAM. I chose 6144 Mb as the limit more or less at random. Web browsers are notoriously demanding of memory and I have not seen any crashes with Firefox yet.

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 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

This will take some time as Firefox has a lot of dependencies.

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

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.

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]

Keith Burnett
Last modified: Fri Jan 6 18:26:58 GMT 2023