env-variables

Environment-variable reference for linuxguard-agent — LINUXGUARD_ENROLL_TOKEN, LINUXGUARD_NODE_NAME, LINUXGUARD_POD_UID, and related variables used by the start command.

This page enumerates every LINUXGUARD_* environment variable that the agent reads from os.Environ at startup. All variables are scoped to the start command — they do not affect config, probe, support-bundle, or other one-shot subcommands. Internal-only variables surfaced by the agent's PID-1 init wrapper are documented here as informational so operators reading process metadata can identify them; they are not for operators to set.

Variables

The table below is exhaustive for the user-facing environment surface. Variables not listed are either internal helpers (no documented effect) or do not exist in the agent source.

Variable	Format	Default	Used by	Description
LINUXGUARD_ENROLL_TOKEN	string (TOTP enrollment token, e.g. XXXX-XXXX-XXXX)	—	start (ephemeral mode)	Short-lived enrollment token. Bound to the --enroll-token flag via urfave/cli/v2's EnvVars. The agent reads this once at startup and immediately calls os.Unsetenv on it before any goroutine forks so the raw value does not remain readable via /proc/<pid>/environ. See Why immediately unset? below.
LINUXGUARD_NODE_NAME	string (Kubernetes node name, e.g. ip-10-0-0-42)	—	start (ephemeral mode)	Kubernetes node name supplied via the Downward API fieldRef: spec.nodeName. Bound to the --node-id flag via EnvVars. Feeds the workload-id derivation: sha256(node_name + ":" + pod_uid) becomes the workload identifier when --workload-id is not provided.
LINUXGUARD_POD_UID	string (Kubernetes pod UID, RFC 4122 v4)	—	start (ephemeral mode)	Kubernetes pod UID supplied via the Downward API fieldRef: metadata.uid. Read directly via os.Getenv (no flag binding) — no --pod-uid flag exists. Required when --workload-id is absent; pairs with LINUXGUARD_NODE_NAME for the workload-id derivation.
LINUXGUARD_TENANT_ID	string (UUID)	—	start (ephemeral mode)	Tenant identifier the agent enrols into. Bound to the --tenant-id flag via EnvVars. Required on the TOTP enrollment path — the backend's /agent/enroll handler rejects with 400 "tenantId required for TOTP enrollment" when the request body's TenantID is empty AND EnrollCode is set. Long-lived API keys carry their own tenant scope server-side, so the variable is optional on that path.
LINUXGUARD_API_URL	string (URL with trailing slash, e.g. https://dev-api.linuxguard.io/v1/)	channel-derived	start (ephemeral mode)	Override the LinuxGuard API base URL. Bound to the --api-url flag via EnvVars. Whitespace-only values are treated as empty so export LINUXGUARD_API_URL="" does not silently route to a no-host enrol POST. Channel default: stable → https://api.linuxguard.io/v1/; otherwise → https://dev-api.linuxguard.io/v1/.
LINUXGUARD_LOADER_EMBEDDED	true / false (boolean)	— (auto-on with loader_embedded build tag under PID 1 or --ephemeral)	start	Force the in-process embedded eBPF loader. Bound to the --loader-embedded flag via EnvVars. When unset, the agent infers the loader mode from build tags + PID-1 / ephemeral detection.
LINUXGUARD_PID1_CHILD	string (any non-empty value)	—	start (PID-1 detection only)	Internal sentinel surfaced for transparency. Set by the agent's PID-1 init re-exec wrapper to mark the child process so the agent code path detects "we are running under the init shim" without parsing the kernel's process tree. Operators should NOT set this manually — doing so causes the agent to skip PID-file machinery on a non-PID-1 host as if it were containerized, which produces a stale linuxguard-agent stop workflow. Documented here so process-introspection tooling (e.g., reading /proc/<pid>/environ during incident triage) can identify the value as agent-internal rather than user-supplied.

Resolution precedence (flag-bound variables)

For variables bound to a flag via urfave/cli/v2's EnvVars, the resolution order is:

1. Explicit --<flag> value on the command line — takes precedence over everything else.

2. EnvVars-bound environment variable — read when the flag is omitted.

3. Built-in default — used when neither the flag nor the env var is set.

LINUXGUARD_POD_UID is the exception: it is NOT bound to a flag (no --pod-uid exists), so it is read directly via os.Getenv and has no command-line override.

Why immediately unset?

The LINUXGUARD_ENROLL_TOKEN variable receives special handling: the agent reads it once at the very top of the start action, captures the value, and calls os.Unsetenv("LINUXGUARD_ENROLL_TOKEN") BEFORE any goroutine forks.

The rationale is the /proc/<pid>/environ leak surface. On Linux, an unprivileged process running as the same UID as the agent can read /proc/<linuxguard-pid>/environ for the lifetime of the agent process and observe every environment variable the agent inherited at exec time. If LINUXGUARD_ENROLL_TOKEN remained in the agent's environ block, a hostile co-tenant or a misconfigured monitoring agent could read the raw enrollment token and (within its TTL) self-enrol a rogue identity into the same tenant.

os.Unsetenv does not retroactively scrub the inherited environ block from kernel memory — the data is allocated at execve time and persists as long as the process lives. The Go runtime's Unsetenv updates the process-internal environ() slice and rewrites the same memory the kernel exposes via /proc/<pid>/environ, so subsequent reads of that pseudo-file return the redacted set. Empirically this means the window in which /proc/<linuxguard-pid>/environ contains the token is approximately the latency between execve and os.Unsetenv — measured in milliseconds, not minutes. The token is consumed once for the enrol POST and never needed again (the agent stores the resulting mTLS cert chain in memory or in /run/linuxguard/tls/ when --tls-cache is set), so the early unset does not impede operation.

Operators must continue to inject the token via container runtime environment-injection (Docker -e LINUXGUARD_ENROLL_TOKEN=..., Kubernetes valueFrom.secretKeyRef) — NOT via the agent command line — so the value does not appear in:

1. The process command line visible via /proc/<pid>/cmdline to ANY local UID.

2. Shell history (~/.bash_history, ~/.zsh_history).

3. The container runtime's audit log (Docker logs the command; not the environ block).

The Kubernetes valueFrom.secretKeyRef pattern is the recommended injection path — see start § Examples.

Variables NOT documented here

Variables that exist in the agent source but are NOT user-facing belong to debug/internal surface deliberately omitted per the hidden-CLI policy. The public flag for selecting the tenant environment is --environment on enroll, with --group as the backward-compatible alias.

If you encounter an undocumented LINUXGUARD_* variable in a process environ block, it is either an internal helper (e.g., the PID-1 init shim's coordination variables) or a test-mode override. Open a support case if you need confirmation; do not rely on undocumented variables for operational workflows — they may be renamed, removed, or made non-functional in any release.

---

Related: start | signals | exit-codes | CLI Reference