Getting started with OpenBSD

Last edited on 2025-04-05 • Tagged under #openbsd #bsd

Tested on OpenBSD 7.6

I've run various distributions of Linux for a number of years, but with little exposure to other Unix-like operating systems. I want to explore different ways of doing things on a computer, and I'm curious about the Berkeley Software Distribution (BSD) releases. I've briefly looked at FreeBSD and NetBSD.

Now I want to give OpenBSD a go with beginner's mind.

I use the OpenBSD install image to create an encrypted, console-only base configuration that can be customized further for various tasks.

This is how I do it...

Start Here

Throughout this guide, if you see square brackets [] in code blocks, that means the word of code (square brackets included) should be replaced with something else. This is detailed in the instructions before or after the code block.

This guide makes a few assumptions:

Target device is amd64 architecture
System uses UEFI to boot and will use a GPT partition table
OpenBSD will be the sole OS on an (encrypted) single disk
OpenBSD install media will be prepared on a Linux-based system
Ethernet will be used for network access during install

Download the OpenBSD install image and the SHA256 file for verification:

wget -c https://cdn.openbsd.org/pub/OpenBSD/7.6/amd64/install76.img
wget https://cdn.openbsd.org/pub/OpenBSD/7.6/amd64/SHA256

Download a copy of root's mail for reference that will be delivered at first login:

wget https://cdn.openbsd.org/pub/OpenBSD/7.6/root.mail

Verify the disk image using sha256sum:

sha256sum -c --ignore-missing SHA256

Plug in the USB stick and identify its device label:

lsblk -f

If the USB stick is mounted, unmount the device:

sudo umount /dev/[device_label]

For example, if the USB stick is mounted as sde1:

sudo umount /dev/sde1

NOTE
Be very careful to note the proper device. All contents on the device will be lost!

Write the install image to the USB stick using the dd command:

sudo dd if=install76.img of=/dev/[device_label] bs=1M status=progress && sync

Using the previous example of sde1, this example would write to sde (omit the partition number):

sudo dd if=install76.img of=/dev/sde bs=1M status=progress && sync

Installation

Boot the target device with our new USB install stick.

User is automatically logged in as root to the first virtual console and presented with the installation program prompt. Select i to start the install:

Welcome to the OpenBSD/amd64 7.6 installation program.
(I)nstall, (U)pgrade, (A)utoinstall or (S)hell? i

Install steps:

Choose your keyboard layout [layout] # Press <enter> for default (us qwerty) or input an alternative. Example: us.colemak
System hostname? [hostname] # Example: foobox
Network interface to configure? [interface] # Wired interface usually auto-detected. Example: em0
IPv4 address for em0? autoconf
IPv6 address for em0? none
Network interface to configure? done
Password for root account? (will not echo) [password]
Password for root account? (again) [password]
Start sshd by default? yes
Do you want the X Window System to be started by xenodm? no
Setup a user? [username] # Example: foo
Full name for user foo? foo
Password for user foo? (will not echo) [password]
Password for user foo? (again) [password]
Allow root ssh login? no
What timezone are you in? [timezone] # Example: Canada/Eastern
Which disk is the root disk? sd0
Encrypt the root disk with a (p)assphrase or (k)eydisk? p
Use (W)hole disk MBR, whole disk (G)PT, or [E]dit? gpt
Configuring the crypto chunk sd0...
Use (W)hole disk MBR, whole disk (G)PT, or [E]dit? gpt
New passphrase: [passphrase]
Re-type passphrase: [passphrase]
Configuring the root disk sd2...
Use (W)hole disk MBR, whole disk (G)PT, or [E]dit? gpt
Use [A]uto layout, (E)dit auto layout, or create [C]ustom layout? a
Which disk do you wish to initialize? done
Location of sets? disk
Is the disk partition already mounted? no
Which disk contains the install media? sd1 # USB stick with installer
Which sd1 partition has the install sets? a
Pathname to the sets? 7.6/amd64
Set name(s)? done # Default is to install all sets
Directory does not contain SHA256.sig. Continue without verification? yes
Location of sets? done
Exit to (S)hell, (H)alt, or (R)eboot? reboot

NOTE
During boot, when prompted for the encryption passphrase - and regardless of the keymap selected during install - enter the correct passphrase using the US QWERTY keymap.

Upon success, boot resumes....

OpenBSD/amd64 (foobox.home) (ttyC0)

login: root
Password:

Welcome to OpenBSD!

Initial Configuration

Check mail

Run the mail(1) program:

mail

Enter more 1 to read the first message. Quit mail by entering q.

Afterboot

afterboot(8) has a list of things to check after the first boot. Run:

man afterboot

The first thing you may notice is that OpenBSD man pages are really good. They provide lots of details which usually include useful examples.

Connect to ethernet network

Ethernet should have been auto-configured during install and activated during boot.

netstart(8) configures network interfaces at boot using hostname.if(5) files, where .if is replaced by the type of card. Example: my Intel ethernet card uses the em(4) driver:

# cat /etc/hostname.em0
inet autoconf

Display what interfaces the system has detected and their parameters with ifconfig(8).

DNS resolution is controlled by the resolv.conf(5) file, which is managed by resolvd(8).

If any modifications are made to a network interface, either reboot or run the netstart(8) script:

sh /etc/netstart

More details: FAQ - Networking

Install firmware updates

Non-free firmware packages the system needs to fully function should have been downloaded and applied during installation. Verify that the system has all the latest updates by running fw_update(8):

fw_update

Install security updates

syspatch(8) can be used to upgrade any files in need of security or reliability fixes on the two most recent OpenBSD releases. This is the quickest and easiest method to get the base system up to date:

syspatch

As there are a number of updates over the life cycle of a release, automate the process of checking for updates by creating a cron(8) job that runs syspatch -c and mails the output to your user if any action is necessary.

Run crontab(5) to create the job:

crontab -e

Have all mail for root cron jobs be sent to user (example: foo):

MAILTO=foo

Example: Create a job that runs syspatch daily at 12:10:

10      12      *       *       *       /usr/sbin/syspatch -c

Save changes and exit.

Cron files are stored in /var/cron/tabs/[user] (in this instance, /var/cron/tabs/root) but should only be edited with crontab.

Allow designated users to run commands as root

A user account was created during the above install (example name: foo) and was assigned to the wheel group.

Use doas(1) to run root-level access commands - and allow members of wheel to do so by default - by creating doas.conf(5):

echo "permit persist keepenv :wheel" > /etc/doas.conf

Allow user foo to run root commands without a password:

echo "permit nopass keepenv foo" >> /etc/doas.conf

Log out as root, and re-login as your user and use doas to run any commands that require root privileges.

Users and groups

View user information with userinfo(8) (example: foo):

$ userinfo foo
login	foo
passwd	*
uid	1000
groups	foo wheel
change	NEVER
class	staff
gecos	foo
dir	/home/foo
shell	/bin/ksh
expire	NEVER

To permit powering off the system as a non-root user using shutdown(8), add the user to the _shutdown group with usermod(8):

$ doas usermod -G _shutdown foo

Logout and login again, then:

$ id
uid=1000(foo) gid=1000(foo) groups=1000(foo), 0(wheel), 118(_shutdown)

Forward root mail to user

When a user is created during install, mail intended for root is forwarded to that user as specified in the /root/.forward file.

Verify that mail is indeed being forwarded by using the mail command to send a test message to root:

$ mail root
Subject: Test forwarding
Is it working?

Press CTRL-d to exit and send message.

$ mail
Mail version 8.1.2 01/15/2001.  Type ? for help.
"/var/mail/foo": 1 message 1 new
>N  1 foo@foobox.home  Wed Apr  2 09:41   15/465   Test forwarding

It works!

Package management

Package management is one area where the differences between the Linux philosophy and the BSD philosophy about how to build a system becomes apparent.

Linux is an operating system kernel. Developers take this kernel and combine it with various independent software projects in a collection of packages that is released as a Linux distribution (Ubuntu, Debian, Fedora, etc.).

In contrast, each of the BSDs develop their own kernel and combine it with system components that are developed together "in-house" and released as a whole. The idea being that this approach leads to a more robust and tightly integrated core operating system. Third-party packages not included in the core may still be installed at the discretion of the user, with source code and binary packages provided from a "ports" repository.

Used as a server, OpenBSD provides a complete operating system that might not require any ports to be added after installation. Used as a desktop, you will probably want to install at least a few ports not included by default, such as a web browser (example: firefox).

Add packages with pkg_add(1):

pkg_add [package]

One of the first packages I like to install on any system is htop:

doas pkg_add htop

To search for any given package name, use the -Q flag of pkg_info(1).

Installed packages can be updated with:

doas pkg_add -u

To remove a package, use pkg_delete(1).

NOTE
Modified configuration files will not be removed.

Dependencies that are no longer needed can afterwards be removed with the -a flag:

pkg_delete -a

More details: FAQ - Package Management

Resources

You can like, share, or comment on this post on the Fediverse 💬

Thanks for reading! Read other posts?

» Next: Create SSH keys on Linux for passwordless logins to servers

« Previous: FOSS IN SPACE #8: HelioLinc3D