# How to Configure Volume Journaling in Apple Container: Ordered, Writeback, and Journal Modes Explained

> Configure Apple Container volume journaling using ordered, writeback, and journal modes. Learn how each mode optimizes performance and durability for your ext4 volumes.

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

---

**Use the `--opt journal=<mode>[:<size>]` flag when creating a volume to set the ext4 journaling mode to `ordered`, `writeback`, or `journal`, where `ordered` provides metadata journaling with data ordering, `writeback` offers metadata-only journaling for speed, and `journal` enables full data journaling for maximum durability.**

The Apple Container framework allows you to configure volume journaling through the container CLI, providing fine-grained control over filesystem durability and performance. Each volume is backed by an ext4 image that supports three distinct journaling configurations, enabling you to optimize for crash consistency or I/O throughput based on your workload requirements.

## Understanding the Three Journaling Modes

Container volumes utilize ext4 images with configurable journaling policies. The three modes differ in what they record and the ordering guarantees they provide.

### Ordered Mode (Metadata with Data Ordering)

**Ordered mode** journals metadata only, but enforces that data is flushed to disk before its corresponding metadata is committed to the journal. This provides safe default kernel behavior and serves as a balanced option for most workloads where data loss on unexpected shutdown must be avoided.

### Writeback Mode (Metadata Only)

**Writeback mode** also journals metadata exclusively, but allows data to be written after its metadata has been committed. This eliminates ordering guarantees to provide the fastest write path, making it suitable for temporary or disposable data where speed is critical and occasional corruption is acceptable.

### Journal Mode (Full Data Journaling)

**Journal mode** records both metadata and data in the journal, providing the highest consistency guarantees. Every write is journaled before reaching the main filesystem, making this mode ideal for databases and workloads requiring maximal durability, though it incurs significant extra I/O overhead.

## How to Configure Volume Journaling at Creation

You configure volume journaling by passing the `--opt journal=<mode>[:<size>]` parameter to the `container volume create` command. The optional `:<size>` component (e.g., `64m`) forces a specific journal size; if omitted, the kernel selects a default size.

Create volumes with specific journaling configurations:

```bash

# 1️⃣ Ordered mode (default safe behavior)

container volume create --opt journal=ordered myOrderedVol

# 2️⃣ Writeback mode – fastest, no ordering guarantees

container volume create --opt journal=writeback:64m myWritebackVol

# 3️⃣ Full data journaling – safest, higher write amplification

container volume create --opt journal=journal --opt size=10g myJournalVol

```

Verify the configuration using the inspect command:

```bash
container volume inspect myJournalVol

# → JSON includes "journal": {"defaultMode":"journal","size":...}

```

## How the Journaling Configuration Is Processed

According to the Apple Container source code, the journaling mode is set once at volume creation through a specific chain of operations in the `ContainerAPIService` and `ContainerizationEXT4` modules.

### Parsing in VolumesService

When you execute `container volume create`, the CLI parses `--opt journal=...` into a driver-options dictionary passed to `VolumesService.create`. Inside [`Sources/Services/ContainerAPIService/Server/Volumes/VolumesService.swift`](https://github.com/apple/container/blob/main/Sources/Services/ContainerAPIService/Server/Volumes/VolumesService.swift), the helper `parseJournalConfig(_:)` (at line 269) splits the string on `:` and maps the first token to `EXT4.JournalConfig.JournalMode`:

```swift
switch modeString {
case "writeback": mode = .writeback
case "ordered":   mode = .ordered
case "journal":   mode = .journal
default: throw VolumeError.storageError(...)
}

```

If a size component exists, the method parses it using `Measurement.parse` and converts the value to bytes, yielding a `UInt64?` size parameter.

### Image Formatting

The resulting `EXT4.JournalConfig` object is passed to the `EXT4.Formatter` when `createVolumeImage` (line 293) executes. The formatter, implemented in [`Sources/ContainerizationEXT4/Formatter.swift`](https://github.com/apple/container/blob/main/Sources/ContainerizationEXT4/Formatter.swift), applies the configuration to the ext4 superblock, setting the block size and journaling policy accordingly.

### Metadata Persistence

The configuration is serialized into the volume's [`entity.json`](https://github.com/apple/container/blob/main/entity.json) metadata file. Subsequent calls to `container volume inspect` read this file to display the current journal mode and size, confirming that the setting persists for the volume's lifetime but cannot be modified without recreation.

## Summary

- **Three modes available**: `ordered` (metadata with data ordering), `writeback` (metadata only, fastest), and `journal` (full data journaling, safest).
- **CLI syntax**: Use `--opt journal=<mode>[:<size>]` during volume creation to configure the ext4 journaling behavior.
- **Implementation**: The `parseJournalConfig` function in [`VolumesService.swift`](https://github.com/apple/container/blob/main/VolumesService.swift) validates the mode, while [`Formatter.swift`](https://github.com/apple/container/blob/main/Formatter.swift) in the `ContainerizationEXT4` module applies the settings during image creation.
- **Immutable**: Journaling mode is set at creation and stored in [`entity.json`](https://github.com/apple/container/blob/main/entity.json); it cannot be changed on existing volumes.

## Frequently Asked Questions

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

If you omit the `--opt journal` flag, the system does not explicitly set a mode in the volume configuration, allowing the ext4 filesystem to use its kernel defaults. However, for explicit crash consistency, Apple recommends using `ordered` mode, which provides metadata journaling with data ordering guarantees.

### Can I change the journaling mode on an existing volume?

No, you cannot change the journaling mode on an existing volume. According to the implementation in [`VolumesService.swift`](https://github.com/apple/container/blob/main/VolumesService.swift), the `EXT4.JournalConfig` is applied only during the initial volume image creation via `createVolumeImage`. To use a different journaling mode, you must create a new volume with the desired `--opt journal` setting and migrate your data.

### How do I verify the current journaling configuration of a volume?

Run `container volume inspect <volume-name>` to view the volume metadata. The output JSON includes a `"journal"` field containing the `defaultMode` and `size` values, reflecting the configuration stored in the volume's [`entity.json`](https://github.com/apple/container/blob/main/entity.json) file during creation.

### What is the performance impact of using journal mode versus writeback?

**Journal mode** incurs the highest write amplification because every data block is written twice—first to the journal and then to the main filesystem—effectively halving sequential write throughput for large files. **Writeback mode** provides the fastest performance by eliminating ordering constraints and writing metadata only, but risks data corruption on system crashes. **Ordered mode** strikes a balance, typically reducing performance by 10-20% compared to writeback while preventing metadata inconsistencies.