Also available as slides
Puffy the fugu fish, OpenBSD 8.0 mascot, an inflated pufferfish with spikes

OpenBSD Jumpstart 8.0

A concise and practical guide for new OpenBSD users, from the first install to PF, packages and daily administration.

October 28th, 2026, proudly hosted by OpenBSD Amsterdam Follow @wesley974

History

Forked from NetBSD. Theo de Raadt is the founder and leader of the OpenBSD project. The source tree was imported into CVS on October 18, 1995.


Why Use OpenBSD?

UNIX-like

A clean, standards-compliant UNIX-like operating system built on decades of engineering rigor and correctness.

Security Focused

Security-focused operating system with unveil(2), pledge(2) and proactive code auditing.

OpenBSD In-House Tools

Get the latest version of OpenSSH, OpenSMTPD, OpenRSYNC, OpenNTPD, OpenIKED, OpenBGPD, rpki-client, LibreSSL, mandoc

PF Packet Filter

Get the latest PF (Packet Filter) features. Also get softraid(4), carp(4), httpd(8), relayd(8), vmd(8)

Thorough FAQ

A comprehensive and well-maintained FAQ covering everything from installation to advanced configuration.

Cryptography

Full Cryptography support integrated in the base system. No compromises on encryption.


OpenBSD Use Cases

Firewall(PF)
Router(networking)
Mailserver(OpenSMTPD)
Webserver(httpd)
Hypervisor(vmd)
VPN(iked, wg)
NAS(softraid)
Desktop(Gnome, KDE Plasma...)

OpenBSD Innovations

Software & Ideas

Software and ideas developed or maintained by the OpenBSD project: openbsd.org/innovations.html

Version Numbers

  • Semiannual release cycle
  • New release is incremented by 0.1

OpenBSD Flavors

-release

Shipped every six months

-stable

-release plus patches (support for 7.9 & 8.0)

-current

Active development branch


CVS Repository & Manual Pages

CVS Repository

Choose your repository at: openbsd.org/anoncvs.html

CVSweb

Browse the source tree in your browser and read each file's revision history: cvsweb.openbsd.org

Manual Pages

# How to read a man page, for example foo(5) ?
man 5 foo

Or view it on your browser at: man.openbsd.org

Supported Hardware

Platforms: openbsd.org/plat.html

Real-world dmesgs: NYC*BUG dmesgd


Installation & Auto-Install

Installation

Really simple, ready in 5 minutes (KISS). Most of the time, pressing Enter at each question gives a good default install.

Get more information: openbsd.org/faq/faq4.html

Auto-Install

For a full unattended install/upgrade process, you can easily use autoinstall(8).


Networking Configuration

Configure and manage network interfaces, routing, and wireless connections on OpenBSD.

Configuration Files

FilePurpose
/etc/mynameDefault hostname
/etc/mygateDefault gateway
/etc/hostsKnown hosts on the network
/etc/resolv.confResolver (DNS), maintained by resolvd(8)
/etc/hostname.ifConfiguration for each network interface, for example: /etc/hostname.bge0

Read: myname(5), mygate(5), hostname.if(5), resolv.conf(5), resolvd(8), hosts(5)

Networking Commands

# Display the current configuration of network interfaces
ifconfig

# Set DHCP for 're0' interface, on the fly
ifconfig re0 inet autoconf

# Perform network (re)initialisation
sh /etc/netstart
Your interface name depends on your hardware. Check ifconfig output and read the relevant man page (e.g. man iwx, man bge).

Networking (Set at Startup)

Example 1: Static IP for re0

inet 192.168.0.58 255.255.255.0
With a static address, set the default gateway in /etc/mygate.

Example 2: DHCP for bge0

inet autoconf

Example 3: Configure Wireless

# First, see a list of available wireless networks:
ifconfig iwx0 scan
nwid ACCESS_POINT_NAME wpakey THE_SECRET_KEY
inet autoconf

# Or, for multiple access points
join AT_HOME wpakey THE_SECRET_KEY
join AT_WORK wpakey THE_SECRET_KEY
inet autoconf
After editing a hostname.if file, apply it to the running system with sh /etc/netstart re0 (use your own interface name).

Routing

# Show the routing table (ipv4)
route -n show -inet

# Show the routing table (ipv6)
route -n show -inet6

# Delete all gateway entries from the routing table
route -n flush
Caution: On a server you reach through a router, route -n flush also removes the default route, and your SSH session goes with it.

Read: route(8)


Packet Filter (PF)

OpenBSD's powerful firewall system: PF commands, rulesets, and troubleshooting.

Useful Commands

# Disable PF (removes all filtering)
pfctl -d

# Check the rules, always before loading them
pfctl -nf /etc/pf.conf

# Enable PF and load the rules
pfctl -ef /etc/pf.conf

# Just load the rules (apply changes)
pfctl -f /etc/pf.conf

# View the loaded rules
pfctl -s rules

Read: pfctl(8)

PF Ruleset Sample

# Protect a laptop (allow only ping/ssh from anywhere, IPv4 only)
# SSH protected by source limiter

set skip on lo

source limiter "ssh-protect" id 1 \
        entries 10000 limit 3 rate 5/60

block log all
pass in on egress inet proto icmp all icmp-type echoreq
pass in on egress inet proto tcp from any to any port ssh \
        source limiter "ssh-protect"
pass out

Read: pf.conf(5)

tcpdump

# Watch PF logs
tcpdump -nettti pflog0

# Watch traffic on egress (no DNS resolution)
tcpdump -n -i egress

# Filter by host / by port
tcpdump -n host 192.168.1.100
tcpdump -n port 22

# Watch DNS queries
tcpdump -n udp port 53

# Save capture to file / read it back
tcpdump -w capture.pcap -i egress
tcpdump -r capture.pcap

Read: tcpdump(8)

PF User's Guide


User & Group Management

User Management

# Manually
user [add|del|info|mod] foobar

# Add a user and create the home directory
user add -m foobar

# Add users interactively
adduser

# Remove users interactively
rmuser

Read: adduser(8), rmuser(8), user(8)

Group Management

File: /etc/group

group [add|del|info|mod] foobar
Members in wheel group can use su(1) to become root.

Read: group(8), group(5), rmgroup(8)

doas(1): Replaces sudo in Base System

# Permit the user 'marc' to reboot the box
permit nopass marc as root cmd /sbin/reboot
# Check the file syntax
doas -C /etc/doas.conf

# As marc, check the rule for this command (prints: permit nopass)
doas -C /etc/doas.conf /sbin/reboot

# Marc can now reboot the box
$ doas /sbin/reboot

Read: doas(1), doas.conf(5)


Package Installation & Management

Package Installation

# By default, it already contains an OpenBSD mirror server URL
https://cdn.openbsd.org/pub/OpenBSD
# Search for packages
pkg_info -Q foobar

# For example, to install Squid
pkg_add squid

# Update packages
pkg_add -u
Look in /usr/local/share/doc/pkg-readmes for extra documentation.

Read: pkg_info(1), pkg_add(1), installurl(5)

Package Management

Query & Inspect

# List packages installed
pkg_info

# List files installed by a package
pkg_info -L foobar

# View install-message for a specific package
pkg_info -M foobar

Read: pkg_info(1), packages(7)

Delete & Clean

# Delete a Package
pkg_delete foobar

# Show unused dependencies
pkg_delete -an

# Delete unused dependencies
pkg_delete -a

# Delete all except 'nginx' (read the output, then rerun without -n)
pkg_delete -nX nginx

Read: pkg_delete(1)

Install Non-Free Firmware Packages

fw_update
Firmware is downloaded from release-specific directories at: firmware.openbsd.org/firmware

Read: fw_update(8)


Managing Daemons & Services

rcctl: Service Control

File: /etc/rc.conf.local

rcctl [enable|disable|start|stop|reload|restart] foobar

# For example, to start the apmd(8) daemon for CPU scaling, you might do
rcctl enable apmd
rcctl set apmd flags -A
rcctl start apmd

Read: rcctl(8), rc.conf(8), rc.conf.local(8)

What's Enabled?

rcctl ls on

Read: rcctl(8)

Running Scripts at Startup

File: /etc/rc.local

Read: rc(8), rc.firsttime(8), rc.local(8), rc.securelevel(8)


Web Hosting (HTTPS)

httpd(8) serves your site and acme-client(1) gets a free Let's Encrypt certificate. Both are in the base system, nothing to install.

Step by Step

# 1. Port 80 server only in /etc/httpd.conf (sample below)
rcctl enable httpd
rcctl start httpd

# 2. Get the certificate (replace example.com first)
cp /etc/examples/acme-client.conf /etc/
acme-client -v example.com

# 3. Add the tls server, test, reload
httpd -n && rcctl reload httpd

# 4. Renew automatically, in root's crontab
~ * * * * acme-client example.com && rcctl reload httpd

Read: httpd(8), httpd.conf(5), acme-client(1), acme-client.conf(5)

httpd.conf Sample

server "example.com" {
    listen on * port 80
    location "/.well-known/acme-challenge/*" {
        root "/acme"
        request strip 2
    }
    location "*" {
        block return 301 "https://$HTTP_HOST$REQUEST_URI"
    }
}

server "example.com" {
    listen on * tls port 443
    tls certificate "/etc/ssl/example.com.fullchain.pem"
    tls key "/etc/ssl/private/example.com.key"
}

Site files go in /var/www/htdocs. Read: httpd.conf(5)

httpd Headers

# Inside a server block

# Response headers ("always" adds them to 4xx/5xx errors too)
header set "X-Content-Type-Options" "nosniff" always
header set "X-Frame-Options" "DENY" always

# Refuse requests on a header (AI crawlers, scanners),
# but a User-Agent is easy to fake
header block "User-Agent" "*GPTBot*" 403
header block "User-Agent" "*ClaudeBot*" 403
header drop "User-Agent" "*WPScan*"
New in 8.0: httpd sets its own headers, no relayd needed for that.

Read: httpd.conf(5)


Virtual Machines (vmm)

vmm(4) is the hypervisor in the base system: vmd(8) runs the virtual machines, vmctl(8) controls them.

# Check CPU support, get vmm-firmware, enable the hypervisor
dmesg | egrep '(VMX/EPT|SVM/RVI)'
fw_update
rcctl enable vmd
rcctl start vmd

# Create a disk, boot install80.iso (2 VCPUs, local network)
vmctl create -s 20G disk.qcow2
vmctl start -m 1G -p 2 -L -i 1 -r install80.iso -d disk.qcow2 myvm

# List VMs, attach the console (leave with ~.), stop
vmctl show
vmctl console myvm
vmctl stop myvm
New in 8.0: up to 64 VCPUs per VM with -p (default: 1).

Read: vmm(4), vmd(8), vmctl(8), vm.conf(5)


Updating & Upgrading OpenBSD

Updating OpenBSD (-stable)

Any security or reliability fixes can be found at:
openbsd.org/errata.html

Errata patches are generated for the last two releases (7.9, 8.0).

Tools for Updating (-stable)

Use syspatch(8) to update your kernel and userland. Binary patches are generated for the last two releases only, on amd64, arm64 and i386.

And pkg_add -u to update packages.

Upgrading OpenBSD

One release at a time. To upgrade 7.8 to 8.0, follow: upgrade79.html
and then
upgrade80.html

sysupgrade(8) upgrades OpenBSD to the next release or a new snapshot.

List Obsolete Files

pkg_add sysclean

sysclean only lists. It removes nothing. Review the output, then delete what you no longer need.


OpenBSD Filesystem

OpenBSD uses FFS2 (Enhanced Fast File System) by default.

Read: newfs(8), hier(7)

Key Directories

DirectoryDescription
/Root directory
/homeUser home directories
/rootDefault home directory for the superuser
/mntA temporary mount point
/etcSystem configuration files and scripts
/etc/examplesExample configuration files for base system daemons
/etc/skel(dot) files for new accounts
/etc/signifyKey files used for signify(1)
/tmpCleaned after a reboot
/var/tmpSymbolic link to the system /tmp
/var/logLog files
/var/runpid, socket files, utmp, dmesg.boot
/var/dbDatabase files
/var/wwwchroot directory for httpd(8)
/var/www/htdocsWeb repository for httpd(8)
/usr/localThird-party software goes here
/usr/srcBSD and/or local source files

OpenBSD Kernels

FileRole
/bsdThe kernel itself, loaded into memory at boot. At each boot, KARL (Kernel Address Randomized Link) relinks a new /bsd in random order for the next boot, so every boot runs a unique kernel.
/obsdPrevious kernel, saved when you build and install a kernel yourself (release(8)). If the new kernel fails to boot, start the previous one from the boot(8) prompt with boot /obsd.
/bsd.spKernel executable for single processor machines.
/bsd.mpKernel executable for multiprocessor machines.
/bsd.rdInstallation kernel. Its built-in RAM disk holds tools that run without an external file system, so it is useful for system maintenance too.
On a multiprocessor machine, the installer renames /bsd to /bsd.sp, then /bsd.mp to /bsd.

Kernel Troubleshooting

config(8) can enable, disable or change devices in a kernel binary, with no recompile. The same editor is available at boot: type boot -c at the prompt, see boot_config(8).

Caution: These edits are lost on upgrade and block kernel relinking. Keep them in bsd.re-config(5) instead.

System Tuning & Maintenance

System Tuning

Laptop Lid Action (sysctl)

machdep.lidaction=0do nothing
machdep.lidaction=1suspend (deep sleep)
machdep.lidaction=2hibernate (memory saved to swap, then power off)
Make it permanent in /etc/sysctl.conf, see /etc/examples/sysctl.conf for more machdep variables.

Read: acpibtn(4), sysctl.conf(5), sysctl(8)

System Maintenance

CommandDescription
doas pkg_check -FChecks that there are no other random objects under /usr/local
doas dmesg -sReview rc(8) system startup messages
ldd foobarList dynamic object dependencies
df -hSee disk usage
top -s .1Check load (cpu/mem)
resetReset your terminal when it gets messed up by control sequences
rcctl ls onWhat is enabled on your system
doas rcctl ls startedWhat is running on your system

Read: pkg_check(8), dmesg(8), ldd(1), ld.so(1), df(1), top(1), reset(1), rcctl(8)

ktrace/kdump Sample Usage

ktrace -f ping.out \
    ping -c 3 openbsd.org
trace the process
kdump -f ping.outinterprets the data from ktrace into a human readable format

Read: ktrace(1), kdump(1)


Useful Packages

PackagePurpose
screenfetchDisplay system information in the terminal
w3mText-based web browser
noiceMinimalistic file browser
pstreeList processes as a tree
testdiskScan and repair disk partitions

Install any of them with pkg_add, for example pkg_add w3m.


Presentations, Papers & Getting Help

Presentations & Papers

openbsd.org/events.html

Getting More Help

You can manage your OpenBSD mailing list membership at lists.openbsd.org.

OpenBSD VPS Hosting

It's time to create your own OpenBSD VM!


Bonus Content

Join us on Telegram!
(Nice people, I promise.)

Merci.

Like what you just learned? Donate to OpenBSD