sdjournal is a pure Rust systemd journal reader and query engine. It reads *.journal files directly and does not depend on libsystemd or invoke journalctl (tests may use journalctl for golden comparisons).
- Pure Rust, with no
libsystemddependency - Bounded, corruption-resistant parsing for production use
- Stable merge ordering, cursor checkpoints, and bounded shared live subscriptions
- Low-memory mode with bounded open files and optional mmap disablement
- Optional mmap, compression backends, tracing, Tokio integration, and FSS verification
- Minimum supported Rust version (MSRV): 1.100.0, using Rust 2024
- Target OS: Linux
- Other Unix hosts and Windows can parse user-supplied
*.journalfiles;Journal::open_default()is Linux-only - Targets outside Unix/Windows are rejected at compile time: native positional file reads are required for concurrent queries
- CI coverage includes Ubuntu 22.04 (systemd 249.x), Ubuntu 24.04 (systemd 255.x), and macOS offline checks
cargo add sdjournal- Default:
mmap,lz4,zstd - Optional:
xz: enable XZ decompressiontracing: emit diagnostics viatracing(caller installs a subscriber)tokio: provides an async live-subscription adapterverify-seal: verify Forward Secure Sealing (TAG/FSS) with a systemd verification key
For constrained processes, set JournalConfig::max_open_files to a small value and
JournalConfig::mmap_policy to MmapPolicy::Never.
use sdjournal::Journal;
let journal = Journal::open_default()?;
let mut q = journal.query();
q.match_exact("_SYSTEMD_UNIT", b"sshd.service");
q.since_realtime(0);
for item in q.iter()? {
let entry = item?;
if let Some(msg) = entry.get("MESSAGE") {
println!("{}", String::from_utf8_lossy(msg));
}
}
# Ok::<(), sdjournal::SdJournalError>(())An end-to-end example that persists the last cursor and resumes via after_cursor is in:
examples/checkpoint_follow.rs
Run it on Linux:
cargo run --example checkpoint_follow -- sshd.service /var/tmp/sdjournal.cursorCursors now use native systemd text (s=...;i=...;b=...;m=...;t=...;x=...). The retired
SJ1: format is rejected. Replace old checkpoints with a new native cursor or choose an explicit
replay start before resuming. Cursor IDs accept 32 hex digits, canonical UUIDs, or UUID URNs;
arbitrarily placed hyphens are rejected.
Partial cursors now require both s and i, or a realtime t field. Boot-relative b/m
cursors without either are rejected instead of producing incorrect results across boots.
Keep the full cursor returned by an entry; b/m/t partial cursors remain supported.
EntryRef::cursor()andEntryOwned::cursor()returnCursordirectly. The same applies toLiveEntry::cursor()through dereferencing. Remove?,expect, orunwrapfrom these calls.Journal::seek_cursor()returnsJournalQuerydirectly. Cursor resolution and read errors are still reported by query execution throughiter()orcollect_owned().- Both historical and live OR-group closures use the public
sdjournal::OrGroupBuilder. The oldLiveOrGroupBuildername has been removed. LiveFilterhas been replaced by the sharedFilter. Create filters withJournal::filter()orLiveJournal::filter(), and reuse them withJournal::query_with_filter()or subscriptions. Destination limits are checked without rebuilding the filter; invalid subscription filters and unresolved starting cursors now fail during registration, before polling begins.LiveSubscription::into_tokio()returnsResult<tokio::sync::mpsc::Receiver<_>>. Usesubscription.into_tokio()?to handle forwarding-thread creation failures, then.recv().awaitinstead of.next().await. The receiver uses the subscription's configured channel capacity;TokioSubscriptionand.into_receiver()have been removed.Journal::live()retains the journal's committed snapshot boundary in both file-access modes. Entries committed after the snapshot was opened are delivered as live entries, including those committed before the live engine was created.- Multi-file queries merge entry metadata before filtering so filters cannot change cursor order and cause resume gaps. This scans more metadata than prefiltering each file through its indexes; single-file queries retain indexed filtering. The bounded streaming merge coalesces identical entries at file heads, but does not promise global deduplication of arbitrarily overlapping files.
- Directory discovery skips missing roots and entries removed during scanning, but propagates other traversal errors even when another root contains readable journals.
Journal::verify_seal()requires every opened file to be sealed through its last committed object. Unsealed files and unsealed tails now return an error; active journals may need a later TAG before verification can succeed. This authenticates FSS-protected object contents, not mutable indexes, the complete header, or the presence of every file and newer entry.
To understand the crate quickly, read or run these examples in order:
tour: guided walkthrough ofJournal,JournalQuery,EntryRef/EntryOwned,Cursor, andLiveJournaltail: the smallest “open default journal and read entries” pathmatch_unit: the most common production filter shapecheckpoint_follow: resume-safe live subscription for long-running consumers
Open / discovery:
tour: guided API overview and mental modelopen_dir: open one journal directory and print entriesopen_dirs: merge multiple journal rootsopen_with_config: customizeJournalConfig
Query builder patterns:
tail: print the newest entries from the default journalfilter_exact: query by an exact field/value pairmatch_present: query by field presencematch_unit: query one systemd unitor_units: OR across two units withor_grouprecent_unit: query a unit within a recent time windowprint_fields: dump all fields from the newest matching entrycollect_owned: detach results intoEntryOwned
Cursor / resume:
cursor_roundtrip: print a cursor and resume from it withseek_cursorafter_cursor: resume strictly after a saved cursor stringcheckpoint_follow: persist cursors while following
Streaming / integration:
follow_unit: block and print a few newly appended entries from a live subscriptionlive_multi_subscriptions: share oneLiveJournalacross multiple unit subscriptionsfollow_tokio: bridge a live subscription into Tokio (--features tokio)verify_seal: verify FSS tags (--features verify-seal)
The zstd feature requires ruzstd 0.9.1, which fixes the unbounded sequence expansion described in
RUSTSEC-2026-0344.
That release still accepts some compressed blocks whose literals exceed the declared frame-window
limit. The crate's decoded-output limit remains enforced, but this is not complete Zstd format
validation. The upstream fix is PR #128, pending a
published release. A specifically ignored regression tracks that remaining case; no private fork
or partial replacement decoder is bundled.
The development toolchain follows stable; CI explicitly selects Rust 1.100.0 to verify the MSRV.
Keep both the root and fuzz Cargo.lock files in version control for reproducible checks. Library
consumers still resolve dependencies using the version requirements in Cargo.toml.
Both manifests deny Cargo's unused_dependencies lint for regular and build dependencies;
the feature matrix also checks optional dependencies in isolation.
just --justfile .justfile ci
just --justfile .justfile auditThese recipes require just, cargo-nextest, and cargo-audit. The CI recipe also smoke-tests the
benchmarks with assertions on live deliveries; it does not measure performance. CI tests each
optional feature with default features disabled, builds the fuzz harnesses with all compression backends enabled,
and runs strict journalctl comparisons on supported Ubuntu versions. Golden tests need a working
Linux journal and permission to write and read entries. They are explicitly ignored in the regular
suite; run them in a suitable environment with:
cargo test --locked --all-features --test golden_journalctl -- --ignoredSet SDJOURNAL_TEST_USE_SUDO=1 if journal access requires sudo. The optional format-fixture test is
also ignored by default; provide tests/fixtures/<case>/journal/ and a sibling expected.json, then run
cargo test --locked --all-features --test format_fixtures -- --ignored.
Explicitly requested integration tests fail if their dependencies or data are unavailable.
When intentionally updating dependencies, run cargo update for both manifests and repeat the
checks before committing the resulting lockfiles:
cargo update
cargo update --manifest-path fuzz/Cargo.toml