status

Reference for linuxguard-agent status — check whether the agent process is running, by inspecting the PID file and verifying the process is alive.

Synopsis

Report whether the linuxguard-agent start process is running on the local host. The check is informational: the answer is conveyed by the stdout text, NOT by the exit code (the command always exits 0). For programmatic health checks in shell scripts, parse the stdout or use pgrep linuxguard-agent / systemctl is-active linuxguard-agent instead.

linuxguard-agent status

How the check works

status reads the PID file at cfg.PidFilePath (default /var/run/linuxguard-agent.pid), parses the integer, and calls syscall.Kill(pid, 0) to verify the process exists. Sending signal 0 is a standard POSIX existence probe — it returns no signal to the target process; it returns success when the process exists or ESRCH when it does not.

A successful "is running" verdict therefore requires both:

1. The PID file at cfg.PidFilePath exists and contains a parseable integer.

2. The process with that PID is alive AND the caller has permission to signal it (root or the same UID).

The check is local-only — status does NOT contact the backend or verify that the running agent is heartbeating to LinuxGuard. A running verdict means "a process exists at the PID file's PID"; it does not mean "the agent is healthy and reporting".

Note: Ephemeral and PID-1 deployments (containerised) skip PID-file machinery entirely. Running linuxguard-agent status inside a container reports not running even when the agent IS running, because the PID file was never written. For container health checks, use the orchestrator's native process supervision (Kubernetes liveness probe, Docker HEALTHCHECK) instead.

Flags

status takes no flags.

Environment

status reads no LINUXGUARD_* environment variables. The PID-file path comes from the agent context's resolved config (cfg.PidFilePath), populated by config.Setup at the binary's Before hook.

Signals

status is a one-shot CLI invocation — it does not install signal handlers via signal.Notify. The signal-0 probe is sent to the agent's PID for the existence check; the agent's start process receives nothing observable (signal 0 is a no-op probe by POSIX definition).

Exit codes

Code	Meaning
0	Always. The "running" / "not running" answer is on stdout. status does not return a non-zero exit when the agent is stopped, missing, or unreadable.

Examples

Check a running agent

sudo linuxguard-agent status

Stdout:

linuxguard-agent is running with PID: 4217

Check a stopped agent

sudo linuxguard-agent status

Stdout:

linuxguard-agent is not running

The same output is produced when the PID file is missing (clean stop or fresh install), corrupt, or when the PID points to a process that has exited.

Use status in a shell script

Because the exit code is always 0, the answer must come from stdout. Capture and grep:

state=$(sudo linuxguard-agent status)
case "$state" in
  *"is running"*) echo "OK" ;;
  *) echo "DOWN" >&2; exit 1 ;;
esac

Or use the systemd integration on packaged installs (no agent invocation needed):

if systemctl is-active --quiet linuxguard-agent; then
  echo "OK"
else
  echo "DOWN" >&2
  exit 1
fi

systemctl is-active returns exit code 0 for active (running) and non-zero for any other state — easier than parsing stdout.

Combine with show-config for triage

if sudo linuxguard-agent status | grep -q "is running"; then
  echo "Agent process: UP"
  sudo linuxguard-agent show-config | sed '/^>>/d' | jq -r .ServerID
else
  echo "Agent process: DOWN — checking enrolment state"
  sudo linuxguard-agent show-config | sed '/^>>/d' | jq -r 'select(.ServerID != "")'
fi

The combination distinguishes "agent not running and never enrolled" (fresh install) from "agent not running but enrolled" (crashed or stopped service that needs investigation).

---

Related: start | show-config | signals | CLI Reference