Skip to main content

AFS_AETHER_SHUTDOWN_TIMEOUT_SECS

Deep-dive reference for:

  • AFS_AETHER_SHUTDOWN_TIMEOUT_SECS

Status​

  • active

Audience​

  • production/user

Type and Default​

  • Type: integer seconds (u64, must be > 0).
  • Default: 15 seconds.

What It Does​

Controls the graceful-shutdown budget for an aether mount process before forced shutdown behavior kicks in.

This timeout is used for:

  • shutdown controller force timer,
  • FUSE session unmount and control-server cleanup budget,
  • runtime/cache/component cleanup timeout budget.

Input Surfaces​

  • Env: AFS_AETHER_SHUTDOWN_TIMEOUT_SECS=<seconds>
  • Config file (aether.toml): shutdown_timeout_secs = <seconds>
  • CLI override: aether mount --shutdown-timeout-secs <seconds>

Resolution and Override Order​

  1. Built-in default (15s)
  2. aether.toml (shutdown_timeout_secs)
  3. Env (AFS_AETHER_SHUTDOWN_TIMEOUT_SECS)
  4. CLI (--shutdown-timeout-secs)

Validation and Failure Behavior​

  • Must parse as integer seconds.
  • Must be greater than 0.
  • 0 is rejected for env/config/CLI inputs with a validation error.

Implementation includes a defensive internal fallback to 5s if a zero duration ever appears programmatically, but normal config paths reject zero.

Runtime Shutdown Flow​

During shutdown:

  • First shutdown signal/request starts graceful shutdown and starts the force timer.
  • Second signal reports "still shutting down" state.
  • Third signal (or later) forces immediate shutdown without waiting for the timer.
  • If graceful shutdown exceeds timeout, forced shutdown is triggered automatically.

Forced shutdown path:

  • Attempts forced detach via umount2(MNT_FORCE|MNT_DETACH).
  • Falls back to fusermount3/fusermount (-u -q -z) if needed.

Operational Guidance​

  • Lower values speed up stuck-shutdown recovery but increase risk of aggressive forced unmount.
  • Higher values allow more graceful draining/flush time but keep shutdown waiting longer when stuck.
  • Default 15s is a balanced production setting.

Quick Examples​

  • One-shot shorter timeout:
    • AFS_AETHER_SHUTDOWN_TIMEOUT_SECS=5 aether mount --session-id s1 --mount-dir /mnt/s1
  • Config file:
    • shutdown_timeout_secs = 20
  • CLI one-off:
    • aether mount --shutdown-timeout-secs 8 --session-id s1 --mount-dir /mnt/s1

Primary Implementation Sources​

  • 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/shutdown.rs
  • packages/aether/src/mount/mount_fuse3.rs
  • packages/aether/src/mount/mount_main.rs