daemon_forge 0.0.1

A robust, cross-platform library for daemonizing Rust applications.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93

# DaemonForge


**DaemonForge** is a cross-platform library for creating system daemons (background services) in Rust.
It abstracts away the low-level complexities of operating system process management, providing a safe, idiomatic, and ergonomic builder API.

This crate is suitable for learning and experimentation, but not recommended for serious or production projects.

## Key Features


* **True Cross-Platform Support**:
    * **Unix/Linux**: Implements the canonical daemonization routine (`double-fork`, `setsid`, `umask`, and signal handling).
    * **Windows**: Uses native "Detached Processes" and manages creation flags for true background execution without a console window.
* **Locking Mechanism**:
    * Automatically prevents multiple instances of the same service from running simultaneously.
    * Utilizes `flock` (Unix) and **Global Named Mutexes** (Windows) for reliable exclusion.
* **Security First**:
    * Secure environment variable clearing.
    * Support for privilege dropping (User/Group switching) and `chroot` jail on Unix systems.
* **Other features**:
    * **Panic Capture**: Redirects `stdout`/`stderr` to log files, ensuring that panics and crashes are recorded instead of being lost.

## Usage Examples


### Linux/Unix Example


```no_run
use daemon_forge::ForgeDaemon;
use std::fs::File;

fn main() {
    let stdout = File::create("/tmp/daemon.out").unwrap();
    let stderr = File::create("/tmp/daemon.err").unwrap();

    let daemon = ForgeDaemon::new()
        .pid_file("/tmp/test.pid")
        .working_directory("/tmp")
        .user("www-data") // Unix specific: drop privileges
        .group("www-data")
        .stdout(stdout)
        .stderr(stderr)
        .start();

    match daemon {
        Ok(_) => println!("Daemon started successfully"),
        Err(e) => eprintln!("Error starting daemon: {}", e),
    }
}
````

### Windows Example


On Windows, it is highly recommended to set a `.name()` for your daemon. This creates a global mutex to ensure uniqueness.

```no_run
use daemon_forge::ForgeDaemon;
use std::fs::File;

fn main() {
    // Use absolute paths on Windows for safety
    let stdout = File::create("C:\\Logs\\service.out").unwrap();
    let stderr = File::create("C:\\Logs\\service.err").unwrap();

    let daemon = ForgeDaemon::new()
        .name("MyUniqueService") // Creates "Global\DaemonForge_MyUniqueService" Mutex
        .pid_file("C:\\Logs\\service.pid")
        .working_directory("C:\\Logs")
        .stdout(stdout)
        .stderr(stderr)
        .start();

    match daemon {
        Ok(_) => println!("Service launched in background"),
        Err(e) => eprintln!("Critical Failure: {}", e),
    }
}
```

## Advanced Configuration


You can execute a `privileged_action` before the process fully daemonizes. This is useful for tasks that require higher permissions (like binding to port 80) or for checking environment prerequisites.

```rust
# use daemon_forge::ForgeDaemon;

ForgeDaemon::new()
    .clear_env(true) // Clears inherited environment variables
    .env("API_KEY", "secret_value") // Sets explicit variables
    .privileged_action(|| {
        println!("Initializing resources before forking...");
        // If this returns Err, the daemon will abort startup.
        Ok("Initialization Done")
    });
```