88 lines
4.0 KiB
Markdown
88 lines
4.0 KiB
Markdown
# Configuration Durations
|
|
|
|
Agent and control-plane TOML duration settings use strings with explicit units.
|
|
Runtime code receives `std::time::Duration`; API and WebSocket numeric fields
|
|
such as `timeout_ms`, `session_ttl_seconds`, and `latency_ms` are unchanged.
|
|
|
|
## Agent
|
|
|
|
```toml
|
|
reconnect_base = "1s"
|
|
reconnect_max = "30s"
|
|
observation_sync_interval = "60s"
|
|
observation_retention = "7d"
|
|
|
|
[terminal]
|
|
session_ttl = "12h"
|
|
```
|
|
|
|
`observation_retention` prunes the agent's local hotplug memory during inventory
|
|
collection. It does not delete the control plane's last snapshot for an agent.
|
|
`"0d"` disables this local pruning. `terminal.session_ttl = "0s"` disables PTY
|
|
expiry. Reconnect and sync timers must be positive and fit the platform timer.
|
|
Terminal TTL and hook retention must resolve to whole seconds because their
|
|
protocol/storage timestamps use seconds. Reconnect and sync intervals can use
|
|
subsecond values.
|
|
Reconnect scheduling retains its existing 100ms minimum backoff.
|
|
|
|
## Control Plane
|
|
|
|
```toml
|
|
command_timeout = "30s"
|
|
enroll_token_ttl = "1d"
|
|
history_retention = "30d"
|
|
device_retention = "60d"
|
|
```
|
|
|
|
All three settings must be positive. Enrollment TTL and history retention must
|
|
resolve to whole seconds. Command timeout can use subsecond values.
|
|
`history_retention` deletes old audit events and alert transitions, not device
|
|
snapshots or saved identities.
|
|
|
|
`device_retention` expires agent-collected device rows and their child endpoints,
|
|
addresses, names and facts. The default is `"60d"`; `"0d"` disables expiry.
|
|
It must resolve to whole seconds. Age is measured from the last CC-received
|
|
snapshot that included the device, not endpoint timestamps or online presence.
|
|
An offline device included in new snapshots therefore stays retained. Saved
|
|
devices and their manually attached identifiers are never deleted by this cleanup.
|
|
Complete snapshots still remove devices omitted by that agent immediately;
|
|
retention handles old rows left behind when an agent stops syncing.
|
|
Expired rows are removed by the Unix daemon's existing maintenance loop every
|
|
five minutes, including an initial tick at startup. Restart CC to apply changes
|
|
to this setting; the state-only reload does not reload configuration.
|
|
|
|
## Legacy Files
|
|
|
|
| Old Key | New Key | Numeric Legacy Unit |
|
|
| --- | --- | --- |
|
|
| Agent `reconnect_base_ms` | `reconnect_base` | milliseconds |
|
|
| Agent `reconnect_max_ms` | `reconnect_max` | milliseconds |
|
|
| Agent `observation_sync_interval_seconds` | `observation_sync_interval` | seconds |
|
|
| Agent `observation_retention_days` | `observation_retention` | days |
|
|
| Agent `terminal.session_ttl_seconds` | `terminal.session_ttl` | seconds |
|
|
| CC `command_timeout_ms` | `command_timeout` | milliseconds |
|
|
| CC `enroll_token_ttl_seconds` | `enroll_token_ttl` | seconds |
|
|
| CC `observation_retention_seconds` | `history_retention` | seconds |
|
|
|
|
Old keys accept non-negative integers in their original units, or explicit
|
|
duration strings, and produce a warning on stderr when loaded. New keys require
|
|
strings; bare numbers are rejected. Supplying both keys for the same setting is
|
|
an error, even when their values agree. Negative, malformed, and overflowing
|
|
values are rejected; zero active timers are rejected rather than silently
|
|
clamped. No secrets are included in deprecation warnings.
|
|
|
|
`init-config --from-config ...` reads legacy files and writes only canonical
|
|
keys and formatted duration strings. Existing numeric CLI flags are unchanged
|
|
in this slice, and their overrides also serialize in the new format.
|
|
|
|
For example, legacy `reconnect_base_ms = 1500` is read as 1500 milliseconds
|
|
and written back as `reconnect_base = "1s 500ms"`. New-key
|
|
`reconnect_base = 1500` is rejected: no implicit numeric unit is assigned.
|
|
Serialization always writes duration strings, regardless of the accepted input
|
|
format, using `humantime-serde`.
|
|
|
|
The parser is [humantime](https://docs.rs/humantime/latest/humantime/fn.parse_duration.html).
|
|
Examples include `"14d"`, `"168h"`, `"250ms"`, and `"1h 30m"`. These are elapsed
|
|
durations, not calendar scheduling rules; use days/hours for retention rather
|
|
than assuming calendar-month semantics.
|