© 2011 Warren Block

Last updated 2011-06-04

Available in HTML or PDF. Links to all my articles here. Created with AsciiDoc.

Warning Make a full backup first.

What Are Labels?

FreeBSD device names are often dynamic. The same hard drive can show up as /dev/ad0 or /dev/ad4 or even /dev/da0, depending on several factors. Using these device names in /etc/fstab is prone to breakage. Put the drive on another connector, in another system, or in an external enclosure, and FreeBSD can’t boot because it can’t find the device listed in fstab.

Labels can be assigned to FreeBSD filesystems or devices, and will remain the same, regardless of the connection type or port. These labels can be used reliably in fstab.

Boot Single-User And Label Filesystems

This example assigns labels to a drive that was /dev/ad4 with FreeBSD on the first slice in a standard layout. Using part of the hostname or other identifying information in the label helps avoid the confusion of multiple drives with identical labels. The example computer is called aardvark, so the labels all start with aa.

# glabel label aaswap /dev/ad4s1b
# tunefs -L aarootfs /dev/ad4s1a
# tunefs -L aavarfs /dev/ad4s1d
# tunefs -L aatmpfs /dev/ad4s1e
# tunefs -L aausrfs /dev/ad4s1f

glabel(8) is used to label swap, which is just a FreeBSD partition without a filesystem. The label will appear in /dev/label when the drive is detected.

tunefs(8) is used to label UFS filesystems, and those labels will appear in /dev/ufs. tunefs will only label an unmounted or read-only filesystem, hence the boot into single-user mode. (Labeling a read-only filesystem seems weird until you realize that the label isn’t part of the filesystem.)

Warning Don’t be in a hurry. If you immediately mount / so you can edit /etc/fstab, the new label on / will go away. Reboot first, or disconnect and reconnect an external device.


Check that all of the labels were assigned correctly.

# ls /dev/label /dev/ufs

aarootfs        aatmpfs         aausrfs         aavarfs

Edit /etc/fstab to use the labels you created in the previous step.

# Device                Mountpoint      FStype  Options         Dump    Pass#
/dev/label/aaswap       none            swap    sw              0       0
/dev/ufs/aarootfs       /               ufs     rw              1       1
/dev/ufs/aatmpfs        /tmp            ufs     rw              2       2
/dev/ufs/aausrfs        /usr            ufs     rw              2       2
/dev/ufs/aavarfs        /var            ufs     rw              2       2

Reboot to make sure that everything is correct and the system comes up.


That’s it. The unchanging labels let FreeBSD find the swap partition and filesystems without caring about the device name or number.