OpenBSD FAQ - Disk Setup [FAQ Index]

Disks and Partitions

The details of setting up disks in OpenBSD vary between platforms, so you should read the instructions in your platform's INSTALL.<arch> file.

Drive Identification

On most platforms, OpenBSD handles mass storage with two drivers: The devices are numbered by the order in which they are detected at boot time, starting at zero. So, the first IDE-like disk will be wd0 and the third SCSI-like disk will be sd2. Note that OpenBSD will not necessarily number drives in the same order as your boot ROM.

Partitions and Filesystems

The term "partition" can mean two different things in OpenBSD: All OpenBSD platforms use the disklabel program as the primary way to manage filesystem partitions. On the platforms that use fdisk, one MBR partition is used to hold all of the OpenBSD filesystems. This partition can be sliced into 16 disklabel partitions, labeled a through p. A few labels are special: To create a new filesystem on a disklabel partition, use the newfs(8) command: 
# newfs sd2a
Thus, a device name plus a disklabel identify an OpenBSD filesystem. For example, the identifier sd2a refers to the filesystem on the a partition of the third sd device. Its device files would be /dev/sd2a for the block device and /dev/rsd2a for the raw (character) device. Remembering whether a rarely used command needs a block or a character device is difficult. Therefore, many commands make use of the opendev(3) function, which automatically expands sd0 to /dev/rsd0c or /dev/sd0c as appropriate.

Disklabel Unique Identifiers

Disks are identified by Disklabel Unique Identifiers (DUIDs) in the fstab(5) file by default. DUIDs are 16 hex digit random numbers that are generated when a disklabel is first created. They are managed by the diskmap(4) device. To display the DUIDs of all disks, do: 
$ sysctl hw.disknames
hw.disknames=wd0:bfb4775bb8397569,cd0:,wd1:56845c8da732ee7b,wd2:f18e359c8fa2522b
You can specify partitions on the disk by appending a period and the partition letter. For example, f18e359c8fa2522b.d is the d partition of the disk f18e359c8fa2522b and will always refer to the same chunk of storage, no matter what order the devices attached to the system, or what kind of interface it is attached to. If you put data on wd2d, then later remove wd1 from the system and reboot, your data is now on wd1d, as your old wd2 is now wd1. However, a drive's DUID won't change after boot.

Using fdisk

The fdisk(8) utility is used on some platforms (i386, amd64 and macppc) to create a partition recognized by the system boot ROM. Normally, only one OpenBSD fdisk partition will be placed on a disk and that partition will then be subdivided into disklabel partitions.

View your partition table with: 

# fdisk sd0
Disk: sd0       geometry: 553/255/63 [8883945 Sectors]
Offset: 0       Signature: 0xAA55
         Starting       Ending       LBA Info:
 #: id    C   H  S -    C   H  S [       start:      size   ]
------------------------------------------------------------------------
 0: 12    0   1  1 -    2 254 63 [          63:       48132 ] Compaq Diag.
 1: 00    0   0  0 -    0   0  0 [           0:           0 ] unused
 2: 00    0   0  0 -    0   0  0 [           0:           0 ] unused
*3: A6    3   0  1 -  552 254 63 [       48195:     8835750 ] OpenBSD
Here, the OpenBSD partition (id A6) is marked with a * to indicate that it is the bootable partition.

A totally blank disk will need to have the master boot record's boot code written to the disk before it can boot. Normally, all you need to do is: 

# fdisk -iy sd0
Alternatively, use the reinit or update commands in interactive mode.

The -e flag starts interactive editing mode: 

# fdisk -e sd0
Enter 'help' for information
fdisk: 1>
Beware that quit saves changes and exits the program, while exit exits without saving. This is the opposite of what many people are now used to in other environments. Note also that fdisk does not warn before saving the changes.

If your system has a maintenance or diagnostic partition, it is recommended that you leave it in place or install it before installing OpenBSD.

Disk Labels

Disk labels are used to manage OpenBSD filesystem partitions. They contain certain details about your disk, such as drive geometry and filesystem information, as described in depth in the disklabel(5) man page. Use the disklabel(8) command to edit the labels.

This can help overcome some architectures' disk partitioning limitations. For example, on i386, there are only four primary MBR partitions available. With disk labels, one of these primary partitions contains all your OpenBSD partitions, while the other three are still available for other operating systems.

On platforms using fdisk, you should leave the first logical track unused, both in disklabel and in fdisk. For this reason, the default is to start the first partition at block 64.

Don't put swap at the very beginning of your disk on sparc64. While Solaris often did that, OpenBSD requires the boot partition to be at the beginning of the disk.

Recovering Partitions After Deleting the Disk Label

If you have a damaged partition table, there are various things you can attempt to do to recover it.

A copy of the disklabel for each disk is saved in /var/backups as part of the daily system maintenance. Assuming you still have the /var partition, you can simply read the output, and put it back into disklabel with the -R flag.

In the event that you can no longer see that partition, there are two options: Fix enough of the disk so you can see it, or fix enough of the disk so that you can get your data off. The scan_ffs(8) utility will look through a disk to find partitions. You can use the information it finds to recreate the disklabel. If you just want /var back, you can recreate the partition for /var, then recover the backed up label and add the rest from that. The disklabel(8) utility will both update the kernel's understanding of the disklabel and attempt to write the label to disk. Therefore, even if the area of the disk containing the disklabel is unreadable, you will be able to mount until the next reboot.

The amd64 Boot Process

Details on the amd64 bootstrapping procedure are given in the boot_amd64(8) man page. The boot process is as follows:
  1. Master Boot Record (MBR) and GUID Partition Table (GPT). The fdisk(8) man page contains the details.
  2. Partition Boot Record (PBR). The first 512 bytes of the boot disk's OpenBSD partition contain the first stage boot loader biosboot(8). It is installed by the installboot(8) utility.
  3. Second stage boot loader /boot. The PBR loads the boot(8) program which has the task of locating and loading the kernel.
So, the very start of the boot process could look like this: 
Using drive 0, partition 3.                      <- MBR
Loading......                                    <- PBR
probing: pc0 com0 com1 mem[638K 1918M a20=on]    <- /boot
disk: hd0+ hd1+
>> OpenBSD/amd64 BOOT 3.33
boot>
booting hd0a:/bsd 4464500+838332 [58+204240+181750]=0x56cfd0
entry point at 0x100120

[ using 386464 bytes of bsd ELF symbol table ]
Copyright (c) 1982, 1986, 1989, 1991, 1993       <- Kernel
        The Regents of the University of California.  All rights reserved.

Root Partition Backup (/altroot)

OpenBSD provides an /altroot facility in the daily(8) scripts. If the environment variable ROOTBACKUP=1 is set in either /etc/daily.local or root's crontab(5), and a partition is specified in fstab(5) as mounting to /altroot with the mount options of xx, every night the entire contents of the root partition will be duplicated to the /altroot partition.

Assuming you want to back up your root partition to the partition specified by the DUID bfb4775bb8397569.a, add the following to /etc/fstab 

bfb4775bb8397569.a /altroot ffs xx 0 0
and set the appropriate environment variable in /etc/daily.local: 
# echo ROOTBACKUP=1 >>/etc/daily.local
As the /altroot process will capture your /etc directory, this will make sure any configuration changes there are updated daily. This is a "disk image" copy done with dd(1) not a file-by-file copy, so your /altroot partition should be at least the same size as your root partition. Generally, you will want your /altroot partition to be on a different disk that has been configured to be fully bootable should the primary disk fail.

Duplicating Filesystems

To duplicate everything under directory /SRC to directory /DST with dump(8) and restore(8), do: 
# cd /SRC && dump 0f - . | (cd /DST && restore -rf - )
or use tar(1): 
# cd /SRC && tar cf - . | (cd /DST && tar xpf - )

Disk Quotas

Quotas are used to place limits on the amount of disk space available to certain users and groups.

Use the keywords userquota and groupquota to mark each filesystem in fstab(5) on which you want to enforce quotas. By default, the files quota.user and quota.group will be created at the root of those filesystems. Here is an example /etc/fstab line: 

0123456789abcdef.k /home ffs rw,nodev,nosuid,userquota 1 2
To set the users' quotas, use edquota(8). For example, issue 
# edquota ericj
and edit the soft and hard limits: 
Quotas for user ericj:
/home: KBytes in use: 62, limits (soft = 1000000, hard = 1500000)
        inodes in use: 25, limits (soft = 0, hard = 0)
In this example, the soft limit is set to 1000000k, and the hard limit is set to 1500000k. No limits on the number of inodes will be enforced, since the corresponding soft and hard limits are set to 0. Users who exceed their soft limit are warned and are given a grace period to get their disk usage below their limits. Grace periods can be set by using the -t option on edquota(8). After the grace period is over, the soft limit is handled as a hard limit. This usually results in an allocation failure.

Use quotaon(8) to enable quotas: 

# quotaon -a
This will scan through fstab(5) and enable quotas on the filesystems with quota options. View quota statistics with quota(1).

Accessing Other Filesystems

Start with the mount(8) manual, which contains examples explaining how to mount some of the most commonly used filesystems. A partial list of supported filesystems and related commands can be obtained with: 
$ man -k -s 8 mount
Note that support may be limited to read-only operation.

Mounting Disk Images

To mount a disk image in OpenBSD you must configure a vnd(4) device. For example, if you have an ISO image located at /tmp/ISO.image, you would take the following steps to mount the image. 
# vnconfig vnd0 /tmp/ISO.image
# mount -t cd9660 /dev/vnd0c /mnt
Since this is an ISO 9660 image, as used by CDs and DVDs, you must specify type of cd9660 when mounting it.

To unmount the image and unconfigure the vnd(4) device, do: 

# umount /mnt
# vnconfig -u vnd0
For more information, refer to vnconfig(8) and mount(8).

Growing Disk Partitions

If an existing partition is followed by unallocated free space, you may increase its size using the growfs(8) utility. Make sure the partition is not currently mounted. Edit your partition table interactively with disklabel -E sd0 and modify the size of the partition using the m command. Adjust the filesystem to use the entire partition with growfs(8): 
# growfs sd0h
Before the partition can be mounted again, its integrity must be checked with fsck(8): 
# fsck /dev/sd0h

RAID and Disk Encryption

The bioctl(8) command manages both hardware and software RAID devices via the bio(4) layer. The softraid(4) subsystem allows combining several OpenBSD disklabel(8) partitions into a virtual sd(4) disk. This virtual disk is treated as any other disk.

Supported softraid disciplines include the following:

Level Description Bootable on
RAID0 striping ---
RAID1 mirroring amd64, arm64, i386, riscv64, sparc64
RAID1C mirroring with disk encryption amd64, arm64, riscv64, sparc64
RAID5 striping with floating parity ---
CONCAT concatenating with no redundancy ---
CRYPTO disk encryption amd64, arm64, i386, riscv64, sparc64

Disk setup may vary from platform to platform. Note that "stacking" softraid modes is not supported at this time.

Installing to a Mirror

This section covers installing OpenBSD to a mirrored pair of hard drives, and assumes familiarity with the installation process.

Before using the install script, you will drop to a shell and set up a softraid(4) device.

The install kernel only has a limited number of /dev entries on boot, so you will need to manually create the required disk devices for your softraid setup. For example, if you need to support three sd(4) devices, the following could be done from the shell prompt: 

Welcome to the OpenBSD/amd64 7.6 installation program.
(I)nstall, (U)pgrade, (A)utoinstall or (S)hell? s
# cd /dev
# sh MAKEDEV sd0 sd1 sd2
The installer would now have full support for the sd0, sd1 and sd2 devices. If the sets are to be installed from a USB drive, don't forget to take that device into account too.

Next, initialize the disks with fdisk(8) and create RAID partitions with disklabel(8).

If you're booting from MBR, do: 

# fdisk -iy sd0
# fdisk -iy sd1
If you use GPT for UEFI booting, do: 
# fdisk -gy -b 532480 sd0
# fdisk -gy -b 532480 sd1
Create the partition layout on the first device: 
# disklabel -E sd0
Label editor (enter '?' for help at any prompt)
sd0> a a
offset: [64]
size: [39825135] *
FS type: [4.2BSD] RAID
sd0*> w
sd0> q
No label changes.
Copy the partition layout to the second device: 
# disklabel sd0 > layout
# disklabel -R sd1 layout
# rm layout
Assemble the mirror with the bioctl(8) command: 
# bioctl -c 1 -l sd0a,sd1a softraid0
scsibus1 at softraid0: 1 targets
sd2 at scsibus2 targ 0 lun 0: <OPENBSD, SR RAID 1, 005> SCSI2 0/direct fixed
sd2: 10244MB, 512 bytes/sec, 20980362 sec total
This shows that we now have a new SCSI bus and a new disk, sd2. This volume will be automatically detected and assembled when the system boots.

Even if you create multiple RAID arrays, the device name will always be softraid0.

Because the new device probably has a lot of garbage where you expect a master boot record and disklabel, zeroing the first chunk of it is highly recommended. Be very careful with this command; issuing it on the wrong device could lead to a very bad day. This assumes that the new softraid device was created as sd2. 

# dd if=/dev/zero of=/dev/rsd2c bs=1m count=1
You are now ready to install OpenBSD on your system. Create all the partitions on your new softraid disk (sd2 in the example here) that should be there, rather than on sd0 or sd1 (the non-RAID disks).

To check on the status of the mirror, issue the following command: 

# bioctl sd2
A nightly cron job to check the status might be a good idea.

Rebuilding a Mirror

When a drive failure happens, you will replace the failed drive, create the RAID and other disklabel partitions, then rebuild the mirror. Assuming your RAID volume is sd2 and you are replacing the failed device with sd1m, the following commands should work: 
# bioctl -R /dev/sd1m sd2
This can also be performed in single user mode or from the ramdisk kernel.

Full Disk Encryption

Much like RAID, full disk encryption in OpenBSD is handled by the softraid(4) subsystem and bioctl(8) command. The OpenBSD installer provides a way to install to a fully encrypted disk, using a passphrase to unlock it.

As an alternative to using a passphrase, it's also possible to use a key stored on a separate device (e.g. a USB stick) to encrypt disks.

At the (S)hell prompt in the installer, initialize the keydisk with fdisk(8), then use disklabel(8) to create a 1 MB RAID partition for the key data. If your keydisk is sd1 and the drive you want to encrypt is sd0, the output will look something like this: 

# bioctl -c C -k sd1a -l sd0a softraid0
sd2 at scsibus3 targ 1 lun 0: <OPENBSD, SR CRYPTO, 005> SCSI2 0/direct fixed
sd2: 19445MB, 512 bytes/sector, 39824607 sectors
softraid0: CRYPTO volume attached as sd2
You won't be prompted to enter a passphrase because you used a keydisk instead. The keydisk must be inserted at startup time.

You can back up and restore your keydisk using dd(1): 

# dd bs=8192 skip=1 if=/dev/rsd1a of=backup-keydisk.img
# dd bs=8192 seek=1 if=backup-keydisk.img of=/dev/rsd1a

Encrypting External Disks

This section explains how to set up a cryptographic softraid volume for an external USB drive. An outline of the steps is as follows: A quick example runthrough of the steps follows, with sd3 being the USB drive. 
# dd if=/dev/urandom of=/dev/rsd3c bs=1m
# fdisk -iy sd3
# disklabel -E sd3 # make an "a" partition of type RAID
# bioctl -c C -l sd3a softraid0
New passphrase:
Re-type passphrase:
softraid0: CRYPTO volume attached as sd4
# dd if=/dev/zero of=/dev/rsd4c bs=1m count=1
# fdisk -iy sd4
# disklabel -E sd4 # make an "i" partition
# newfs sd4i
# mkdir -p /mnt/secretstuff
# mount /dev/sd4i /mnt/secretstuff
# mv somefile /mnt/secretstuff/
# umount /mnt/secretstuff
# bioctl -d sd4
The same bioctl(8) command used to create the volume can be used to attach it later on.