Skip to main content

AFS_AETHER_CONFIG

Deep-dive reference for:

  • AFS_AETHER_CONFIG

Status​

  • active

Audience​

  • production/user

Type and Default​

  • Type: filesystem path to a TOML config file.
  • Default: unset.
  • Loader fallback when unset: ./aether.toml if present.

What It Does​

Selects which aether.toml file Aether should load at startup.

This variable chooses the config file location; it is not a runtime behavior knob by itself.

Input Surfaces​

  • Env:
    • AFS_AETHER_CONFIG=/path/to/aether.toml
  • CLI:
    • aether --config /path/to/aether.toml ...

There is no aether.toml field for this setting (a config file cannot point to itself).

Resolution and Override Order​

For config loading:

  1. CLI --config (ConfigOverrides.config_path)
  2. Env AFS_AETHER_CONFIG
  3. Implicit ./aether.toml if it exists
  4. Otherwise: run with built-in defaults + other env/CLI overrides

Notes:

  • CLI --config wins over AFS_AETHER_CONFIG when both are set.
  • AFS_AETHER_CONFIG is intentionally skipped during env application (it only selects file path).

Missing File Behavior​

  • If path is explicitly provided (CLI --config or AFS_AETHER_CONFIG) and does not exist:
    • startup fails with ConfigFileNotFound.
  • If no explicit path is provided and ./aether.toml is absent:
    • no error; Aether continues with defaults/env/CLI overrides.

Parse and Validation Behavior​

  • File must parse as TOML and match the allowed schema (deny_unknown_fields in loader structs).
  • Parse errors fail startup.
  • Value-level validation errors (for fields inside the file) fail startup with field-specific errors.

Relationship to Config-Editing Commands​

Commands that persist tunables (for example prefetch/journal/fallback tuning flows) resolve target config path with the same precedence intent:

  1. CLI --config
  2. AFS_AETHER_CONFIG
  3. ./aether.toml

Those commands may create aether.toml when needed.

Operational Guidance​

  • For production services/wrappers, set an explicit config path (CLI or env) to avoid cwd-dependent behavior.
  • Prefer absolute paths in automation.
  • Keep one config file per environment/profile (dev/staging/prod) and select via --config or this env var.

Quick Examples​

  • Use env-selected config:
    • AFS_AETHER_CONFIG=/etc/aetherfs/aether.toml aether mount --session-id s1 --mount-dir /mnt/s1
  • Use explicit CLI config (overrides env):
    • aether --config /opt/aetherfs/aether-prod.toml mount --session-id s1 --mount-dir /mnt/s1
  • Inspect resolved config-derived metrics address:
    • aether --config /opt/aetherfs/aether-prod.toml metrics show

Primary Implementation Sources​

  • packages/aether/src/config/env/env_keys.rs
  • packages/aether/src/config/types/file_config_loader.rs
  • packages/aether/src/config/types/apply_env.rs
  • packages/aether/src/config/types/model_defaults.rs
  • packages/aether-cli/src/cli/args/cli_root_commands.rs
  • packages/aether-cli/src/app/fuse_and_journal_helpers.rs