James’s OpenBSD notes

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.

Installation and full disk encryption

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.

Wifi configuration

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"

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"

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"

After setting up your hostname.iwn0, connect to the network:

# sh /etc/netstart

X11 configuration

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 .xsession:

xterm &

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 .xsession:

Making the caps-lock key into something more useful

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. /usr/X11R6/share/X11/xkb/rules/base.

Setting a nice background

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 BlanchedAlmond or purple4 (see /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:

Small screenshot showing a dark slate and purple background pattern

xenodm(1) customisation

To customise what X looks like before you log in—on the login screen—you can modify the file /etc/X11/xenodm/Xsetup_0.

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:

Small screenshot showing a dark slate and green background pattern