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:
OpenBSD's default window manager is fvwm(1), the Feline (maybe) Virtual Window Manager. OpenBSD comes with fvwm version 2.2.5, while (at the time of writing) fvwm 2.6.5 is available as a package (named
fvwm2). This newer version does have some nice features, but for the purpose of these notes we are sticking to the default install as much as possible, so what follows is specific to OpenBSD's default fvwm 2.2.5.
On a fresh install, the file
/usr/X11R6/lib/X11/fvwm/.fvwmrc control's fvwm's configuration. If you wish to customise the configuration using that file as a starting point, you can make a copy at
$HOME/.fvwmrc - this will then be used as fvwm's configuration instead.
In your new
$HOME/.fvwmrc, find the "Menus" section. Under the '
AddToMenu RootMenu...' line, you should see the current menu items. Let's add a launcher for Firefox, right underneath the existing XTerm line:
######################## Menus ################### AddToMenu RootMenu "Root Menu" Title + "XTerm%mini.xterm.xpm%" Exec exec xterm + "Firefox" Exec exec firefox
You can also add an icon next to the name of the program, just as XTerm has:
Here's a way to do that (using the
convert utility from the
firefoxpackage, and place it in $HOME/icons:
$ mkdir $HOME/icons $ convert -resize 14 /usr/local/lib/firefox/browser/chrome/icons/default/default128.png $HOME/icons/firefox.xpm
$HOME/iconsdirectory to the
PixmapPathline near the top of your
.fvwmrc, separated by a colon:
+ "Firefox%firefox.xpm%" Exec exec firefox
I like to use GKrellM as a system monitor, and I want to have it present on every virtual desktop (i.e. I want it to be 'sticky' in window manager parlance). To do this in your
.fvwmrc, go to the "Styles for various common programs" section and add a line like the following:
Style "gkrellm" Sticky
The Fvwm pager (the miniature view of your virtual desktops) is configured by default with the
StaysOnTop style option. This can be annoying if you frequently maximise windows (though note that you can temporarily lower any window, even a
StaysOnTop one, by double-clicking on its window-frame). To set the pager to normal ('
StaysPut') behaviour, find this line in your
.fvwmrc and comment it out:
#Style "FvwmPager" StaysOnTop
Classical X applications like xterm(1) can be configured by setting “resources” (see the “RESOURCES” chapter in X(7) for details). The usual place to write your personal X resources is in
$HOME/.Xdefaults (see Loading the Resource Database in the X Toolkit Intrinsics documentation for more on where resources can be specified). This file is read on each application launch (no need to restart your X session).
The foreground and background colours of the terminal can be set as follows in your
Note that the colour names you can use are the same as I described above in "setting a nice background", including hex colour references.