Skip to main content

muti-metroo config

Inspect a configuration without starting an agent. Both subcommands accept either a YAML file or a Muti Metroo binary with an embedded configuration. A path ending in .yaml or .yml is read as YAML; any other path is first checked for an embedded configuration and then read as YAML.

Global flags (--token, --yes, --no-color) are described in CLI overview.

config validate​

muti-metroo config validate <path> [flags]

Parse the configuration and run the same validation the agent runs at startup: schema, key formats, listener and peer settings, CIDR, domain, and hostname values, and management key consistency. Environment variable references are expanded from the current environment first, so validate in the same environment the agent will run in.

Flags​

FlagDefaultDescription
--jsonfalsePrint the result as a JSON object instead of text.

Output​

On success, the text output names the source:

OK: config.yaml (file)
OK: /usr/local/bin/my-agent (embedded in binary)

On failure, the error lists every problem found:

Error: config validation failed: validation errors:
  - listeners[0]: invalid transport: carrier-pigeon (must be quic, h2, or ws)

With --json, the object has path and ok, plus embedded on success or error on failure:

{
  "embedded": false,
  "ok": true,
  "path": "config.yaml"
}
{
  "error": "config validation failed: validation errors:\n  - listeners[0]: invalid transport: carrier-pigeon (must be quic, h2, or ws)",
  "ok": false,
  "path": "config.yaml"
}

Exit status​

0 if the configuration is valid, 2 if it parses but fails validation, 1 if the file cannot be read. The same codes apply with --json, which also reports the outcome in the ok field.

Examples​

muti-metroo config validate ./config.yaml
muti-metroo config validate /usr/local/bin/my-agent

Fail a CI job on an invalid configuration:

muti-metroo config validate --json ./config.yaml | jq -e '.ok'

config show​

muti-metroo config show [<path>] [flags]

Print the effective configuration: the file with built-in defaults filled in and environment variable references expanded. <path> defaults to ./config.yaml.

Secrets are replaced with <redacted> when set and left empty when not, so the output shows whether a secret is configured without revealing it. Redacted keys:

  • agent.private_key
  • tls.key, tls.key_pem, and the same keys in per-listener and per-peer tls blocks
  • peers[].proxy_auth.password
  • socks5.auth.users[].password, socks5.auth.users[].password_hash
  • http.token_hash
  • management.private_key, management.signing_private_key

Flags​

FlagDefaultDescription
--diff-from-defaultfalsePrint only the keys whose values differ from the built-in defaults.
--jsonfalsePrint JSON instead of YAML.

Examples​

Show only what a configuration changes from the defaults:

muti-metroo config show ./config.yaml --diff-from-default
agent:
  display_name: gateway-1
http:
  address: 127.0.0.1:8080
  enabled: true
  token_hash: <redacted>
listeners:
  - address: 0.0.0.0:4433
    transport: quic
socks5:
  address: 127.0.0.1:1080
  enabled: true

Compare the effective settings of two deployments:

diff <(muti-metroo config show site-a.yaml --diff-from-default) \
     <(muti-metroo config show site-b.yaml --diff-from-default)

Inspect the configuration embedded in a binary:

muti-metroo config show /usr/local/bin/my-agent

Exit status​

0 on success, 2 if the configuration parses but fails validation, 1 if it cannot be read.

See Also​