OpenBSD 5.6 Desktop HOWTO

Last updated: Jan 11, 2015

Yet Another One?

There are a few other variants of desktop HOWTOs available from other users, such as Eric Radman and Jussi-Pekka Erkkilä. Information contained herein is partially a repeat from other sources. The purpose of this HOWTO is to simply write down what I have done to a fresh install of OpenBSD 5.6 to get it to a minimal working desktop with the dwm tiling manager, just so I won't have to remember it all... Some may say HOWTOs like this one distract users from original documentation and I wholeheartedly agree. OpenBSD FAQ contains a wealth of information on how to get started, and if you want to get even better understanding how the system works, OpenBSD is notorious for its detailed Manual Pages.

I find it easier to use su(1) instead of sudo(8) on a single-user desktop, thus commands that should be issued as root are prefixed with the # symbol below. I also don't use display managers and prefer to start the X Window System with startx(1), thus configuration of xdm(1) is not included in this HOWTO. Please refer to the X Window System section of the OpenBSD FAQ for more information about display managers.

A good place to start after the first complete boot is the afterboot(8) manual page:

$ man afterboot

System Daemons

The beauty of OpenBSD is its simplicity. It comes out of the box with pretty much everything one needs for a minimal desktop workstation or a laptop. The only things that may be desired extra would be ntpd(8) to synchronize system time, and apmd(8) to control power features on the laptop, such as CPU scaling. For this, edit /etc/rc.conf.local and set:
Lines above cancel default NO values for those daemons in the /etc/rc.conf that is desired to be left intact. The ntpd(8) may be already enabled on your system if you have positively answered a question during installation, however I have included it into this example for illustrative purposes. You may want to start it with the -s flag to set the time immediately on the startup. It is also worth to mention that you may want to use -C or -A flags with the Advanced Power Management daemon. The former optimizes the system for low power use while the latter optimizes for performance when using AC power, however scales down when using battery. I find the default "" apmd(8) setting to be optimal for my laptop which is often connected to AC power. That's it!

Wireless Networking

OpenBSD provides a very convenient way to assicate wireless network interfaces with a default access point. Just edit the /etc/hostname.if files. This is described in the Networking section of the OpenBSD FAQ. Here is an example of my /etc/hostname.iwn0 for automatic association with AccessPoint, whereby iwn0 is my Wi-Fi NIC:
nwid AccessPoint
wpakey password
More information on how to use hostname.if configuration files, including for Ethernet NICs, is available from the hostname.if(5) manpage. To re-initialize the networking system with new configuration, execute as root:
# sh /etc/netstart
To scan available access points:
# ifconfig if scan
To associate with an access point AccessPoint manually and use DHCP to obtain IP address:
# ifconfig if nwid AccessPoint wpakey password
# dhclient if

Installing Packages

First of all, the repository must be set so the system will know where to pull packages from. A good place may be the ~/.profile of root:
export PKG_PATH=ftp://your.openbsd.mirror/pub/OpenBSD/5.6/packages/`machine -a`/
A list of mirrors is available on the OpenBSD web site. When the OpenBSD's default ksh (Korn shell) starts, it reads this file to initialize. The PKG_PATH will be set at this time. For other shells the location of the profile may be different. This is all what's needed to begin adding packages to the system by using:
# pkg_add PackageName
At this point I generally install a variety of desktop packages, such as chromium, thunderbird, and many others.

Getting the Ports Tree

While OpenBSD is packages-oriented system, it is convenient to use the port system to install, for example, X fonts or the dwm that requires you to edit its source code to configure. To begin using ports, we will need to untar the port tree to the /usr directory:

# cd /tmp
# ftp ftp://your.openbsd.mirror/pub/OpenBSD/5.6/ports.tar.gz
# cd /usr
# tar xzf /tmp/ports.tar.gz
After this, to install a port, change the active directory to this port's directory and issue:
# make install clean
A good reference for using ports system is available in the OpenBSD Porter's Handbook.

Intalling and configuring dwm

From ports. To install and configure dwm, I use the following procedure:
# cd /usr/ports/x11/dwm
# make patch
# cd `make show=WRKDIST`
At this point, you can patch and edit dwm files. To international keyboard functionality functionality, I change the *keyus mapping in the dwm's config.h file as following, to execute my changexkbmap script:
static const char *keyus[] = { "/home/username/changexkbmap",  NULL };
Once finished patching, change directory back and continue to install:
# cd -
# make install

International Keyboard Layouts

The ~/changexkbmap script is used to change keyboard layout for internationalization purposes. It is initiated by dwm as I have mapped it to Alt+Space. It cycles between two layouts.
layout=`setxkbmap -query | sed -rn 's/layout.*(..)/\1/p'`
case $layout in
    setxkbmap us

    setxkbmap ru

X Window System Startup Sequence

The ~/.xinitrc file in the home directory is the X Window System startup shell script. Here, I place my window manager and other applications to run in the background while X is running. It makes use of the xcalib program to adjust monitor calibration as well as the dwm tiling window manager. feh is used to set background image in X. All programs are available as ports or packages in OpenBSD. Much of this file is optional.
# Set X font paths - here is my personal TTF collection 
xset fp+ /usr/local/lib/X11/fonts/myfonts

# Font paths for installed fonts
xset fp+ /usr/local/lib/X11/fonts/mscorefonts
xset fp+ /usr/local/lib/X11/fonts/terminus

# Make the X server to reread the font database from the paths set above
xset fp rehash

# Disable X beep
xset b off

# Enable Touchpad tap and vertical edge scroll 
synclient TapButton1=1
synclient VertEdgeScroll=1

# Calibrate display with an ICM profile
/usr/local/bin/xcalib /home/username/monitor_calibration_profile.icm 

# Erase weather data and run wunderground script in the background to fetch outside temperature 
echo "" > /home/username/.wunderground 
/home/username/wunderground &

# Set background image 
feh --bg-fill /home/username/background.jpg


# Set dwm caption showing date, current keymap, mixer volume, weather and battery status in the 
# caption
while xsetroot -name "`date` `setxkbmap -query | sed -rn 's/layout.*(..)/\1/p'` vol:`mixerctl \
 outputs.master | sed -rn 's/outputs.master=(...?),(...)?/\2/p'`/255 $wunderground $batterywatch"
    sleep 1
    wunderground=`cat /home/username/.wunderground`

case `sysctl -n hw.sensors.acpiac0.indicator0` in
    "Off (power supply)")
    batterywatch="batt:`sysctl -n hw.sensors.acpibat0.watthour3 | cut -f1,2 -d" "`"
    "On (power supply)")
done &

# Launch uxterm window when X starts
uxterm &

# Run dwm in infinite loop until X server is running
while true; do
    # Log stderror to a file 
        dwm 2> ~/.dwm.log

Getting Outside Temperature

The ~/wunderground script fetches outside temperature from Weather Underground and puts the results into ~/.wunderground file. By default Prague weather station is used.
while true 

    tstring=`curl -s $url | sed -rn 's/<title>Current Conditions : (.*),(.*)/\1/p'`
    echo $tstring > /home/username/.wunderground
    /bin/sleep ${loop}


UXTerm Customization

The file ~/UXTerm is used to customize terminal. Most of the fields are self-explanatory. The saveLines section expands the scroll buffer. The ISO10646 font regsitry enables unicode.
UXTerm*Background:		black
UXTerm*Foreground:		gray
UXTerm*saveLines:		10000
UXTerm*scrollBar:		off
UXTerm*font: 			-*-fixed-bold-*-*-*-15-*-*-*-*-*-iso10646-*

Performance Tweaks

OpenBSD default resource limits are rather restrictive. Without raising them, resource-hungry applications like chromium or thunderbird will segfault due to being out of memory. Resource settings are available at /etc/login.conf:
The user running X should be of the staff class (do not confuse with the group) for these settings to take effect:
# usermod -L staff username
At this point it usually makes sense to add this user to the wheel group to be able ot use su:
# usermod -G wheel username
It also makes sense to add softdep option to the /etc/fstab to increase disk writing performance. Example:
DUID.b none swap sw
DUID.a / ffs rw,softdep 1 1
DUID.k /home ffs rw,nodev,nosuid,softdep 1 2
DUID.d /tmp ffs rw,nodev,nosuid,softdep 1 2
Above, disklabel unique identifiers (DUIDs) are used. Your fstab may contain device names instead. I also disable core dumps in ~/.profile by adding:
ulimit -c 0

HTML5 Video

No known solutions exist, unfortunately. If you know how to play video without stuttering inside a web browser, please tell me.

Change Log

Jan 11, 2015 Jan 9, 2015 Jan 8, 2015


I thank the following people for helping me put this together: Darren Breidigan, Kennith (Kenny) Mann, Paul Kelly, Raf Czlonka.

OpenBSD Desktop HOWTO by Maxim Usatov, maxim.usatov@bcsatellite.net