Skip to main content

AFS_AETHER_READ_ONLY

Deep-dive reference for:

  • AFS_AETHER_READ_ONLY

Status​

  • active

Audience​

  • production/user

Type and Default​

  • Type: boolean.
  • Default: false (unset).

Accepted truthy values:

  • true, 1, yes, y, on

Accepted falsey values:

  • false, 0, no, n, off

What It Does​

Forces Aether session capabilities into read-only mode at mount startup.

When enabled, mutation paths are rejected and the mount behaves as read-only from the runtime side.

Input Surfaces​

  • Env: AFS_AETHER_READ_ONLY=true
  • Config file (aether.toml): read_only = true
  • CLI override: aether mount --read-only

Note: --read-only is a one-way flag (enable only). There is no --read-only=false.

Resolution and Override Order​

  1. Built-in default (false)
  2. aether.toml (read_only)
  3. Env (AFS_AETHER_READ_ONLY)
  4. CLI/internal override layer (ConfigOverrides.read_only) when set

For normal CLI usage this is effectively:

  • default < config file < env < --read-only (enable only)

Runtime Behavior​

When read-only is enabled:

  • Session capability controller is initialized with read_only=true.
  • Local mutation operations are rejected with read-only errors (EROFS) across paths including:
    • create/mkdir/mknod
    • unlink/rmdir/rename
    • symlink/link/fallocate
    • mutation setattr fields (mode/uid/gid/size)
    • write-intent opens (O_WRONLY / O_RDWR / append / truncation)
  • Read paths remain available.
  • Mount startup does not wire writeback sink/lease manager (writeback_enabled=false when read-only).

Difference vs AFS_AETHER_MOUNT_OPTIONS=ro​

  • AFS_AETHER_READ_ONLY controls Aether runtime/session mutation capability.
  • AFS_AETHER_MOUNT_OPTIONS read_only/ro is a mount-option token path.
  • They are separate controls; use AFS_AETHER_READ_ONLY when you need runtime-enforced read-only behavior.

Validation and Failure Behavior​

  • Invalid env boolean values fail config load (invalid value for AFS_AETHER_READ_ONLY).
  • Config file values must parse as TOML booleans; invalid values fail config-file parsing.

Reload Semantics​

  • On config reload (SIGHUP), changing read_only is detected but logged as restart-required.
  • Existing mounts should be restarted for deterministic effect from config/env changes.

Operational Guidance​

  • Use this as a safety switch for browse/audit sessions where mutation must be blocked.
  • Keep disabled for normal write-capable development sessions.
  • If you need a read-only one-off invocation, prefer CLI:
    • aether mount --read-only ...

Quick Examples​

  • One-shot via env:
    • AFS_AETHER_READ_ONLY=true aether mount --session-id s1 --mount-dir /mnt/s1
  • Config file:
    • read_only = true
  • CLI one-off:
    • aether mount --read-only --session-id s1 --mount-dir /mnt/s1

Primary Implementation Sources​

  • packages/aether/src/config/env/env_keys.rs
  • packages/aether/src/config/types/model_defaults.rs
  • packages/aether/src/config/types/apply_env.rs
  • packages/aether/src/config/types/file_config_loader.rs
  • packages/aether/src/config/types/config_resolution.rs
  • packages/aether-cli/src/cli/args/cli_option_args.rs
  • packages/aether-cli/src/cli/args/cli_root_commands.rs
  • packages/aether/src/mount/config.rs
  • packages/aether/src/mount/mount_main.rs
  • packages/aether/src/state/session.rs
  • packages/aether/src/engine/errors.rs
  • packages/aether/src/engine/local/file_ops.rs
  • packages/aether/src/engine/local/special_ops.rs
  • packages/aether/src/engine/local/metadata.rs
  • packages/aether/src/config/reload.rs