About me: My name is Solène Rapenne, pronouns she/her. I like learning and sharing knowledge. Hobbies: '(BSD OpenBSD Qubes OS Lisp cmdline gaming security QubesOS internet-stuff). I love percent and lambda characters. OpenBSD developer solene@. No AI is involved in this blog.

Contact me: solene at dataswamp dot org or @solene@bsd.network (mastodon).

You can sponsor my work financially if you want to help me writing this blog and contributing to Free Software as my daily job.

OpenBSD: getting started

Written by Solène, on 03 May 2021.
Tags: #openbsd

Comments on Fediverse/Mastodon

1. Introduction §

This is a guide to OpenBSD beginners, I hope this will turn to be an useful resource helping people to get acquainted to this operating system I love. I will use a lot of links because I prefer to refer to official documentation.

If you are new on OpenBSD, welcome aboard, this guide is for you. If you are not new, well, you may learn a few things.

2. Installation step §

This article is not about installing OpenBSD. There are enough official documentation for this.

OpenBSD FAQ about Installation

3. Booting the first time §

So, you installed OpenBSD, you chose to enable X (the graphical interface at boot) and now you face a terminal on a gray background. Things are getting interesting here.

3.1. Become super user (root) §

You will often have to use the root account for commands or modifying system files.

su -l

You will have to type root user password (defined at install time) to change to that user. If you type "whoami" you should see "root" as the output.

3.2. You got a mail! §

When you install the system (or upgrade) you will receive an email on root user, you can read it using the "mail" command, it will be an email from Theo De Raadt (founder of OpenBSD) greeting you.

You will notice this email contain hints and has basically the same purpose of my current article you are reading. One important man page to read is afterboot(8).

afterboot(8) man page

3.3. What is a man page? §

If you don't know what a man page is, it's really time to learn because you will need it. When someone say a "man page" it implies "a manual page". Documentation in OpenBSD is done in manual pages related to various software, concepts or C functions.

To read a man page, in a terminal type "man afterboot" and use arrows or page up/down to navigate within the man page. You can read "man man" page to read about man itself.

Previously I wrote "afterboot(8)" but the real man page name is "afterboot", the "(8)" is meant to specify the man page section. Some words can be used in various contexts, that's where man pages sections come into the place. For instance, there are sysctl(2) documenting the system call "sysctl()" while sysctl(8) will give you information about the sysctl command to change kernel settings. You can specify which section you want to read by typing the number before the page name, like in "man 2 sysctl" or "man 8 sysctl".

Man pages are constructed in the same order: NAME, SYNOPSIS, DESCRIPTION..... SEE ALSO..., the section "SEE ALSO" is an important one, it gives you man page references of other pages you may want to read. For example, afterboot(8) will give you hints about doas(1), pkg_add(1), hier(7) and many other pages.

Now, you should be able to use the manual pages.

4. Install a desktop environment §

When you want to install a desktop environment, there will often be a "meta package" which will pull every packages required for the environment to work.

OpenBSD provides a few desktop environments like:

- Gnome 3 => pkg_add gnome

- Xfce => pkg_add xfce

- MATE => pkg_add mate

When you install a package using "pkg_add", you may find a message at the end of the pkg_add output telling you there is a file in /usr/local/share/doc/pkg-readmes/ to read, those files are specifics to packages and contains instructions that should be read before using a package.

The instructions could be about performance, potential limits issues, configuration snippets, how to init the service etc... They are very important to read, and for desktop environment, they will tell you everything you know to get it started.

5. Graphical session §

When you log-in from the xenodm screen (the one where you have a Puffer fish and OpenBSD logo asking login/password), the program xenodm will read your ~/.xsession file, this is where you prepare your desktop and the execute commands. Usually, the first blocking command (that keeps running on foreground) is your window manager, you can put commands before to customize your system or run programs in background.

# disable bell
xset b off

# auto blank after 10 minutes
xset s 600 600

# run xclock and xload
xclock -geometry 75x75-70-0 -padding 1 &
xload -nolabel -update 5 -geometry 75x75-145-0 & 

# load my ~/.profile file to define ENV
. ~/.profile

# display notifications
dunst &

# load changes in X settings
xrdb -merge ~/.Xresources

# turn the screen reddish to reduce blue color
sct 5600

# synchronize copy buffers
autocutsel &

# kdeconnect to control android phone
kdeconnect-indicator &

# reduce sound to not destroy my ears
sndioctl -f snd/1 output.level=0.3 

# compositor for faster windows drawing
picom &

# something for my mouse setup (I can't remember)
xset mouse 1 1
xinput set-prop 8 273 1.1

# run my window manager

6. Configure your shell §

This is a very recurrent question, how to get your shell aliases to be working once you have logged in? In bash, sh and ksh (and maybe other shells), every time you spawn a new interactive shell (in which you can enter commands), the environment variable ENV will be read and if it has a value matching a file path, it will be loaded.

The design to your beloved shell environment set is the following:

- ~/.xsession will source ~/.profile when starting X, inheriting the content to everything run from X

- ~/.profile will export ENV like in "export ENV=~/.myshellfile"

7. CPU frequency auto scaling §

If you run a regular computer (amd64 arch) you will want to run the service "apmd" in automatic mode, it will keep your CPU at lowest frequency and increase the frequency when you have some load, allowing to reduce heat, power usage and noise.

Here are commands to run as root:

rcctl enable apmd
rcctl set apmd flags -A
rcctl start apmd

8. What are -release and -stable? §

To make things simple, the "-release" version is the whole sets of files to install OpenBSD of that release when it's out. Further updates for that release are called -stable branch, if you run "pkg_add -u" to update your packages and "syspatch" to update your base system you will automatically follow -stable (which is fine!). Release is a single point in time of the state of OpenBSD.

9. Quick FAQ §

9.1. Where is steam? §

No steam, it's proprietary and can't run on OpenBSD

9.2. Where is wine? §

No wine, it would require changes into the kernel.

9.3. Does my recent NVIDIA card work? §

No nvidia driver, it would work but with a VESA driver, it will be sluggish and very slow.

9.4. Does the linux emulation work? §

There is no linux emulation.

9.5. I want my favorite program to run on OpenBSD §

If it's not opensource and not using a language like Java or C# that use a Language Virtual Machine allowing abstraction layer to work, it won't work (and most program are not like that).

If it's opensource, it may be possible if all its dependencies are available on OpenBSD.

Get into the ports tree to make things run on OpenBSD

9.6. Can I have sudo? §

OpenBSD ships a sudo alternative named "doas" in the base system but sudo can be installed from packages.

doas man page

doas.conf man page

9.7. How to view the package list? §

You can check the package directory in a mirror or visit

Openports.pl (using the development version of the ports tree)

9.8. What can the virtualization tool do? §

The virtualization system of OpenBSD can run OpenBSD or some linux distributions but without a graphical interface and with only 1 CPU. This mean you will have to configure a serial console to proceed to the installation and then use ssh or the serial console to use your system.

There is qemu in ports but it's not accelerated and won't suit most of people needs because it's terribly terribly slow.