greggd

Lightweight Linux, macOS, and Windows metrics daemon for the gregg monitoring ecosystem.

Installation

The current published v1.0.12 release is source-only. Cargo is the working installation path until the first binary-bearing release; the bootstrap installer is the intended path afterward.

# Current working installation
cargo install greggd --locked

# After a binary-bearing release is published
# curl -fsSL https://github.com/eggstack/gregg/releases/latest/download/install.sh | sudo sh -s -- greggd

Prebuilt assets (glibc 2.17 on Linux, unsigned on macOS):

greggd-x86_64-unknown-linux-gnu · greggd-aarch64-unknown-linux-gnu (covers 64-bit Raspberry Pi/Le Potato)
greggd-x86_64-apple-darwin · greggd-aarch64-apple-darwin
greggd-x86_64-pc-windows-msvc.exe

Linux ARMv7 (armv7l) is source-build only and uses cargo install when available. See packaging/README.md for the full bootstrap contract, checksum verification, and install.sh/install.ps1 details.

Usage

Run the daemon directly in the foreground. On Unix, systemd and launchd are optional operator-managed deployment mechanisms; greggd does not invoke them.

greggd run
greggd run --config /path/to/greggd.toml

On Windows, native SCM lifecycle commands remain available:

greggd start
greggd stop
greggd restart

Automatic startup and restart (cross-platform restart, Unix startup):

greggd startup install                        # auto: systemd / launchd / cron / Windows SCM
greggd startup install --method systemd       # explicit method
greggd startup instructions                   # read-only, prints exact commands/paths
greggd startup instructions --method cron
greggd restart                                # manager-aware restart (systemd / launchd / SCM / direct)
greggd update                                 # binary-first update; restarts if running, leaves stopped services stopped

startup install defaults to auto: Windows→SCM, macOS→launchd, Linux with running systemd→systemd, else cron. Systemd uses /usr/local/bin/greggd, /etc/gregg/greggd.toml, greggd user/group, /etc/systemd/system/greggd.service (atomic, daemon-reload + enable + start/restart); launchd uses /Library/LaunchDaemons/com.eggstack.greggd.plist; cron uses an idempotent # greggd managed watchdog block with @reboot + * * * * * croncheck (shell-quoted, preserves unrelated crontab, never edits /var/spool/cron). An identified systemd/launchd host never silently falls back to cron on permission failure; the exact sudo <exe> startup install --method <...> is printed and exit 4 is returned. No internal sudo. startup instructions never mutates state. restart is manager-aware and factored for update reuse (systemd via systemctl restart greggd, launchd via launchctl kickstart -k, Windows via SCM, otherwise stop + detached run).

greggd update queries the latest stable greggd crate on crates.io, downloads the exact vX.Y.Z GitHub asset plus .sha256, verifies checksum and candidate version before any replacement, then atomically replaces the current executable (same-filesystem rename on Unix, self-replace on Windows) and restarts only when the daemon was running/managed (systemd active, launchd loaded, SCM running, or direct/cron running); intentionally stopped services remain stopped and a successful replacement with failed restart reports Installed X.Y.Z but not activated with the exact greggd restart/systemctl/launchctl command and returns nonzero. No background checks or sudo.

Ensure the daemon is running. croncheck is a watchdog for cron, Task Scheduler, and other supervisors without built-in readiness monitoring. It probes /v2/healthz with bounded raw HTTP on the configured local endpoint, normalizing wildcard binds to loopback. Valid Gregg Ready, Warming, and Failed responses all mean the daemon is running. Only a refused connection proves the endpoint absent and permits spawning greggd run as a detached child; unrelated, malformed, silent, or ambiguous peers return nonzero without spawning. No service manager is invoked.

greggd croncheck
greggd configprint
greggd version

On Windows, the service entry point is greggd service (internal, used by the SCM). Install/uninstall via the provided PowerShell scripts in packaging/. For startup, the PowerShell installer remains the canonical SCM registration; startup install on Windows reports service state and startup instructions prints SCM commands.

Configuration

Default config path:

Linux: /etc/gregg/greggd.toml
macOS: /Library/Application Support/gregg/greggd.toml
Windows: %ProgramData%\gregg\greggd.toml

Override the default with --config PATH.

configprint is read-only and prints the configured bind address as a canonical socket address, with bind wildcards resolved to the host's primary local IP so the output is a usable address a remote client can dial. A specific configured host is preserved unchanged, and a wildcard is preserved verbatim if the local IP cannot be resolved. The output looks like 192.168.182.143:11310 or [fd00::10]:11310. The command does not probe the network, bind a listener, start, stop, or modify the daemon; wildcard resolution uses a transient UDP connect() that performs a local route lookup only and transmits no packets.

Network

This daemon is designed for private networks only. It exposes a read-only HTTP/1 JSON API on the configured port (default 11310) and is not hardened for public internet exposure. No firewall rules are created automatically. LAN exposure is operator-controlled and the daemon has no TLS or authentication.

/v2/status is the universal status endpoint and may include a bounded drives list of mounted local filesystem names with numeric used and total bytes. Missing or null drive data means unavailable/legacy; an empty list means successful enumeration with no eligible volumes. Collection is best-effort and does not model physical disks or storage topology. Linux and macOS retain /v1/status; Windows is v2-only for status semantics.

The configured daemon display name must be non-empty, at most 128 bytes, and contain no control characters. If identity collection fails, the daemon does not publish a blank identity; it remains warming or failed and preserves any previous valid snapshot.

When writing configuration, a newly created parent directory is restricted to mode 0700; an existing operator-managed directory keeps its current permissions. Metadata errors while loading a default config are reported instead of silently falling back to defaults.

On Unix, greggd stop uses the config-specific local control socket. The socket path is reserved by the kernel before its restrictive permissions are verified, so a concurrent path occupant is never replaced; the temp-directory fallback remains best effort when the config-adjacent directory is unavailable.

If the system clock moves backward, a future-dated cached snapshot is not treated as stale solely because its timestamp is ahead of the current clock.

License

MIT