blivet

A correct, full-featured Unix daemon library and CLI for Rust.

blivet implements the full double-fork daemonization sequence with a parent-notification pipe, so your process detaches cleanly and the calling shell (or init system) knows exactly when the daemon is ready -- or why it failed. Errors that happen after forking are reported back to the parent with sysexits.h codes instead of vanishing into a void.

Why this crate?

• Correct by default. Mandatory double-fork, setsid, signal reset (including real-time signals on Linux), signal mask clear, fd close, /dev/null redirect -- the things most hand-rolled daemonizers forget.
• Parent notification. The calling process blocks until the daemon signals readiness or reports an error. No more "did it start?" polling.
• Split-phase privilege dropping. daemonize() returns while still privileged, giving you a window for operations like binding privileged ports before calling drop_privileges().
• Fail-safe drop. If you forget to call notify_parent(), the parent exits non-zero automatically.
• Unsafe contained. #![deny(unsafe_code)] at the crate root. All unsafe lives in a single module (unsafe_ops), with safe wrappers for everything else.
• Library and CLI. Use it as a Rust library with a builder API, or as a standalone daemonize binary (installed by cargo install blivet) that wraps any program.

Why the name blivet?

A blivet is the "impossible pitchfork" optical illusion, also known as the devil's fork, where the prongs are mysteriously detached from the base. Daemons are created by forking to detach from their parent terminal.

Install

cargo install blivet

This installs the daemonize command (the crate is blivet; the binary is daemonize). Verify with daemonize --version.

Or add the library to your project:

cargo add blivet

CLI Quickstart

Daemonize any program:

# Basic usage
daemonize -- /usr/bin/my-server --port 8080

# With pidfile and log redirection (stderr mirrors stdout by default)
daemonize \
  -p /var/run/myapp.pid \
  -o /var/log/myapp.log \
  -c /var/lib/myapp \
  -- /usr/bin/my-server

# Split stdout/stderr using .stdout/.stderr or .out/.err extensions (auto-derived)
daemonize \
  -p /var/run/myapp.pid \
  -o /var/log/myapp.stdout \
  -- /usr/bin/my-server  # stderr goes to /var/log/myapp.stderr

# Separate lockfile (overrides the pidfile default)
daemonize \
  -p /var/run/myapp.pid \
  -l /var/run/myapp.lock \
  -- /usr/bin/my-server

# Run as a different user and group (requires root)
daemonize -u www-data -g www-data -- /usr/bin/my-server

# Run in foreground (no fork/setsid)
daemonize --foreground -p /var/run/myapp.pid -- /usr/bin/my-server

# Set environment variables
daemonize -E RUST_LOG=info -E PORT=8080 -- /usr/bin/my-server

The parent process blocks until the daemon successfully calls exec, then exits 0. If anything fails (lockfile conflict, permission denied, exec error), the parent prints the error to stderr and exits with a sysexits.h code.

When -u/-g are specified, the CLI transfers ownership of the pidfile, lockfile, and log files to the target user/group before dropping privileges, so the daemon can continue to write to them after the switch.

CLI flags

Listed in daemonize --help order (a test keeps this table in sync with the binary):

Library quickstart

use blivet::{DaemonConfig, daemonize};

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let mut config = DaemonConfig::new();
    config
        .pidfile("/var/run/myapp.pid")
        .lockfile("/var/run/myapp.lock")
        .stdout("/var/log/myapp.out")
        .stderr("/var/log/myapp.err")
        .chdir("/var/lib/myapp");

    // SAFETY: must be called before spawning any threads.
    // daemonize() validates the config internally before forking.
    let mut ctx = unsafe { daemonize(&config)? };

    // Application initialization goes here (open sockets, load config, etc.)

    // Signal the parent that we're ready.
    ctx.notify_parent()?;

    // Daemon continues running...
    Ok(())
}

daemonize_checked provides a safe wrapper that verifies the process is single-threaded before forking — no unsafe needed:

use blivet::{DaemonConfig, daemonize_checked};

let config = DaemonConfig::new();
let mut ctx = daemonize_checked(&config)?; // panics unless exactly 1 thread
ctx.notify_parent()?;

It is available on Linux, macOS, FreeBSD, NetBSD, and OpenBSD, each using the kernel's own thread count (/proc/self/status on Linux, proc_pidinfo on macOS, sysctl on the BSDs). On any other target it is a #[deprecated] stub that never daemonizes (a hard compile error under -D warnings / #![deny(deprecated)]) — use unsafe { daemonize(&config) } there. To also compile on such a target, gate the call so the stub is never built:

#[cfg(any(target_os = "linux", target_os = "macos", target_os = "freebsd",
          target_os = "netbsd", target_os = "openbsd"))]
let mut ctx = blivet::daemonize_checked(&config)?;
#[cfg(not(any(target_os = "linux", target_os = "macos", target_os = "freebsd",
              target_os = "netbsd", target_os = "openbsd")))]
// SAFETY: no threads spawned before this point.
let mut ctx = unsafe { blivet::daemonize(&config)? };

Tip: see examples/echo_server.rs for a complete, runnable daemonized TCP echo server with clean signal-based shutdown and pidfile removal.

Split-phase privilege dropping

When your daemon needs to perform privileged operations (like binding to port 80, calling chroot, or setting resource limits) before dropping to an unprivileged user:

use blivet::{DaemonConfig, daemonize};

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let mut config = DaemonConfig::new();
    config
        .pidfile("/var/run/myapp.pid")
        .user("www-data")
        .group("www-data");

    // SAFETY: must be called before spawning any threads.
    let mut ctx = unsafe { daemonize(&config)? };

    // Still running as root here -- bind privileged port, chroot, set rlimits, etc.
    // let listener = TcpListener::bind("0.0.0.0:80")?;

    // Transfer file ownership, then drop privileges
    ctx.chown_paths()?;
    ctx.drop_privileges()?;

    ctx.notify_parent()?;
    // Now running as www-data...
    Ok(())
}

Foreground mode

For systemd, containers, or debugging, use foreground mode to skip forking while still applying all other daemon setup (umask, chdir, signal reset, etc.). Stdout and stderr are left inherited (not redirected to /dev/null) unless explicitly configured with .stdout()/.stderr():

let mut config = DaemonConfig::new();
config
    .foreground(true)
    .close_fds(false);  // keep supervisor-passed fds

Pidfile cleanup

When cleanup_on_drop is true (the default), the pidfile is removed when DaemonContext is dropped. However, Drop does not run when the process is killed by a signal (SIGTERM, SIGKILL, etc.) — which is how most daemons are stopped, so the pidfile would be left behind.

The simplest fix is the built-in cleanup_on_term_signals(), which installs async-signal-safe handlers that remove the pidfile on SIGINT/SIGTERM and then re-raise so the process still terminates normally:

use blivet::{DaemonConfig, daemonize};

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let mut config = DaemonConfig::new();
    config.pidfile("/var/run/myapp.pid");
    let mut ctx = unsafe { daemonize(&config)? };

    // Remove the pidfile on SIGINT/SIGTERM (pass custom signal numbers to
    // `cleanup_on_signals(&[...])` instead, if needed).
    ctx.cleanup_on_term_signals()?;

    ctx.notify_parent()?;
    // ... daemon work ...
    Ok(())
}

Note: this is library-only. The daemonize CLI cannot do this: it execs the target program, and exec resets all custom signal handlers to their default disposition. A program launched via the CLI must clean up its own pidfile.

If you already run a signal loop (e.g. to drive a graceful shutdown), you can instead clear the flag yourself and call cleanup() / let ctx drop. The example below uses the signal_hook crate for that; blivet does not re-export it, so add it yourself:

cargo add signal_hook

use std::sync::atomic::{AtomicBool, Ordering};
use std::sync::Arc;
use blivet::{DaemonConfig, daemonize};

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let config = DaemonConfig::new();
    let mut ctx = unsafe { daemonize(&config)? };
    ctx.notify_parent()?;

    // Set a flag on SIGTERM/SIGINT so the main loop exits cleanly
    let running = Arc::new(AtomicBool::new(true));
    signal_hook::flag::register(signal_hook::consts::SIGTERM, Arc::clone(&running))?;
    signal_hook::flag::register(signal_hook::consts::SIGINT, Arc::clone(&running))?;

    while running.load(Ordering::Relaxed) {
        // ... daemon work ...
    }

    ctx.cleanup(); // or just let ctx drop
    Ok(())
}

API overview

DaemonConfig

Builder for daemonization settings. All methods are infallible setters; validation is deferred to validate().

daemonize(&config) -> Result<DaemonContext, DaemonizeError>

Performs the daemonization sequence: pipe, double-fork, setsid, umask, chdir, /dev/null redirect, lockfile, pidfile, signal reset, signal mask clear, env vars, output redirect, fd close. Returns a DaemonContext in the grandchild (or the current process in foreground mode). The original parent blocks on the notification pipe.

User/group switching is not performed during this call. Use DaemonContext::drop_privileges() after doing any privileged work.

DaemonContext

Returned by a successful daemonize() call. Holds the lockfile, notification pipe, and config state needed for privilege operations.

Dropping without calling notify_parent() causes the parent to exit non-zero. When cleanup_on_drop is true (the default), dropping also removes the pidfile. Note that Drop does not run on signal termination — see Pidfile cleanup above.

DaemonizeError

Sixteen variants covering validation, fork, setsid, lock, permission, chown, exec, and parent-notify failures, plus a caller-supplied Application variant. Each maps to a sysexits.h exit code via exit_code().

Reporting your own failures

If startup work in the privileged init window fails (a socket bind, a database connect), report it to the parent with a sysexits.h code of your choosing via report_error_msg — no need to construct a DaemonizeError by hand:

let listener = match TcpListener::bind("0.0.0.0:80") {
    Ok(l) => l,
    // 71 == EX_OSERR; the parent prints the message and exits with this code.
    Err(e) => ctx.report_error_msg(71, format!("bind failed: {e}")),
};

Propagating exit codes from main

The sysexits.h codes only reach the shell if you use them. The idiomatic fn main() -> Result<(), E> prints the error via Termination and exits 1, ignoring exit_code(). To preserve the codes, drive exit_code() yourself:

use blivet::{daemonize, DaemonConfig, DaemonizeError};

fn main() {
    if let Err(e) = run() {
        eprintln!("{e}");
        std::process::exit(e.exit_code() as i32); // e.g. 77 for PermissionDenied
    }
}

fn run() -> Result<(), DaemonizeError> {
    let config = DaemonConfig::new();
    let mut ctx = unsafe { daemonize(&config)? };
    // ... application init ...
    // notify_parent() returns DaemonizeError (NotifyFailed, exit 71), so `?`
    // keeps a single error type and preserves the exit code.
    ctx.notify_parent()?;
    Ok(())
}

Minimum supported Rust version

1.85

License

Licensed under either of Apache License, Version 2.0 or MIT License at your option.