FreeBSD Handbook
Prev | Chapter 19 GEOM: Modular Disk Transformation Framework | Next

# 19.6 Labeling Disk Devices

During system initialization, the FreeBSD kernel will create device nodes as devices are found. This method of probing for devices raises some issues, for instance what if a new disk device is added via USB? It is very likely that a flash device may be handed the device name of `da0` and the original `da0` shifted to `da1`. This will cause issues mounting file systems if they are listed in `/etc/fstab`, effectively, this may also prevent the system from booting.

One solution to this issue is to chain the SCSI devices in order so a new device added to the SCSI card will be issued unused device numbers. But what about USB devices which may replace the primary SCSI disk? This happens because USB devices are usually probed before the SCSI card. One solution is to only insert these devices after the system has been booted. Another method could be to use only a single ATA drive and never list the SCSI devices in `/etc/fstab`.

A better solution is available. By using the `glabel` utility, an administrator or user may label their disk devices and use these labels in `/etc/fstab`. Because `glabel` stores the label in the last sector of a given provider, the label will remain persistent across reboots. By using this label as a device, the file system may always be mounted regardless of what device node it is accessed through.

> Note: This goes without saying that a label be permanent. The `glabel` utility may be used to create both a transient and permanent label. Only the permanent label will remain consistent across reboots. See the glabel(8) manual page for more information on the differences between labels.

## 19.6.1 Label Types and Examples

There are two types of labels, a generic label and a file system label. Labels can be permanent or temporary. Permanent labels can be created with the tunefs(8) or newfs(8) commands. They will then be created in a sub-directory of `/dev`, which will be named according to their file system type. For example, UFS2 file system labels will be created in the `/dev/ufs` directory. Permanent labels can also be created with the `glabel label` command. These are not file system specific, and will be created in the `/dev/label` directory.

A temporary label will go away with the next reboot. These labels will be created in the `/dev/label` directory and are perfect for experimentation. A temporary label can be created using the `glabel create` command. For more information, please read the manual page of glabel(8).

To create a permanent label for a UFS2 file system without destroying any data, issue the following command:

    # tunefs -L home /dev/da3

> Warning: If the file system is full, this may cause data corruption; however, if the file system is full then the main goal should be removing stale files and not adding labels.

A label should now exist in `/dev/ufs` which may be added to `/etc/fstab`:

    /dev/ufs/home      /home            ufs     rw              2      2

> Note: The file system must not be mounted while attempting to run `tunefs`.

Now the file system may be mounted like normal:

    # mount /home

From this point on, so long as the `geom_label.ko` kernel module is loaded at boot with `/boot/loader.conf` or the `GEOM_LABEL` kernel option is present, the device node may change without any ill effect on the system.

File systems may also be created with a default label by using the `-L` flag with `newfs`. See the newfs(8) manual page for more information.

The following command can be used to destroy the label:

    # glabel destroy home

The following example shows how to label the partitions of a boot disk.

Example 19-1. Labeling Partitions on the Boot Disk

By permanently labeling the partitions on the boot disk, the system should be able to continue to boot normally, even if the disk is moved to another controller or transferred to a different system. For this example, it is assumed that a single ATA disk is used, which is currently recognized by the system as `ad0`. It is also assumed that the standard FreeBSD partition scheme is used, with `/`, `/var`, `/usr` and `/tmp` file systems, as well as a swap partition.

Reboot the system, and at the loader(8) prompt, press 4 to boot into single user mode. Then enter the following commands:

    # glabel label rootfs /dev/ad0s1a
    GEOM_LABEL: Label for provider /dev/ad0s1a is label/rootfs
    # glabel label var /dev/ad0s1d
    GEOM_LABEL: Label for provider /dev/ad0s1d is label/var
    # glabel label usr /dev/ad0s1f
    GEOM_LABEL: Label for provider /dev/ad0s1f is label/usr
    # glabel label tmp /dev/ad0s1e
    GEOM_LABEL: Label for provider /dev/ad0s1e is label/tmp
    # glabel label swap /dev/ad0s1b
    GEOM_LABEL: Label for provider /dev/ad0s1b is label/swap
    # exit

The system will continue with multi-user boot. After the boot completes, edit `/etc/fstab` and replace the conventional device names, with their respective labels. The final `/etc/fstab` file will look like the following:

    # Device                Mountpoint      FStype  Options         Dump    Pass#
    /dev/label/swap         none            swap    sw              0       0
    /dev/label/rootfs       /               ufs     rw              1       1
    /dev/label/tmp          /tmp            ufs     rw              2       2
    /dev/label/usr          /usr            ufs     rw              2       2
    /dev/label/var          /var            ufs     rw              2       2

The system can now be rebooted. If everything went well, it will come up normally and `mount` will show:

    # mount
    /dev/label/rootfs on / (ufs, local)
    devfs on /dev (devfs, local)
    /dev/label/tmp on /tmp (ufs, local, soft-updates)
    /dev/label/usr on /usr (ufs, local, soft-updates)
    /dev/label/var on /var (ufs, local, soft-updates)

Starting with FreeBSD 7.2, the glabel(8) class supports a new label type for UFS file systems, based on the unique file system id, `ufsid`. These labels may be found in the `/dev/ufsid` directory and are created automatically during system startup. It is possible to use `ufsid` labels to mount partitions using the `/etc/fstab` facility. Use the `glabel status` command to receive a list of file systems and their corresponding `ufsid` labels:

    % glabel status
                      Name  Status  Components
    ufsid/486b6fc38d330916     N/A  ad4s1d
    ufsid/486b6fc16926168e     N/A  ad4s1f

In the above example `ad4s1d` represents the `/var` file system, while `ad4s1f` represents the `/usr` file system. Using the `ufsid` values shown, these partitions may now be mounted with the following entries in `/etc/fstab`:

    /dev/ufsid/486b6fc38d330916        /var        ufs        rw        2      2
    /dev/ufsid/486b6fc16926168e        /usr        ufs        rw        2      2

Any partitions with `ufsid` labels can be mounted in this way, eliminating the need to create permanent labels for them manually, while still enjoying the benefits of device-name independent mounting.

Prev | Home | Next
GEOM Gate Network Devices | Up | UFS Journaling Through GEOM

This, and other documents, can be downloaded from ftp://ftp.FreeBSD.org/pub/FreeBSD/doc/.

For questions about FreeBSD, read the documentation before contacting <questions@FreeBSD.org>.
For questions about this documentation, e-mail <doc@FreeBSD.org>.