start

Reference for linuxguard-agent start — typical service mode and ephemeral mode flags, environment variables, signals, and exit codes.

Synopsis

Start the LinuxGuard agent. Two operating modes are supported:

• Typical service mode — the agent runs as a long-lived systemd service on a host, reads its enrollment from the persisted local config database (/var/lib/linuxguard/), and writes a PID file to coordinate with linuxguard-agent stop and linuxguard-agent status.

• Ephemeral mode — the agent runs as the main process inside a container (typically PID 1), enrols once via a short-lived TOTP token supplied through LINUXGUARD_ENROLL_TOKEN, holds the resulting mTLS cert chain in memory, and skips PID-file machinery because the container orchestrator owns lifecycle. Triggered by any of: the --ephemeral flag, a non-empty --enroll-token value, or detection of PID 1 / the LINUXGUARD_PID1_CHILD re-exec sentinel.

linuxguard-agent start [flags]

Flags

Flag	Type	Default	Description
--api-url <url>	string	channel-derived (stable→https://api.linuxguard.io/v1/; otherwise https://dev-api.linuxguard.io/v1/)	Override the LinuxGuard API base URL for ephemeral mode. Whitespace-only values are treated as empty. Reads LINUXGUARD_API_URL when the flag is omitted.
--config-dir <path>	string	/var/lib/linuxguard/ on Linux, ./ for local builds	Override the local config directory. Ignored in ephemeral mode.
--enroll-token <value>	string	—	Enrollment token for ephemeral mode. Prefer the LINUXGUARD_ENROLL_TOKEN env var: the agent reads the env-bound value once at startup and immediately unsets it so the raw token does not remain visible via /proc/<pid>/environ.
--ephemeral	bool	false	Run in ephemeral (containerised) mode: enrol via LINUXGUARD_ENROLL_TOKEN, hold the cert chain in memory, never write to /var/lib/linuxguard/. Requires either Downward API env vars (LINUXGUARD_NODE_NAME + LINUXGUARD_POD_UID) or --workload-id.
--loader-embedded	bool	auto-on with the loader_embedded build tag under PID 1 or --ephemeral	Force the in-process embedded eBPF loader. Reads LINUXGUARD_LOADER_EMBEDDED when the flag is omitted.
--node-id <name>	string	—	Kubernetes node name (Downward API). Populates the workload-id derivation. Reads LINUXGUARD_NODE_NAME when the flag is omitted.
--server-id <id>	string	—	Pre-fill server ID for re-enrol continuity. Optional.
--tenant-id <id>	string	—	Tenant ID the agent enrols into. Required for the TOTP-token ephemeral path (the backend's /agent/enroll handler rejects with 400 "tenantId required for TOTP enrollment" when the body is missing this value). Optional on the long-lived API-key path. Reads LINUXGUARD_TENANT_ID when the flag is omitted.
--tls-cache	bool	false	Opt-in: write cert chain + token-hash tag to /run/linuxguard/tls/ (mode 0700/0600) so a container restart can reuse the cache without re-enrolling. Docker operators additionally pass --tmpfs /run/linuxguard:rw,mode=0700,size=10m.
--workload-id <hex>	string	—	Explicit workload identifier (sha256 hex). Required when the Downward API env vars are absent. Hard-error if neither this flag nor LINUXGUARD_NODE_NAME + LINUXGUARD_POD_UID are set.

Enrollment flags

Two enrollment paths are supported on the start command:

• Long-lived API key (typical service mode). The agent reuses an enrollment performed previously via linuxguard-agent enroll (documented in Agent Commands for the v3.0 surface; phase 18 will ship the per-command v4.0 page). start reads the persisted tenant_id, api_key, base_url, and server_id from the local config database.

• Short-lived TOTP enrollment token (ephemeral mode). Supply the token via LINUXGUARD_ENROLL_TOKEN (preferred) or the --enroll-token flag, plus --tenant-id (required by the backend for the TOTP path), plus a workload identifier either via Downward API env vars or --workload-id. The agent posts a one-shot enrollment, receives the mTLS cert chain in the response, holds it in memory (or in /run/linuxguard/tls/ when --tls-cache is set), and never writes to /var/lib/linuxguard/.

The --server-id flag is optional in either path and provides re-enrol continuity when an existing server identity is being recycled.

Ephemeral mode flags

The trio --ephemeral + --workload-id + --tls-cache configures the container-friendly mode. The agent treats the presence of a non-empty --enroll-token (or its env-bound equivalent) as an implicit --ephemeral, so the explicit flag is not required when docker run -e LINUXGUARD_ENROLL_TOKEN=... supplies the token. The agent also auto-detects PID 1 as ephemeral so containerised PID-1 deployments do not need the flag at all.

In ephemeral mode the agent does NOT call agent.EnsureNotRunning or agent.WritePID; the container orchestrator owns lifecycle and a parent-vs-worker PID race would otherwise kill the worker before the first heartbeat.

Network and storage flags

--api-url (or LINUXGUARD_API_URL) overrides the channel-baked default base URL. Whitespace-only values are treated as empty so an operator who exports LINUXGUARD_API_URL="" does not silently route the agent to a no-host enrol POST. The resolution order is: explicit flag > env var > channel default. Channel default is determined by the binary's build-time channel ldflag: stable returns https://api.linuxguard.io/v1/; anything else (including unstable and empty) returns the dev backend.

--tls-cache controls whether the ephemeral cert chain is mirrored to a tmpfs path for restart continuity. Off by default. Without --tls-cache, a container restart triggers a fresh enrollment.

Environment

Variable	Default	Description	Used by
LINUXGUARD_ENROLL_TOKEN	—	TOTP enrollment token consumed once at startup and immediately unset to avoid /proc/<pid>/environ leaks. Bound to the --enroll-token flag.	start (ephemeral)
LINUXGUARD_NODE_NAME	—	Kubernetes node name supplied via the Downward API fieldRef. Bound to the --node-id flag. Feeds the workload-id derivation.	start (ephemeral)
LINUXGUARD_POD_UID	—	Kubernetes pod UID supplied via the Downward API fieldRef. Read directly via os.Getenv (no flag binding). Required when --workload-id is not provided.	start (ephemeral)
LINUXGUARD_TENANT_ID	—	Tenant ID the agent enrols into. Bound to the --tenant-id flag. Required for the TOTP path; optional for the API-key path.	start (ephemeral)
LINUXGUARD_API_URL	channel default	Override the LinuxGuard API base URL. Bound to the --api-url flag. Whitespace-only values are treated as empty.	start (ephemeral)
LINUXGUARD_LOADER_EMBEDDED	—	Force the in-process embedded eBPF loader. Bound to the --loader-embedded flag.	start
LINUXGUARD_PID1_CHILD	—	Internal sentinel set by the agent's PID-1 init re-exec wrapper. Operators should not set this manually. When present (or when os.Getpid() == 1), the agent treats the context as ephemeral and skips PID-file machinery.	start (PID-1 detection)

Signals

The start command installs a single handler goroutine plus a separate SIGHUP listener for log-level reload. All other agent commands are one-shot and do not install signal handlers.

Signal	Behavior
SIGHUP	Two independent effects: (1) the active lumberjack rotator calls Rotate() to close and reopen the current log file descriptor — enables coexistence with external logrotate via a postrotate kill -HUP. (2) The log-level reload handler re-runs config.Setup and applies the resolved level via lglog.SetLevel so a config set log_level change takes effect without restart.
SIGTERM	Graceful shutdown. The signal is stored in the caughtSignal atomic value, the agent context is cancelled, and main returns. After the agent run unwinds, the agent calls os.Exit(128 + int(syscall.SIGTERM)) = os.Exit(143).
SIGINT	Graceful shutdown (Ctrl-C). Same path as SIGTERM. The agent calls os.Exit(128 + int(syscall.SIGINT)) = os.Exit(130).

The agent re-raises caught signals from main (not the signal-handling goroutine) so the re-raise is guaranteed to run on a goroutine the runtime keeps alive until main returns. The earlier signal.Reset + syscall.Kill approach routed through Go's dieFromSignal and silently exited 2 in containerized PID-1 deployments; the os.Exit(128+signum) approach matches docker wait's reported exit code.

Important: An external logrotate postrotate script must kill -HUP the running agent PID to close and reopen the agent's log file descriptor; otherwise the rotated file remains open via the inherited fd and disk usage continues growing on the inode of the rotated file.

Exit codes

Code	Meaning
0	Successful operation. start does not exit 0 in normal long-running service mode; 0 is observed only for --help and similar early-exit paths.
1	General error — surfaced via log.Fatal(err) after the agent run returns a non-nil error. Includes enrollment failures, PID-file collisions in typical service mode, and most agent-runtime errors.
130	SIGINT (Ctrl-C) — graceful interactive cancellation. os.Exit(128 + int(syscall.SIGINT)).
143	SIGTERM — graceful orchestrator-driven shutdown. os.Exit(128 + int(syscall.SIGTERM)).

Examples

Typical service mode (host install)

The agent has already been enrolled via linuxguard-agent enroll; start reuses the persisted enrollment from /var/lib/linuxguard/.

sudo linuxguard-agent start

In packaged installs this is invoked by the linuxguard-agent.service systemd unit on boot; manual invocation is for development and incident-response scenarios.

Ephemeral mode (Docker)

Supply the enrollment token through an environment variable so the value never appears on the command line or in shell history. The agent reads it once and unsets it before any goroutine forks.

docker run --rm \
  --pid=host \
  --cap-add=SYS_ADMIN --cap-add=BPF --cap-add=PERFMON \
  -e LINUXGUARD_ENROLL_TOKEN="$ENROLL_TOKEN" \
  -e LINUXGUARD_TENANT_ID="$TENANT_ID" \
  -e LINUXGUARD_NODE_NAME="$(hostname)" \
  -e LINUXGUARD_POD_UID="$(uuidgen)" \
  --tmpfs /run/linuxguard:rw,mode=0700,size=10m \
  ghcr.io/linuxguardx/linuxguard-agent:vX.Y.Z \
  linuxguard-agent start --tls-cache

Ephemeral mode (Kubernetes DaemonSet, abbreviated)

env:
  - name: LINUXGUARD_ENROLL_TOKEN
    valueFrom:
      secretKeyRef:
        name: linuxguard-enroll
        key: token
  - name: LINUXGUARD_TENANT_ID
    valueFrom:
      secretKeyRef:
        name: linuxguard-enroll
        key: tenantId
  - name: LINUXGUARD_NODE_NAME
    valueFrom:
      fieldRef:
        fieldPath: spec.nodeName
  - name: LINUXGUARD_POD_UID
    valueFrom:
      fieldRef:
        fieldPath: metadata.uid
args: ["start", "--tls-cache"]

The full DaemonSet manifest with securityContext, hostPath rationale, Pod Security Standard profile, and RBAC ships in Phase 20.

Reload log level without restart

config set log_level persists the new value and sends SIGHUP to the running agent. The SIGHUP handler in start re-reads the persisted config and applies the new level immediately.

sudo linuxguard-agent config set log_level debug

The single config set command performs the persist + SIGHUP in one step (see config). External tools that bypass config set (e.g., editing the config database directly) must kill -HUP $(cat /var/run/linuxguard-agent.pid) themselves.

---

Related: config | probe | CLI Reference | Reference