# How to Configure Volume Journaling Modes for Apple Containers: Ordered, Writeback, and Journal

> Master Apple container volume journaling modes ordered, writeback, and journal using the journal driver option. Optimize your container storage performance today.

- Repository: [Apple/container](https://github.com/apple/container)
- Tags: how-to-guide
- Published: 2026-06-29

---

**Apple Containers support three ext4 volume journaling modes—ordered, writeback, and journal—configured via the `--opt journal=<mode>[:<size>]` driver option when creating volumes.**

The `apple/container` repository provisions container volumes as ext4-formatted block-device images created on demand. When configuring volume journaling modes, you specify the desired consistency and performance trade-off through a driver option parsed by the server-side volume service.

## Understanding the Three Journaling Modes

Apple Containers store data on ext4-formatted block-device images. The journaling mode determines how the filesystem commits changes to disk, impacting both durability and performance.

### Ordered Mode

Journals only metadata while guaranteeing that **data is written to disk before its metadata is committed**. This mode provides a good balance between safety and performance and matches the Linux kernel's default ext4 behavior.

### Writeback Mode

Journals only metadata but does **not** guarantee data ordering relative to metadata commits. This mode offers the fastest write performance but provides the least data safety, making it suitable for temporary or cache-like workloads where speed outweighs durability concerns.

### Journal Mode (Full Data Journaling)

Journals both **metadata and data**, ensuring the highest level of data integrity. This mode causes the highest write amplification and is ideal for workloads requiring strict durability guarantees.

## Parsing Configuration in VolumesService.swift

In [`Sources/Services/ContainerAPIService/Server/Volumes/VolumesService.swift`](https://github.com/apple/container/blob/main/Sources/Services/ContainerAPIService/Server/Volumes/VolumesService.swift), the `parseJournalConfig(_:)` method handles the journal option string. The implementation splits the input on the colon character (`:`), mapping the first token to an `EXT4.JournalConfig.JournalMode` value.

If a size suffix is provided (e.g., `writeback:64m`), the substring after the colon is parsed by the generic `Measurement.parse` utility and converted to bytes. This produces an `EXT4.JournalConfig` containing both the explicit mode and the optional size.

The parsing logic appears at lines 269–288, where the server validates the mode and extracts any size parameter.

## Creating Volumes with Journal Options

The journal configuration is passed to the ext4 formatter when the volume image is created. At lines 290–299 in [`VolumesService.swift`](https://github.com/apple/container/blob/main/VolumesService.swift), the service instantiates:

```swift
let formatter = try EXT4.Formatter(
    FilePath(blockPath),
    blockSize: 4096,
    minDiskSize: sizeInBytes,
    journal: journal               // ← the parsed EXT4.JournalConfig
)

```

The CLI reference in [`docs/command-reference.md`](https://github.com/apple/container/blob/main/docs/command-reference.md) (lines 886–904) documents the syntax. Use the `--opt` flag with the `journal` key when running `container volume create`:

```bash

# Ordered mode (default kernel behavior)

container volume create --opt journal=ordered myvolume

# Writeback mode with 128 MiB journal

container volume create --opt journal=writeback:128m myvolume

# Full data journaling with 10 GiB volume

container volume create \
    --opt journal=journal \
    --opt size=10g \
    myvolume

```

## Architecture Flow

The journal configuration propagates through four distinct layers:

1. **CLI Parsing** – The `container` binary forwards driver options to the server component.
2. **Server Processing** – `VolumesService._create` extracts the `journal` key, invokes `parseJournalConfig`, and passes the result to `createVolumeImage`.
3. **EXT4 Formatting** – The `EXT4.Formatter` receives the `EXT4.JournalConfig` and constructs the on-disk journal with the requested mode and size.
4. **Volume Activation** – The resulting block-device image mounts into containers, obeying the selected journaling semantics.

Because the journal mode is part of the volume's immutable configuration, changing it later requires recreating the volume with the desired option.

## Summary

- Apple Containers use ext4-formatted block devices with configurable journaling modes.
- Three modes are available: **ordered** (balanced), **writeback** (fastest), and **journal** (safest).
- Configure modes using `--opt journal=<mode>[:<size>]` when creating volumes.
- The `VolumesService.parseJournalConfig(_:)` method in [`VolumesService.swift`](https://github.com/apple/container/blob/main/VolumesService.swift) handles parsing.
- Journal configuration is immutable; modify it only at volume creation time.

## Frequently Asked Questions

### What is the default journaling mode if I don't specify one?

If you omit the `--opt journal` flag, the ext4 formatter uses the kernel's default behavior, which corresponds to **ordered** mode. However, explicit configuration is recommended for production workloads to ensure predictable data safety guarantees.

### Can I change the journal mode of an existing volume?

No. According to the implementation in [`VolumesService.swift`](https://github.com/apple/container/blob/main/VolumesService.swift), the journal configuration is immutable after volume creation. To use a different mode, you must create a new volume with the desired `--opt journal` setting and migrate your data.

### How does the size parameter affect journal performance?

The optional size parameter (e.g., `writeback:64m`) specifies the journal file size in bytes. Larger journals allow more transactions to buffer before committing, which can improve throughput for write-heavy workloads but consumes more disk space. The `Measurement.parse` utility converts human-readable suffixes like `m` or `g` to bytes automatically.

### Where can I find the unit tests for journal parsing?

The parsing logic is validated in [`Tests/ContainerResourceTests/VolumeJournalConfigTests.swift`](https://github.com/apple/container/blob/main/Tests/ContainerResourceTests/VolumeJournalConfigTests.swift), while integration tests covering the CLI appear in [`Tests/CLITests/Subcommands/Volumes/TestCLIVolumes.swift`](https://github.com/apple/container/blob/main/Tests/CLITests/Subcommands/Volumes/TestCLIVolumes.swift). These suites verify that modes like `journal`, `ordered`, and `writeback` parse correctly with various size specifications.