GJOURNAL(8)

🌸 gjournal(8) — from the System Manager's Manual 🌸

okay bestie, buckle up — this is the manual page for gjournal, the control utility for journaled devices. it's a little retro, a little powerful, and honestly kind of iconic once you get it. let's go 💅

---

✨ NAME ✨

gjournal — control utility for journaled devices 🎀

---

✨ SYNOPSIS ✨

gjournal label [-cfhv] [-s jsize] dataprov [jprov]
gjournal stop [-fv] name ...
gjournal sync [-v]
gjournal clear [-v] prov ...
gjournal dump prov ...
gjournal list
gjournal status
gjournal load
gjournal unload

---

🦋 DESCRIPTION 🦋

so, gjournal is the utility you use for journal configuration on a given GEOM provider. the journal and the data can live on the same provider or on two separate providers — your call, no pressure 🫶

this is block level journaling, not file-system-level journaling, which means everything gets logged. like, for file systems, it journals both data and metadata. the gjournal GEOM class can talk to file systems, which is what lets you use gjournal for file system journaling and to keep file systems in a consistent state. at this time, only UFS file system is supported — so that's the vibe check for now.

to configure journaling on the UFS file system using gjournal, you should first create a gjournal provider using the gjournal utility, then run newfs(8) or tunefs(8) on it with the -J flag, which instructs UFS to cooperate with the gjournal provider underneath. ✨

⚠️ there are important differences in how journaled UFS works. the most important one: sync(2) and fsync(2) system calls do not work as expected anymore. to make sure data is actually stored on the data provider, use the gjournal sync command after calling sync(2). seriously. don't skip it 😭

for the best performance possible, soft-updates should be disabled when gjournal is used. it's also safe and recommended to use the async mount(8) option 💖

when gjournal is configured on top of gmirror(8) or graid3(8) providers, it also keeps them in a consistent state, so automatic synchronization on power failure or system crash may be disabled on those providers. one less thing to worry about, slay 👑

the gjournal utility uses on-disk metadata, stored in the provider's last sector, to store all needed information. which could be a problem when an existing file system is converted to use gjournal — just, heads up 🫠

the first argument to gjournal indicates an action to be performed:

• label — configures gjournal on the given provider(s). if only one provider is given, both data and journal are stored on the same provider. if two providers are given, the first one will be used as the data provider and the second will be used as the journal provider. 💾

additional options include:

• -c — checksum journal records.
• -f — may be used to convert an existing file system to use gjournal, but only if the journal will be configured on a separate provider and if the last sector in the data provider is not used by the existing file system. if gjournal detects that the last sector is used, it will refuse to overwrite it and return an error. this behavior may be forced by using the -f flag, which will force gjournal to overwrite the last sector. > ⚠️ that's the "i know what i'm doing" flag, bestie — it overwrites.
• -h — hardcode provider names in metadata.
• -s jsize — specifies size of the journal if only one provider is used for both data and journal. the default is one gigabyte. size should be chosen based on the provider's load, and not on its size — recommended minimum is twice the size of the physical memory installed. it is not recommended to use gjournal for small file systems (e.g.: only few gigabytes big). 🍓

• clear — clear metadata on the given providers.
• stop — stop the given provider.

additional options include:

• -f — stop the given provider even if it is opened.

• sync — trigger journal switch and enforce sending data to the data provider. 🔥
• dump — dump metadata stored on the given providers.
• list — see geom(8).
• status — see geom(8).
• load — see geom(8).
• unload — see geom(8).

additional options include:

• -v — be more verbose. 🗣️

---

💜 EXIT STATUS 💜

exit status is 0 on success, and 1 if the command fails. simple as that ✨

---

🌈 EXAMPLES 🌈

create a gjournal based UFS file system and mount it — the classic little ritual:

gjournal load
gjournal label da0
newfs -J /dev/da0.journal
mount -o async /dev/da0.journal /mnt

configure journaling on an existing file system, but only if gjournal allows this (i.e., if the last sector is not already used by the file system) — note the || fallback, she's prepared 💅:

umount /dev/da0s1d
gjournal label da0s1d da0s1e && \
    tunefs -J enable -n disable da0s1d.journal && \
    mount -o async /dev/da0s1d.journal /mnt || \
    mount /dev/da0s1d /mnt

---

🧚 SYSCTLS 🧚

gjournal adds the sysctl level kern.geom.journal. the string and integer information available is detailed below. the changeable column shows whether a process with appropriate privilege may change the value. 👑

the top-level ones, in all their glory:

• debug — integer, changeable: yes
• switch_time — integer, changeable: yes
• force_switch — integer, changeable: yes
• parallel_flushes — integer, changeable: yes
• accept_immediately — integer, changeable: yes
• parallel_copies — integer, changeable: yes
• record_entries — integer, changeable: yes
• optimize — integer, changeable: yes

what they actually do, bestie:

• debug — setting a non-zero value enables debugging at various levels. debug level 1 will record actions at a journal level, relating to journal switches, metadata updates, etc. debug level 2 will record actions at a higher level, relating to the numbers of entries in journals, access requests, etc. debug level 3 will record verbose detail, including insertion of I/Os to the journal. 🔍
• switch_time — the maximum number of seconds a journal is allowed to remain open before switching to a new journal.
• force_switch — force a journal switch when the journal uses more than N% of the free journal space.
• parallel_flushes — the number of flush I/O requests to be sent in parallel when flushing the journal to the data provider.
• accept_immediately — the maximum number of I/O requests accepted at the same time.
• parallel_copies — the number of copy I/O requests to send in parallel.
• record_entries — the maximum number of record entries to allow in a single journal.
• optimize — controls whether entries in a journal will be optimized by combining overlapping I/Os into a single I/O and reordering the entries in a journal. this can be disabled by setting the sysctl to 0.

🍓 cache

the string and integer information available for the cache level is detailed below. the changeable column shows whether a process with appropriate privilege may change the value.

• used — integer, changeable: no
• limit — integer, changeable: yes
• divisor — integer, changeable: no
• switch — integer, changeable: yes
• misses — integer, changeable: yes
• alloc_failures — integer, changeable: yes

and the meanings:

• used — the number of bytes currently allocated to the cache.
• limit — the maximum number of bytes to be allocated to the cache.
• divisor — sets the cache size to be used as a proportion of kmem_size. a value of 2 (the default) will cause the cache size to be set to 1/2 of the kmem_size.
• switch — force a journal switch when this percentage of cache has been used.
• misses — the number of cache misses, when data has been read, but was not found in the cache.
• alloc_failures — the number of times memory failed to be allocated to the cache because the cache limit was hit.

⭐ stats

the string and integer information available for the statistics level is detailed below. the changeable column shows whether a process with appropriate privilege may change the value.

• skipped_bytes — integer, changeable: yes
• combined_ios — integer, changeable: yes
• switches — integer, changeable: yes
• wait_for_copy — integer, changeable: yes
• journal_full — integer, changeable: yes
• low_mem — integer, changeable: yes

the receipts 💀:

• skipped_bytes — the number of bytes skipped.
• combined_ios — the number of I/Os which were combined by journal optimization.
• switches — the number of journal switches.
• wait_for_copy — the number of times the journal switch process had to wait for the previous journal copy to complete.
• journal_full — the number of times the journal was almost full, forcing a journal switch.
• low_mem — the number of times the low_mem hook was called.

---

👀 SEE ALSO 👀

geom(4), geom(8), mount(8), newfs(8), tunefs(8), umount(8) — go read these too, iykyk 💖

---

🎀 HISTORY 🎀

the gjournal utility appeared in FreeBSD 7.0. a legend was born ✨

---

🫶 AUTHORS 🫶

Pawel Jakub Dawidek <pjd@FreeBSD.org> — ty for your service, king 👑

---

and that's the whole page, bestie! this one's from the Debian build, dated February 17, 2009 — vintage but still serving 💅✨ go journal something responsibly 🦋