Installing OpenBSD

Synopsis #

This chapter describes preparing installation media, selecting a disk layout, installing file sets, and completing initial system setup.

Obtaining Installation Media #

Official OpenBSD installation images are distributed via the OpenBSD mirror network. The master list of mirrors is maintained at:

Choose a mirror close to your geographic location for best performance. The installation sets for the current release are found under:

/pub/OpenBSD/8.0/ARCH/

Replace ARCH with your hardware architecture (e.g., amd64, arm64, i386).

For example, the amd64 directory for OpenBSD 8.0 is:

https://cdn.openbsd.org/pub/OpenBSD/8.0/amd64/

Installation Images #

Common installation images include:

  • install80.img - USB install image (recommended for most users).
  • install80.iso - ISO image for CD/DVD media.
  • miniroot80.img - small disk image without file sets; network boot uses architecture-specific boot files.

Downloading via Command Line #

On an OpenBSD system, use ftp(1) :

ftp https://cdn.openbsd.org/pub/OpenBSD/8.0/amd64/install80.img
ftp https://cdn.openbsd.org/pub/OpenBSD/8.0/amd64/SHA256.sig

On Linux or macOS, alternatives include curl(1) or wget(1):

curl -O https://cdn.openbsd.org/pub/OpenBSD/8.0/amd64/install80.img
wget https://cdn.openbsd.org/pub/OpenBSD/8.0/amd64/SHA256.sig

Always fetch the corresponding SHA256.sig file, which contains a signed list of release-file checksums.

Verifying Signatures #

Verification ensures the image has not been tampered with. Use signify(1) with the release public key (already installed on OpenBSD systems in /etc/signify/):

signify -C -p /etc/signify/openbsd-80-base.pub -x SHA256.sig install80.img

On non-OpenBSD systems, download the correct public key from https://ftp.openbsd.org/pub/OpenBSD/ under the release directory (e.g., openbsd-80-base.pub) and verify against it.

A successful verification prints OK. If it fails, do not use the image.

Writing the Installation Image to USB #

The downloaded .img file must be written raw to a USB stick. Writing to the wrong disk will destroy existing data, so carefully identify the correct device before proceeding.

Identifying the Target Disk #

On OpenBSD, use dmesg(8) immediately after inserting the USB stick:

dmesg | tail

Example output:

sd6 at scsibus3 targ 1 lun 0: <Generic, Flash Disk, 8.07> removable
sd6: 30528MB, 512 bytes/sector, 62537728 sectors

This shows the device is sd6. Always use the raw device (rsd6c) when writing with dd(1) .

On Linux, check with lsblk(8):

lsblk

Example output:

NAME   MAJ:MIN RM  SIZE RO TYPE MOUNTPOINT
sda      8:0    0 477G  0 disk
├─sda1   8:1    0 512M  0 part /boot
├─sda2   8:2    0 476G  0 part /
sdb      8:16   1 29.3G  0 disk
└─sdb1   8:17   1 29.3G  0 part /media/usb

Here the USB stick is /dev/sdb. Unmount any partitions before writing.

On macOS, use diskutil(8):

diskutil list

Example output:

/dev/disk2 (external, physical):
   #:                       TYPE NAME           SIZE       IDENTIFIER
   0:     FDisk_partition_scheme             *31.9 GB    disk2
   1:                 DOS_FAT_32 UNTITLED     31.9 GB    disk2s1

The correct device is /dev/disk2. For raw writes, use /dev/rdisk2.

Writing on OpenBSD #

doas dd if=install80.img of=/dev/rsd6c bs=1m

Writing on Linux #

sudo dd if=install80.img of=/dev/sdX bs=1M status=progress conv=fsync

Replace /dev/sdX with the target USB disk (e.g., /dev/sdb).

Writing on macOS #

diskutil unmountDisk /dev/disk2
sudo dd if=install80.img of=/dev/rdisk2 bs=1m
sync

Graphical Options #

If a graphical tool is preferred, the following applications can directly write .img files:

Pre-Installation Tasks #

Minimum Requirements #

Choose memory and disk space for the intended workload. The walkthrough uses 2 GiB of RAM and a 32 GiB disk. Review the filesystem sizes proposed by the installer; free space assigned to one filesystem cannot be used by another.

Backup and Preparation #

Make full backups if the target system contains valuable data or if it will be used in a multiboot configuration. Backups should be stored externally.

Information to Gather #

  • Hostname
  • Time zone
  • Root password
  • User account details
  • Static IP configuration (if not using DHCP)
  • Disk layout and encryption choices

Firmware Setup #

  • Disable Secure Boot in UEFI
  • Enable UEFI or BIOS boot depending on your hardware
  • Set USB or CD/DVD drive as the first boot device

Running the Installation #

Boot the system from the prepared USB stick. At the installer prompt:

(I)nstall, (U)pgrade, (A)utoinstall or (S)hell?

Choose I to begin a fresh installation.

Installer Prompts (Annotated) #

Terminal and System Setup #

  • Terminal type? Default vt220 works for most systems.

Networking #

  • System hostname? Example: myrouter

  • Which network interface to configure? Select interface or type done.

  • IPv4 address? autoconf, none, or a static address. The autoconf choice obtains IPv4 configuration through DHCP.

  • IPv6 address? autoconf, none, or static.

  • Default IPv4 route? Only if static IP. Example: 192.168.1.1.

  • DNS domain name? / DNS nameservers? Usually provided via DHCP.

Users and Access #

  • Password for root? Input is hidden.

  • Start sshd(8) ? Choose yes if remote login is needed.

  • Setup a user? Recommended. Enter lowercase username.

  • Allow root ssh login? Choose no or prohibit-password for security.

Timezone #

  • What timezone are you in? Use ? to list options.

Disk Setup #

  • Which disk is the root disk? Example: sd0.

  • Partitioning scheme? GPT is preferred on UEFI systems.

  • Use (A)uto layout, (E)dit auto layout, or create (C)ustom layout? Review the displayed sizes and mount points before accepting the automatic layout. It separates filesystems such as /, /var, /tmp, /usr, and /home. Adjust the layout when the intended workload requires different allocations. Leave free space in /usr for updates and kernel relinking. On small disks, edit the automatic layout if /usr has too little space. Check the final installer output for errors even if it displays a completion message.

Encryption #

On supported installation paths, the installer offers root-disk encryption before partition layout, using a passphrase or key disk. The basic walkthrough below accepts the unencrypted default. See Full-Disk Encryption for an encrypted installation.

File Sets #

  • Location of sets? Usually http.

  • Mirror and path? Example:

    cdn.openbsd.org
pub/OpenBSD/8.0/amd64/

  • Select/deselect sets Default is fine. Use -game* to skip games.

At the end:

CONGRATULATIONS! Your OpenBSD install has been successfully completed!
Exit to (S)hell, (H)alt or (R)eboot? [reboot]

Installation Walkthrough #

This recording demonstrates OpenBSD 7.9. Use the OpenBSD 8.0 media and file-set names shown above for a new installation.

Installing OpenBSD 7.9
Screenshots
OpenBSD installer showing the installation menu and terminal type prompt.
The installer shows defaults in brackets. Press Enter to accept a default.
Automatic disk layout for a 32 GiB disk, including separate root, usr, var, and home filesystems.
Review the filesystem sizes before accepting the layout.
Selected OpenBSD installation sets and a verified download signature.
The installer checks the signature before installing the selected sets.
Installer reporting successful kernel preparation and installation, with the reboot prompt.
Kernel preparation is complete. Restart to boot the installed system.

Read the terminal transcript

Post-Installation Configuration #

After reboot, follow these steps:

Logging In and Configuring doas #

Log in on the console as root for initial administration. A regular account created by the installer belongs to the wheel group, but doas(1) requires a policy in /etc/doas.conf before it can grant access.

As root, create /etc/doas.conf with the following policy when members of wheel should administer the system:

permit persist :wheel

Protect and validate the file from the existing root shell:

chmod 600 /etc/doas.conf
  # Restrict access to the policy file
doas -C /etc/doas.conf
  # Check policy syntax

Then log in as the regular user and verify access:

doas id

The command prompts for that user’s password and should report uid=0(root). Use the regular account for routine work.

Confirm the Update Mirror #

Check installurl(5) before fetching patches or packages:

doas cat /etc/installurl

A local server used only for installation sets may not provide patches or packages. If necessary, select a complete mirror:

printf '%s\n' "https://cdn.openbsd.org/pub/OpenBSD" | doas tee /etc/installurl > /dev/null

Apply Binary Patches #

Run syspatch(8) :

doas syspatch

Reboot when requested to load a patched kernel.

Package Updates #

Update installed packages with pkg_add(1) :

doas pkg_add -u

A fresh installation may have no third-party packages to update. Configuration merging with sysmerge is part of a release upgrade , rather than a required step after every binary patch.

Configure Timezone #

The installer selects the timezone. To change it later, update the /etc/localtime symbolic link to a file under /usr/share/zoneinfo, as described in afterboot(8) :

doas ln -fs /usr/share/zoneinfo/Europe/Amsterdam /etc/localtime
  # Select the timezone
doas date
  # Check the displayed local time

Enable Services #

Use rcctl(8) :

doas rcctl enable ntpd
doas rcctl start ntpd
doas rcctl ls on

Review System Logs #

doas tail -n 60 /var/log/messages
doas sysctl hw.sensors
doas ifconfig -A

Configure Remote Access #

Ensure sshd(8) is enabled and copy keys:

mkdir -p ~/.ssh
chmod 700 ~/.ssh
touch ~/.ssh/authorized_keys
chmod 600 ~/.ssh/authorized_keys

Add the intended public key to ~/.ssh/authorized_keys and test a separate login before closing the existing session.

Verify Disk Encryption #

A passphrase-based CRYPTO installation prompts at boot; a keydisk-based installation needs its keydisk. Swap encryption is automatic.

doas bioctl softraid0

UEFI Boot Notes #

On amd64, OpenBSD installs its UEFI bootloader at:

/EFI/BOOT/BOOTX64.EFI

Most firmware detects it automatically. Secure Boot must be disabled.

Custom Installation with siteXX.tgz #

OpenBSD supports an additional file set named site80.tgz which is extracted after all base system sets. Use it to add local configuration, scripts, and files to new installations.

When It Is Applied #

Select the custom set during installation or include it in the unattended set selection. For HTTP installation, list it in the set directory’s index.txt. Selected site sets are extracted after the base sets.

Supported names include a generic archive:

  • site80.tgz

and a host-specific variant:

  • site80-HOSTNAME.tgz

Typical Contents #

Examples:

etc/rc.conf.local
etc/pf.conf
etc/hostname.em0
root/.ssh/authorized_keys
install.site
usr/local/bin/custom-script

Example Creation #

doas tar -C /path/to/custom/root -czphf site80.tgz .

Ensure file modes and ownership are preserved. An executable /install.site is run in a chroot rooted at the installed system near the end of installation.

Example install.site #

#!/bin/sh
echo "Provisioning $(hostname)" >> /var/log/install.log
pkg_add rsync htop
rcctl enable sshd

This enables post-install automation.

Example Use Cases #

Network Configuration #

etc/hostname.em0

inet 192.168.1.10 255.255.255.0
up

Firewall Rules #

etc/pf.conf

set block-policy drop
block all
pass in on egress proto tcp to port ssh

Enable Services #

etc/rc.conf.local

sshd_flags=
ntpd_flags=
smtpd_flags=

Add User SSH Keys #

root/.ssh/authorized_keys

ssh-ed25519 AAAA... root@admin

Pre-Configure Package Mirror #

etc/installurl

https://cdn.openbsd.org/pub/OpenBSD

Unattended Installation #

OpenBSD can install itself automatically using a configuration file and optional custom file sets.

How It Works #

  1. Choose (A)utoinstall at the installer menu. Network boot can select unattended installation automatically.
  2. The installer discovers the response-file server through DHCP and fetches answers over HTTP. If discovery fails, it asks for a URL or local path.
  3. Custom sets and an executable install.site can supply additional configuration.

A response file embedded as /auto_install.conf in bsd.rd is another supported method. Simply copying install.conf to an arbitrary USB filesystem does not enable automatic discovery.

Example install.conf #

System hostname = server1
Password for root = *************
Setup a user = alice
Password for user = REPLACE_WITH_ENCRYPTED_PASSWORD
Public ssh key for user = ssh-ed25519 AAAA... alice@laptop
Location of sets = http
HTTP Server = cdn.openbsd.org
Set name(s) = -game* +xbase* +xshare*

Replace the key and password placeholders before use. Generate the password hash with encrypt(1); the account needs a usable local password for an authenticated doas policy. Thirteen asterisks disable password login. Preserve console recovery and provision the administrative policy explicitly.

Deployment Options #

  • PXE boot + DHCP: serve bsd.rd and install.conf automatically.
  • Local response file: provide its actual accessible path when prompted, or embed /auto_install.conf in the ramdisk using the documented autoinstall(8) method.

This allows fully automatic provisioning of many machines with identical or host-specific settings.

Stateless Setup #

The standard bsd.rd image is a limited installation and recovery environment. It does not become a general-purpose stateless system by adding siteXX.tgz, and it does not automatically extract that set and run install.site at every boot.

Characteristics #

A diskless installation requires a separately configured boot and root-filesystem arrangement. See diskless(8) and the platform’s network-boot instructions.

Building a Stateless Environment #

Plan the root filesystem, networking, writable storage, and service startup explicitly. The custom-set mechanism described above applies to installation into a target root filesystem.

Considerations #

Recovery-media utilities are a limited subset of the installed system. Do not assume applications, package management, or a normal multiuser environment are available in bsd.rd.

Troubleshooting #

  • Review dmesg(8) and installer output.
  • Confirm UEFI/BIOS settings.
  • Always consult the INSTALL.arch file in the release directory
Report a bug