107 lines
6.1 KiB
Markdown
107 lines
6.1 KiB
Markdown
# RVBox v1 configuration contract
|
|
|
|
RVBox v1 uses TOML 1.0 for daemon configuration. The normative annotated
|
|
examples are [`examples/server.toml`](examples/server.toml) and
|
|
[`examples/client.toml`](examples/client.toml). They list every supported v1
|
|
knob, with the routing, persistence, and safety limits first in each section.
|
|
The runnable Windows-first deployment example is
|
|
[`examples/client.windows.toml`](examples/client.windows.toml); omitted entries
|
|
use the defaults documented by the all-knob client reference.
|
|
|
|
## Loading and precedence
|
|
|
|
- `rvbox-server --config PATH` and `rvbox --config PATH` load one UTF-8 TOML
|
|
file. There is no implicit merge, runtime rewrite, or hot reload in v1.
|
|
On Windows, the SCM service command line holds the canonical explicit config
|
|
path; omitting it during installation selects the resolved
|
|
`%ProgramData%\RVBox\client.toml`; first run creates its annotated template
|
|
and the service reports not-ready until routing is valid rather than
|
|
connecting to a placeholder server.
|
|
- Precedence is compiled default, then TOML, then an explicitly supplied CLI
|
|
flag. Flags exist for operationally important scalar keys; they use the same
|
|
validation as TOML. RVBox does not implicitly import configuration from
|
|
environment variables.
|
|
- Unknown keys, duplicate keys/tables, type mismatches, invalid UTF-8, and
|
|
values outside documented ranges are startup errors. Parsing never silently
|
|
substitutes a default for a present invalid value.
|
|
- Durations are quoted Go-style duration strings such as `"250ms"`, `"15m"`,
|
|
and `"720h"`. Byte sizes and counts are base-10 TOML integers whose values are
|
|
bytes; comments show the equivalent binary unit. URLs and paths are strings.
|
|
- Relative paths are rejected for state, socket, CA, shell-executable, and
|
|
allowed-CWD-root fields. `client.daemon_cwd` is resolved once at startup and
|
|
then stored and advertised as an absolute path. On Unix it is the omitted-CWD
|
|
default; on Windows it is the protected parent under which the service creates
|
|
an ACL-isolated default directory for the selected execution identity. The
|
|
annotated client example uses Unix paths; a Windows deployment replaces
|
|
`state_dir`, `daemon_cwd`, and relevant shell paths with absolute Windows
|
|
paths. Shell fields for the other platform are syntax-checked but not resolved
|
|
or advertised.
|
|
- The daemon prints its effective configuration after validation, with no
|
|
command data or TLS material. Since v1 stores command/environment payloads in
|
|
plaintext, configuration output is hygiene rather than a secrecy guarantee.
|
|
|
|
## Limits and cross-field validation
|
|
|
|
Configuration may lower protocol and storage limits, but may not raise a hard
|
|
wire ceiling above the v1 values in the examples. For every high/low watermark,
|
|
`0 < low < high`; send windows must fit below their corresponding durable quota.
|
|
The 64 KiB command closeout reserve must fit within the command quota, and the
|
|
command quota must fit within the client and server tiers. Queue and byte counts
|
|
must be positive except where a comment explicitly gives zero a disabling or
|
|
indefinite meaning. `queue.max_per_client` may not exceed `queue.max_server`.
|
|
|
|
The server must reject external JSON-RPC binds unless `json_rpc.enabled=true`.
|
|
Any enabled non-loopback bind produces a conspicuous warning but is permitted by
|
|
the accepted v1 debugging contract. The control Unix socket always uses mode
|
|
`0600`; it is not a configurable relaxation.
|
|
|
|
Windows automatic start is SCM state, not TOML state. Installation registers
|
|
the machine-wide service as Automatic; an administrator may change it to Manual
|
|
through the tray or normal service-management tools. RVBox has no
|
|
`windows.start_on_boot` key and never attempts to reconcile two sources of
|
|
truth. The optional per-user tray uses the installer-created logon registration
|
|
and is never required for service readiness or command execution.
|
|
|
|
## Shell executable resolution
|
|
|
|
Each `ShellType` maps to one startup-validated absolute executable path from
|
|
`[shells]`. The client canonicalizes the path, verifies that it names an
|
|
executable regular file appropriate to the platform, and advertises only shells
|
|
that passed validation. The configured platform default must be one of those
|
|
shells. There is no fallback.
|
|
|
|
The resolved executable is independent of a command's `PATH` override. For
|
|
example, a request for `SHELL_BASH` still launches the validated `/bin/bash`
|
|
even when the request contains `PATH=/tmp/untrusted`; it never searches that
|
|
directory for another `bash`. An administrator may intentionally select another
|
|
implementation, such as an absolute `pwsh.exe` path for `SHELL_POWERSHELL`, but
|
|
the selection remains fixed until daemon restart.
|
|
|
|
Command text and uploaded scripts are written to generated wrapper paths and
|
|
passed to exactly this executable. The user-supplied script filename is display
|
|
metadata only.
|
|
|
|
## Resource-profile composition
|
|
|
|
`LIGHT` is exclusive. Otherwise, a request may combine at most one CPU tier,
|
|
one memory tier, and one disk tier. Thus `CPU_HEAVY + MEM_MEDIUM` is valid, while
|
|
`CPU_MEDIUM + CPU_HEAVY` and `LIGHT + MEM_HEAVY` are invalid. A configured
|
|
profile declares which controls are required. If the platform cannot apply a
|
|
required control atomically before launch, the command is terminal `REJECTED`.
|
|
|
|
Profile names describe administrator-defined allowance classes: a `HEAVY` tier
|
|
normally permits more resources than `MEDIUM`; RVBox does not invent numeric
|
|
values. Zero for an individual numeric limit means that control is not requested
|
|
by that profile, but every name in `required_controls` must have a nonzero,
|
|
platform-applicable value. Linux disk limits use configured cgroup device
|
|
major/minor keys. Windows applies the equivalent whole-Job rate control and
|
|
ignores Linux device maps only when disk control is not declared required.
|
|
|
|
## Validation ownership
|
|
|
|
`internal/config` owns TOML DTOs, strict decoding, default application, flag
|
|
overrides, canonicalization, and cross-field validation. It converts the parsed
|
|
form into immutable domain configuration before listeners or child processes
|
|
start. Network, storage, and supervisor packages receive only their relevant
|
|
validated sub-configuration and never parse TOML themselves.
|