Implementing UFS Journaling on a Desktop PC

3.1 Reserving Space for Journaling

A typical desktop machine usually has one hard disk that stores both the OS and user data. Arguably, the default partitioning scheme selected by sysinstall is more or less suitable: A desktop machine does not need a large /var partition, while /usr is allocated the bulk of the disk space, since user data and a lot of packages are installed into its subdirectories.

The default partitioning (the one obtained by pressing A at the FreeBSD partition editor, called Disklabel) does not leave any unallocated space. Each partition that will be journaled, requires another partition for the journal. Since the /usr partition is the largest, it makes sense to shrink this partition slightly, to obtain the space required for journaling.

In our example, an 80 GB disk is used. The following screenshot shows the default partitions created by Disklabel during installation:

If this is more or less what you need, it is very easy to adjust for journaling. Simply use the arrow keys to move the highlight to the /usr partition and press D to delete it.

Now, move the highlight to the disk name at the top of the screen and press C to create a new partition for /usr. This new partition should be smaller by 1 GB (if you intend to journal /usr only), or 2 GB (if you intend to journal both /usr and /var). From the pop-up that appears, opt to create a file system, and type /usr as the mount point.

To keep things as easy going as possible, we are going to use sysinstall to create the partitions required for journaling. However, during installation, sysinstall insists on asking a mount point for each partition you create. At this point, you do not have any mount points for the partitions that will hold the journals, and in reality you do not even need them. These are not partitions that we are ever going to mount somewhere.

To avoid these problems with sysinstall, we are going to create the journal partitions as swap space. Swap is never mounted, and sysinstall has no problem creating as many swap partitions as needed. After the first reboot, /etc/fstab will have to be edited, and the extra swap space entries removed.

To create the swap, again use the arrow keys to move the highlight to the top of Disklabel screen, so that the disk name itself is highlighted. Then press N, enter the desired size (1024M), and select “swap space” from the pop-up menu that appears. Repeat for every journal you wish to create. In our example, we create two partitions to provide for the journals of /usr and /var. The final result is shown in the following screenshot:

When you have completed creating the partitions, we suggest you write down the partition names, and mount points, so you can easily refer to this information during the configuration phase. This will help alleviate mistakes that may damage your installation. The following table shows our notes for the sample configuration:

Continue the installation as you would normally do. We would however suggest you postpone installation of third party software (packages) until you have completely setup journaling.

---

3.2 Booting for the first time

Your system will come up normally, but you will need to edit /etc/fstab and remove the extra swap partitions you created for the journals. Normally, the swap partition you will actually use is the one with the “b” suffix (i.e. ad0s1b in our example). Remove all other swap space entries and reboot so that FreeBSD will stop using them.

When the system comes up again, we will be ready to configure journaling.

4.1 Executing gjournal

Having prepared all the required partitions, it is quite easy to configure journaling. We will need to switch to single user mode, so login as root and type:

# shutdown now

Press Enter to get the default shell. We will need to unmount the partitions that will be journaled, in our example /usr and /var:

# umount /usr /var

Load the module required for journaling:

# gjournal load

Now, use your notes to determine which partition will be used for each journal. In our example, /usr is ad0s1f and its journal will be ad0s1g, while /var is ad0s1d and will be journaled to ad0s1h. The following commands are required:

# gjournal label ad0s1f ad0s1g

GEOM_JOURNAL: Journal 2948326772: ad0s1f contains data.
GEOM_JOURNAL: Journal 2948326772: ad0s1g contains journal.

# gjournal label ad0s1d ad0s1h

GEOM_JOURNAL: Journal 3193218002: ad0s1d contains data.
GEOM_JOURNAL: Journal 3193218002: ad0s1h contains journal.

At this point, two new devices are created, namely ad0s1d.journal and ad0s1f.journal. These represent the /var and /usr partitions we have to mount. Before mounting, we must however set the journal flag on them and clear the Soft Updates flag:

# tunefs -J enable -n disable ad0s1d.journal

tunefs: gjournal set
tunefs: soft updates cleared

# tunefs -J enable -n disable ad0s1f.journal

tunefs: gjournal set
tunefs: soft updates cleared

Now, mount the new devices manually at their respective places (note that we can now use the async mount option):

# mount -o async /dev/ad0s1d.journal /var
# mount -o async /dev/ad0s1f.journal /usr

Edit /etc/fstab and update the entries for /usr and /var:

/dev/ad0s1f.journal     /usr            ufs     rw,async      2       2
/dev/ad0s1d.journal     /var            ufs     rw,async      2       2

Finally, edit /boot/loader.conf and add the following line so the gjournal(8) module is loaded at every boot:

geom_journal_load="YES"

Congratulations! Your system is now set for journaling. You can either type exit to return to multi-user mode, or reboot to test your configuration (recommended). During the boot you will see messages like the following:

ad0: 76293MB XEC XE800JD-00HBC0 08.02D08 at ata0-master SATA150
GEOM_JOURNAL: Journal 2948326772: ad0s1g contains journal.
GEOM_JOURNAL: Journal 3193218002: ad0s1h contains journal.
GEOM_JOURNAL: Journal 3193218002: ad0s1d contains data.
GEOM_JOURNAL: Journal ad0s1d clean.
GEOM_JOURNAL: Journal 2948326772: ad0s1f contains data.
GEOM_JOURNAL: Journal ad0s1f clean.

After an unclean shutdown, the messages will vary slightly, i.e.:

GEOM_JOURNAL: Journal ad0s1d consistent.

This usually means that gjournal(8) used the information in the journal provider to return the file system to a consistent state.

---

4.2 Journaling Newly Created Partitions

While the above procedure is necessary for journaling partitions that already contain data, journaling an empty partition is somewhat easier, since both the data and the journal provider can be stored in the same partition. For example, assume a new disk was installed, and a new partition /dev/ad1s1d was created. Creating the journal would be as simple as:

# gjournal label ad1s1d

The journal size will be 1 GB by default. You may adjust it by using the -s option. The value can be given in bytes, or appended by K, M or G to denote Kilobytes, Megabytes or Gigabytes respectively. Note that gjournal will not allow you to create unsuitably small journal sizes.

For example, to create a 2 GB journal, you could use the following command:

# gjournal label -s 2G ad1s1d

You can then create a file system on your new partition, and enable journaling using the -J option:

# newfs -J /dev/ad1s1d.journal

---

4.3 Building Journaling into Your Custom Kernel

If you do not wish to load geom_journal as a module, you can build its functions right into your kernel. Edit your custom kernel configuration file, and make sure it includes these two lines:

options UFS_GJOURNAL # Note: This is already in GENERIC

options GEOM_JOURNAL # You will have to add this one

Rebuild and reinstall your kernel following the relevant instructions in the FreeBSD Handbook.

Do not forget to remove the relevant “load” entry from /boot/loader.conf if you have previously used it.