205 lines
5.7 KiB
Markdown
205 lines
5.7 KiB
Markdown
# ChronoGrid Daemon — Headless Node Setup Guide
|
||
|
||
This guide covers building, configuring, and deploying the `chronogrid-daemon`
|
||
binary as a persistent background peer node on Linux (systemd) and Windows.
|
||
|
||
---
|
||
|
||
## 1. Prerequisites
|
||
|
||
| Requirement | Minimum Version | Notes |
|
||
|---|---|---|
|
||
| Rust toolchain | 1.75 | Install via [rustup](https://rustup.rs) |
|
||
| OpenSSL dev libs | 3.x | Linux only: `libssl-dev` (Debian/Ubuntu) |
|
||
| Strawberry Perl | 5.x | Windows only: required by `openssl-sys` build script |
|
||
| OS keychain | — | Windows Credential Manager or Linux SecretService (libsecret) |
|
||
|
||
---
|
||
|
||
## 2. Building the Binary
|
||
|
||
### 2.1 Windows (MSVC target)
|
||
|
||
```powershell
|
||
cargo build --release --package chronogrid_daemon
|
||
# Output: target\release\chronogrid-daemon.exe
|
||
```
|
||
|
||
### 2.2 Linux (native)
|
||
|
||
```bash
|
||
cargo build --release --package chronogrid_daemon
|
||
# Output: target/release/chronogrid-daemon
|
||
```
|
||
|
||
### 2.3 Cross-compile for headless Linux server (from Windows)
|
||
|
||
```powershell
|
||
rustup target add x86_64-unknown-linux-gnu
|
||
cargo build --release --package chronogrid_daemon --target x86_64-unknown-linux-gnu
|
||
# Output: target/x86_64-unknown-linux-gnu/release/chronogrid-daemon
|
||
```
|
||
|
||
---
|
||
|
||
## 3. Installation (Linux)
|
||
|
||
```bash
|
||
# Create a dedicated system user
|
||
sudo useradd --system --no-create-home --shell /usr/sbin/nologin chronogrid
|
||
|
||
# Install the binary
|
||
sudo install -m 755 target/release/chronogrid-daemon /usr/local/bin/chronogrid-daemon
|
||
|
||
# Create data and config directories
|
||
sudo mkdir -p /var/lib/chronogrid /etc/chronogrid
|
||
sudo chown -R chronogrid:chronogrid /var/lib/chronogrid
|
||
sudo chmod 750 /var/lib/chronogrid
|
||
|
||
# Install config
|
||
sudo cp apps/chronogrid_daemon/config.example.toml /etc/chronogrid/config.toml
|
||
sudo chown root:chronogrid /etc/chronogrid/config.toml
|
||
sudo chmod 640 /etc/chronogrid/config.toml
|
||
```
|
||
|
||
### Cluster Swarm Key Distribution
|
||
|
||
All nodes in the same ChronoGrid cluster **must share the same swarm key**.
|
||
The key is auto-generated on first boot at `swarm_key_path`. Copy it to all other nodes:
|
||
|
||
```bash
|
||
# Retrieve key from the first node
|
||
cat /var/lib/chronogrid/swarm.key
|
||
|
||
# Place it on additional nodes
|
||
sudo -u chronogrid cp swarm.key /var/lib/chronogrid/swarm.key
|
||
sudo chmod 600 /var/lib/chronogrid/swarm.key
|
||
```
|
||
|
||
---
|
||
|
||
## 4. systemd Service
|
||
|
||
Create `/etc/systemd/system/chronogrid-daemon.service`:
|
||
|
||
```ini
|
||
[Unit]
|
||
Description=ChronoGrid P2P Headless Peer Node
|
||
Documentation=https://git.kellsupport.com/chronogrid
|
||
After=network-online.target
|
||
Wants=network-online.target
|
||
|
||
[Service]
|
||
Type=simple
|
||
User=chronogrid
|
||
Group=chronogrid
|
||
WorkingDirectory=/var/lib/chronogrid
|
||
ExecStart=/usr/local/bin/chronogrid-daemon \
|
||
--config /etc/chronogrid/config.toml \
|
||
--log-level info
|
||
Restart=on-failure
|
||
RestartSec=5
|
||
StartLimitIntervalSec=60
|
||
StartLimitBurst=5
|
||
NoNewPrivileges=yes
|
||
PrivateTmp=yes
|
||
ProtectSystem=strict
|
||
ReadWritePaths=/var/lib/chronogrid
|
||
ProtectHome=yes
|
||
CapabilityBoundingSet=
|
||
StandardOutput=journal
|
||
StandardError=journal
|
||
SyslogIdentifier=chronogrid-daemon
|
||
|
||
[Install]
|
||
WantedBy=multi-user.target
|
||
```
|
||
|
||
```bash
|
||
sudo systemctl daemon-reload
|
||
sudo systemctl enable chronogrid-daemon
|
||
sudo systemctl start chronogrid-daemon
|
||
sudo journalctl -u chronogrid-daemon -f
|
||
```
|
||
|
||
---
|
||
|
||
## 5. CLI Reference
|
||
|
||
```
|
||
chronogrid-daemon [OPTIONS]
|
||
|
||
Options:
|
||
-c, --config <PATH> Path to TOML config file
|
||
--db <PATH> SQLCipher database path (overrides config)
|
||
--log-level <LEVEL> error | warn | info | debug | trace [default: info]
|
||
-h, --help Print help
|
||
-V, --version Print version
|
||
```
|
||
|
||
`RUST_LOG` environment variable overrides `--log-level` and supports
|
||
target-specific directives, e.g. `RUST_LOG=chronogrid=debug,libp2p=warn`.
|
||
|
||
---
|
||
|
||
## 6. Key Management & First Boot
|
||
|
||
On first boot the daemon:
|
||
|
||
1. Generates a new Ed25519 node keypair → saved to `identity_path`.
|
||
2. Generates a new 256-bit swarm key → saved to `swarm_key_path`.
|
||
3. Derives a 256-bit Argon2id database master key (node + swarm fingerprints + random salt).
|
||
4. Stores derived key + salt in the OS keychain:
|
||
- **Linux**: SecretService D-Bus (libsecret).
|
||
- **Windows**: Windows Credential Manager (DPAPI-backed).
|
||
5. Opens or creates the SQLCipher 4.x database at `database.path`.
|
||
|
||
On subsequent boots the key is retrieved from the keychain — no human passphrase needed.
|
||
|
||
> **Security Note**: Protect `swarm.key` with mode `600`. Any node that holds the
|
||
> swarm key can join the cluster.
|
||
|
||
---
|
||
|
||
## 7. Networking & Firewall
|
||
|
||
Default ports used by the daemon:
|
||
|
||
| Protocol | Port | Purpose |
|
||
|---|---|---|
|
||
| TCP | 7700 | libp2p TCP transport (Noise XK) |
|
||
| UDP | 7700 | libp2p QUIC-v1 transport |
|
||
|
||
```bash
|
||
# UFW (Ubuntu/Debian)
|
||
sudo ufw allow 7700/tcp comment "ChronoGrid P2P TCP"
|
||
sudo ufw allow 7700/udp comment "ChronoGrid P2P QUIC"
|
||
```
|
||
|
||
LAN discovery uses **mDNS** (multicast UDP 5353) — no extra firewall rules needed on local networks.
|
||
|
||
---
|
||
|
||
## 8. Upgrading
|
||
|
||
```bash
|
||
cargo build --release --package chronogrid_daemon
|
||
sudo systemctl stop chronogrid-daemon
|
||
sudo install -m 755 target/release/chronogrid-daemon /usr/local/bin/chronogrid-daemon
|
||
sudo systemctl start chronogrid-daemon
|
||
```
|
||
|
||
Schema DDL uses `CREATE TABLE IF NOT EXISTS` — migrations apply automatically without data loss.
|
||
|
||
---
|
||
|
||
## 9. Troubleshooting
|
||
|
||
| Symptom | Likely Cause | Resolution |
|
||
|---|---|---|
|
||
| `Keychain retrieval failed` | `libsecret` not installed | Install `libsecret-1-dev`; ensure D-Bus session exists |
|
||
| `Failed to open encrypted database` | Corrupt DB or wrong key | Check keychain entry; restore from backup |
|
||
| `No valid listen addresses` | Invalid Multiaddr syntax | Verify `listen_addrs` in config |
|
||
| No peers discovered | Swarm key mismatch or firewall | Confirm all nodes share the same `swarm.key`; check firewall |
|
||
| High CPU on startup | Argon2id KDF (expected) | ~1–2 s on first boot at 64 MiB / 3 iterations — normal |
|