These are my personal notes on installing, setting up, and using OpenBSD on two Thinkpads (an X220 and a T400). They're applicable to OpenBSD-current as at 2020-09-05 (somewhere between OpenBSD versions 6.7 and 6.8) - please bear in mind that some things may have changed if you're using a different version.
Important: You should always refer to the official OpenBSD FAQ, manual pages, or possibly a good book like Absolute OpenBSD rather than relying solely on information here or elsewhere on the web. I'm providing these notes in the hope that they can usefully supplement those resources, and I've tried to provide links back to those resources throughout.
To install OpenBSD, you should follow the Installation Guide in the OpenBSD FAQ. Below are just some notes to complement that guide.
Pay attention to the section on verifying the downloaded image before you install. From an existing OpenBSD system, it should be something like this:
$ signify -Cx SHA256.sig install68.img Signature Verified install68.img: OK
If possible, perform the installation using a wired ethernet connection even if you plan to use wifi, since (depending on your interface) the installer may need to download firmware before it can use the wifi hardware.
When you reach the installer's initial "Welcome" message, instead of proceeding with the install, choose 'S' for (S)hell, and then follow the Full Disk Encryption instructions to encrypt the entire disk with a passphrase you'll need to enter to boot the system.
Run ifconfig(8) to identify the name of your wireless interface. We'll assume it's iwn0. To scan for available wifi networks:
# ifconfig iwn0 up # ifconfig iwn0 scan
Create the file /etc/hostname.iwn0 (see hostname.if(5) for more details) as follows, to connect to the network automatically on boot:
nwid "Your SSID" wpakey "Your WPA key" dhcp
The nwid can either be an ASCII string as above, or a hexadecimal number prefixed with 0x—this is useful if the SSID contains something non-ASCII (such as emoji 😎):
nwid 0xf09f988e636f6f6c wpakey "Emoji SSIDs are cool" dhcp
If you would like your system to choose from a list of networks, you can build a "joinlist" in /etc/hostname.iwn0 instead (you can't mix and match nwid and join in one file):
join "Your SSID" wpakey "Your WPA key" join "Your other SSID" wpakey "The other WPA key" join 0xf09f988e636f6f6c wpakey "Emoji SSIDs are cool" dhcp
After setting up your hostname.iwn0, connect to the network:
# sh /etc/netstart
When you log into an X session with xenodm(1) on a fresh install of OpenBSD, the file /etc/X11/xenodm/Xsession is responsible for setting up your session. Towards the end of that file, it runs $HOME/.xsession if that file exists and is non-empty; otherwise, it just runs xterm(1) and fvwm(1) - that's what you see when you log into a fresh install.
To customise your X session, create the file
.xsession in your home directory. It is normally a shell script, and your X session will end when it finishes running. So, to have multiple programs run at startup, make sure that all commands except the last one either complete quickly or are run 'asynchronously' (i.e. run with an "
&" after the command). For example, here is how you'd recreate the default behaviour described above in your own
xterm & fvwm
The xterm stays running, but control immediately passes on to the next line. When fvwm quits, you will be logged out.
That's a pretty minimal
.xsession—what else might you add to it? Here are a couple of ideas from my
If you don't use the caps-lock key, you can use setxkbmap(1) to remap it to a key you use more often, such as escape or control (I learned about this from Cullum Smith's excellent OpenBSD on a laptop guide). To remap caps-lock as an extra control key:
setxkbmap -option ctrl:nocaps
Or to remap it as an extra escape key:
setxkbmap -option caps:escape
The full list of different ways you can remap keys can be found under
/usr/X11R6/share/X11/xkb - see e.g.
You can change the background/wallpaper (“root window”) to a solid colour, or a variety of simple two-colour patterns, using xsetroot(1). Colours can either be names like
/usr/X11R6/share/X11/rgb.txt for the full list of names), or they can be hexadecimal colour references like
"#2a1e2f". For example, to set a solid black background:
xsetroot -solid black
My favourite setting uses the
-mod option to create a grid with two colours:
xsetroot -mod 16 16 -bg "#112233" -fg "#552211"
Here's what that looks like:
To customise what X looks like before you log in—on the login screen—you can modify the file
As I write this, the unmodified file contains an xsetroot(1) line to set a gentler version of the standard X "root weave" background. You can modify this line as described above—in fact, if you don't set the background after logging in (e.g. in your
.xsession), then the one set by xenodm(1) will persist. Personally, I set my xenodm(1) background to a slight colour-variation of my
.xsession one above:
xsetroot -bg \#222229 -fg \#115522 -mod 16 16
That ends up looking like this: