config

Reference for linuxguard-agent config — set, get, unset, and list-keys subcommands for runtime configuration without restarting the agent.

Synopsis

Read or mutate individual runtime configuration keys. The config command exposes only toggleable fields — fields whose Go type is bool, string, or []string. Identity fields (server_id, tenant_id, api_key, env, mode, base_url) are NOT exposed via this command; they are bound at enrollment and immutable for the agent's lifetime.

linuxguard-agent config <subcommand> [args]

Subcommands

Subcommand	Synopsis	Purpose
set	linuxguard-agent config set <key> <value>	Persist a toggleable key. Bool values: true/false/1/0. String slices: comma-separated. The log_level key triggers a special path (validate + persist + SIGHUP).
get	linuxguard-agent config get <key>	Print the current value of a single toggleable key. Bool fields render as true/false; string slices render comma-separated.
unset	linuxguard-agent config unset <key>	Clear a key. Currently supports only log_level (clears the local pin and SIGHUPs the running agent so the precedence chain falls back to ack-delivered → tenant default → built-in info).
list-keys	linuxguard-agent config list-keys	Print all toggleable keys with their current values in struct declaration order.

Toggleable keys

The full set of toggleable keys is enumerated by linuxguard-agent config list-keys against the running binary — the canonical list is exposed by the agent's Config.ListKeys() API and depends on the json: struct tags present in the Config type. The matrix below documents the keys whose behavior is non-obvious. Bool values accept true/false/1/0; string slices are comma-separated.

Key	Type	Default	Description	Reload behavior
log_level	string	info	Wire-format level: lowercase trace / debug / info / warn / error. Strict — INFO, Info, integer codes, or any other casing are rejected. Uses the special path described below.	Validate + persist + SIGHUP delivered to the running agent. Applied without restart.
logging.max_size_mb	int (1..10000)	50	Lumberjack rotation size threshold in MB. Set to e.g. 100 to allow 100 MB per rotated segment.	Applied at next rotation point.
logging.max_age_days	int (0..3650)	14	Days a rotated backup is retained before lumberjack deletes it. Explicit 0 means no age-based pruning.	Applied at next rotation point.
logging.max_backups	int (0..100)	5	Maximum number of rotated backup files lumberjack retains. Explicit 0 means retain all.	Applied at next rotation point.
logging.compress	bool	true	Whether lumberjack gzip-compresses each rotated backup.	Applied at next rotation point.
tags	string slice	—	Comma-separated tag names applied to the agent's identity. Documented elsewhere; included here as a list-keys example.

Important: Identity fields (server_id, tenant_id, api_key, env, mode, base_url) are NOT toggleable via config set. They are owned by the enroll subcommand and ephemeral-mode enrollment via LINUXGUARD_ENROLL_TOKEN; once set they remain immutable for the agent's lifetime. The config command rejects attempts to set them by returning unknown config key (they are excluded from the exposed key set).

The log_level special path

When the set subcommand receives log_level as the key, the agent runs a four-step flow distinct from the generic SetField path:

1. Validate the value via lglog.ParseLevel against the strict lowercase wire format. Invalid values (uppercase, integer, empty) return an error and the persist step is skipped.

2. Persist both LogLevel and LogLevelLocalPinned = true to the local config database. The sentinel pair signals "operator pinned this level explicitly" so backend acks do not overwrite it.

3. SIGHUP the running agent. The signal triggers the agent's log-level reload handler which re-reads the persisted config and applies the new level via lglog.SetLevel.

4. Report the result. The command prints >> log_level = <value> (persisted, SIGHUP delivered) on success, or >> log_level = <value> (persisted; agent not running — applies on next start) if no agent process is found at the PID-file path.

The unset log_level flow mirrors this in reverse: it clears both LogLevel and LogLevelLocalPinned, persists, and SIGHUPs. After unset, the agent's precedence chain resolves to: cached ack-delivered value > tenant default > built-in info.

Flags

The top-level config command has no flags of its own. Subcommands take positional arguments (<key> and optionally <value>) as documented in the Subcommands table above.

Environment

config reads no environment variables beyond what config.Setup reads for the agent process at start time (notably the local-config-environment selection that resolves to dev or prod configuration paths). The LINUXGUARD_* env vars documented for start do not affect config invocations.

Signals

config is a one-shot CLI invocation — it does not install signal handlers via signal.Notify. The agent's process model for config is: run the subcommand, persist if applicable, optionally deliver a single SIGHUP via syscall.Kill to the running start process (the log_level special path), and exit.

The SIGHUP delivery is the agent's only signal interaction during a config invocation. It targets the PID discovered via pidfile.Discover(cfg.PidFilePath); ESRCH (process exited between discovery and kill) is treated as "agent not running" and not an error.

Exit codes

Code	Meaning
0	Successful operation. The key was read or set; the SIGHUP was delivered (or ESRCH-tolerated).
1	General error. Surfaced via log.Fatal after the agent run returns a non-nil error. Includes: unknown config key, invalid value (e.g., non-bool for a bool field, out-of-range integer for a logging.* key, invalid log level), wrong argument count, config-service init failure, persist failure, SIGHUP delivery failure for reasons other than ESRCH.

Examples

Pin the log level to debug at runtime

sudo linuxguard-agent config set log_level debug

Expected stdout:

>> log_level = debug (persisted, SIGHUP delivered)

If the agent is not running:

>> log_level = debug (persisted; agent not running — applies on next start)

Clear the local log-level pin

sudo linuxguard-agent config unset log_level

Expected stdout:

>> log_level cleared (persisted, SIGHUP delivered)

After unset, the precedence chain resolves to the cached ack value (if the backend has delivered one), the tenant default (if configured), or the built-in info.

Inspect a single key

linuxguard-agent config get logging.max_size_mb

Expected stdout (default):

50

List all toggleable keys with current values

linuxguard-agent config list-keys

Sample stdout (truncated; exact key set depends on the binary's Config struct):

log_level                                debug
logging.max_size_mb                      50
logging.max_age_days                     14
logging.max_backups                      5
logging.compress                         true
tags                                     web-server,us-east
...

Increase log retention without restart

sudo linuxguard-agent config set logging.max_age_days 30
sudo linuxguard-agent config set logging.max_backups 10

The new values are applied at the next rotation point; the active log file is not rotated immediately. To force an immediate close-and-reopen for an external logrotate step, send SIGHUP to the running agent.

Reject an invalid log level

sudo linuxguard-agent config set log_level INFO

Expected exit code: 1. Expected stderr (paraphrased):

unknown log level "INFO" (must be one of: trace, debug, info, warn, error)

The strict lowercase wire format prevents subtle drift between the agent CLI, the config file, the ack envelope, and the audit log row.

---

Related: start | probe | CLI Reference | Reference