Implementing UFS Journaling on a Desktop PC

Soft Updates is the default UFS consistency mechanism in FreeBSD. When combined with journaling, it provides metadata journaling within the file system itself.

Advantages of Soft Updates with journaling include:

From tunefs(8):

This mechanism is suitable for nearly all UFS-based systems and is the default recommendation.

GEOM journaling operates at the block level, below the file system. It journals all block writes, including both metadata and file data.

Key characteristics of GEOM journaling:

Because of these differences, GEOM journaling is not recommended for general-purpose desktop or server use.

Soft Updates with journaling record file system metadata changes in a journal stored inside the file system itself, implemented as a hidden file named .sujournal in the root of the file system. In the event of a crash or power failure, pending metadata operations are replayed from the journal, allowing the file system to be mounted quickly without a full consistency check.

This form of journaling applies to file system metadata only. File data integrity remains the responsibility of applications.

The file system must be unmounted or mounted read-only before changing journaling settings.

No additional configuration is required. Standard mount options may be used.

A default journal size is selected automatically when journaling is enabled. In most cases, the default size is sufficient and does not require adjustment.

If necessary, the journal size in bytes can be specified explicitly using the -S option to tunefs(8):

Journal size tuning is rarely required and should be considered only for file systems with unusually high metadata update rates.

The journaling status of a UFS file system using Soft Updates can be verified with tunefs(8) or dumpfs(8).

To display the current file system settings, run:

Look for the following indicators in the output:

Alternatively, dumpfs(8) can be used to inspect the file system superblock:

These commands are read-only and do not modify file system state.

Although journaling dramatically reduces recovery time after a crash, it does not eliminate the need for periodic full file system checks.

This functionality is provided by loading the geom_journal.ko module into the kernel (or building it into a custom kernel) and using the gjournal command to configure the file systems. In general, you would like to journal large file systems, like /usr. You will need however (see the following section) to reserve some free disk space.

GEOM journaling is implemented by the geom_journal kernel module and is configured using the gjournal(8) utility. It provides block-level journaling below the file system layer and requires explicit cooperation from UFS.

When GEOM journaling is used, some disk space is needed to keep the journal itself. The provider that contains the file system data is referred to as the data provider, while the provider that stores the journal is referred to as the journal provider.

When journaling an existing (non-empty) file system, the data and journal providers must be separate. When journaling a new, empty file system, a single provider may be used to store both data and journal information. In both cases, gjournal(8) combines the data and journal providers to create a new journaled provider, which is then mounted by the file system. For example:

The amount of disk space required for the journal depends primarily on the write workload of the file system rather than on the size of the data provider. Systems with sustained or bursty write activity require larger journals to avoid excessive journal switching or write throttling.

From the man page gjournal(8):

An undersized journal may result in degraded performance or forced journal switches under heavy write load.

For more information about journaling, please read the manual page of gjournal(8).

This section describes optional installation-time preparation for systems that are configured to use GEOM journaling. The goal is to reserve disk space for journal providers that will later be associated with the /usr and /var file systems.

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:

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.

GEOM journaling status can be verified by inspecting active GEOM providers.

To list all active GEOM journal devices, run:

Or to view a summary of journal status:

Journaled file systems are identified by device names ending in .journal. The presence of these providers indicates that GEOM journaling is active.

Additional information about GEOM device stacking can be obtained with:

Alternatively, dumpfs(8) can be used to inspect the file system superblock:

On modern FreeBSD systems, kernel panics caused solely by an undersized GEOM journal are rare.

Under sustained or burst-heavy write workloads, an undersized journal typically results in write throttling or temporary I/O stalls while the journal is flushed to the data provider. A kernel panic may occur only in exceptional cases, usually in combination with additional problems such as I/O errors or resource exhaustion, where continuing operation could risk file system integrity.

If panics are observed during heavy write activity, increasing the size of the journal provider for the affected file system is recommended.

You either forgot (or misspelled) the entry in /boot/loader.conf, or there are errors in your /etc/fstab file. These are usually easy to fix. During system startup, when the boot process stops and prompts for single-user mode (for example after a failed mount or fsck error), press Enter to get to the default single user shell. Then locate the root of the problem:

Ensure that the following line exists and is spelled correctly:

If the geom_journal_load entry is missing or misspelled, the journaled devices are never created. Load the module manually, mount all partitions, and continue with multi-user boot:

If, on the other hand, this entry is correct, have a look at /etc/fstab. You will probably find a misspelled or missing entry. In this case, mount all remaining partitions by hand and continue with the multi-user boot.

Sure. Use the following procedure, which reverses the changes. The partitions you created for the journal providers can then be used for other purposes, if you so wish.

Login as root and switch to single user mode:

Unmount the journaled partitions:

Synchronize the journals:

Stop the journaling providers:

Next step should be done with unloaded gjournal kernel module. If the following command fails:

ensure that the following line exists in /boot/loader.conf and is spelled correctly:

Reboot your desktop without gjournal kernel module:

Boot into single-user mode again. Clear the journaling metadata from all the devices used:

Clear the file system journaling flag, and restore the Soft Updates flags:

Remount the old devices by hand:

Edit /etc/fstab and restore it to its original state:

Finally, edit /boot/loader.conf, remove the entry that loads the geom_journal module (or re-enable it if gjournal is still required for other partitions), and reboot.

To boot the system without GEOM journaling, prevent the journal module from loading during startup.

Comment out or remove the following line from /boot/loader.conf and reboot:

After booting without GEOM journaling, journaled devices (*.journal) will not be created. File Systems must be mounted using their original (non-journaled) providers, or mounted manually as needed for recovery or maintenance.

This method does not modify on-disk journal metadata and can be safely used for troubleshooting.

No. A GEOM journal cannot be resized in place after it has been created.

The journal size is fixed at the time the journal is labeled. To change the journal size, GEOM journaling must be removed and reconfigured with a new journal provider of the desired size. For file systems containing data, this requires unmounting the file system and recreating the journal using appropriately sized providers, as described earlier in this article.

Plan journal sizes conservatively to accommodate peak write activity, as resizing requires reinitialization of the journal configuration.

After an unclean shutdown or power failure, GEOM journaling and Soft Updates with journaling replay the pending journal records during the next boot to return the file system to a consistent state.

If the journal replay completes successfully, the file system is mounted normally and no full file system check is required. Journal replay typically takes only a few seconds and depends on the amount of recent write activity rather than the size of the file system.

A full file system check may still be required in rare cases, such as when underlying storage errors are detected or the journal itself is inconsistent.

GEOM journaling and Soft Updates with journaling interact with fsck_ffs(8) in different ways, reflecting their different integration levels in the FreeBSD storage stack.

For GEOM journaling, crash recovery is performed by the GEOM framework itself. During system startup, the geom_journal class detects journal metadata and replays any pending journal records while the provider is being tasted by GEOM, before the journaled device becomes visible to higher layers of the system. If journal replay completes successfully, the file system is returned to a consistent state and the UFS superblock is updated to indicate that no file system check is required. When fsck_ffs(8) is later invoked during boot, it reads this state from the superblock and skips the file system check.

For Soft Updates with journaling, recovery is initiated by fsck_ffs(8) itself. During the file system check phase at boot time, fsck_ffs(8) detects that the files ystem supports Soft Updates with journaling and invokes the journal replay logic. If journal replay reports that the file system is consistent, fsck_ffs(8) terminates early without performing a full check. If journal replay cannot complete successfully, a traditional file system check is performed.

As a result, the recovery path during system startup depends on the journaling mechanism in use, as illustrated by the following boot sequence:

fsck_ffs(8) is still used when journal replay cannot be completed, when underlying storage errors are detected, or during periodic manual or scheduled file system checks. GEOM journaling reduces recovery time after crashes but does not replace fsck_ffs(8) entirely.

In GEOM, the same underlying storage can be exposed through multiple provider names at the same time. For example, a partition may be visible both under its disk-based name (e.g. vtbd0p7) and under a GPT label (e.g. /dev/gpt/labelname). These are different GEOM providers referring to the same physical storage.

When gjournal stop or gjournal clear is executed on one provider name, the GEOM framework may immediately detect the journal metadata again through another provider name during the tasting process. As a result, the journal is re-attached automatically, and attempts to clear its metadata fail with an "Operation not permitted" error.

It is technically possible to suppress this behavior by disabling GEOM tasting or by preventing the creation of alternative provider names, but doing so is strongly discouraged. Such changes may negatively affect other GEOM classes and system components that rely on normal provider discovery.

For this reason, the recommended and safe procedure is to unload the geom_journal module entirely before removing journal metadata, as described earlier in this article. With the module unloaded, no tasting occurs and the journal cannot be re-attached, allowing gjournal clear to complete successfully.

Yes. GEOM journaling can be used on the root file system, but it requires additional care during system configuration.

The GEOM journal module must be loaded early during the boot process so that the journaled root device is available before the root file system is mounted. Misconfiguration may prevent the system from booting normally, so this setup is generally recommended only for experienced users who fully understand the boot sequence and recovery procedures.

For these reasons, GEOM journaling is more commonly applied to non-root file systems such as /usr and /var.

GEOM journaling introduces additional write I/O because all write operations are first recorded in the journal before being committed to the data provider. This results in increased write latency and higher overall write amplification compared to non-journaled file systems.

Read performance is typically unaffected. The performance impact is most noticeable on write-heavy workloads and depends on journal size, placement, and the speed of the underlying storage. Using a sufficiently sized journal and fast storage for the journal provider minimizes performance penalties.

Yes. GEOM journaling can be stacked with other GEOM classes.

When used together, GEOM journaling typically operates on top of providers created by other GEOM classes such as gmirror(8) or graid3(8). The order of stacking is important and should follow the documented layering requirements of the involved GEOM classes.

GEOM journaling maintains file system consistency across the stacked providers, but it does not replace redundancy or error detection provided by other GEOM classes.

No. GEOM journaling and Soft Updates must not be enabled at the same time on the same file system.

GEOM journaling requires exclusive control over write ordering and consistency guarantees. If Soft Updates are enabled together with GEOM journaling, the file system may behave unpredictably and data integrity cannot be guaranteed.

When using GEOM journaling, Soft Updates must be disabled on the affected file system, as described earlier in this article.

Both Soft Updates and Soft Updates with Journaling are designed to maintain file system consistency, but they use different mechanisms and behave differently after a system crash.

Soft Updates ensure consistency by carefully ordering metadata writes in memory so that only safe states are written to disk. If a crash occurs, any metadata updates that have not yet been written are simply lost, leaving the file system in a consistent but possibly older state. However, resource accounting may be temporarily inaccurate, and a full fsck_ffs(8) run is required to reclaim unused blocks and inodes.

Soft Updates with Journaling build on top of Soft Updates by adding a metadata journal stored within the file system. Metadata changes are first recorded in the journal and are replayed automatically during the next boot after an unclean shutdown. This allows the file system to be restored to a consistent state quickly, usually without requiring a full fsck_ffs(8) run.

In short, Soft Updates provide consistency without a journal, while Soft Updates with Journaling add fast and automatic recovery after crashes at the cost of additional disk space and minor performance overhead.