Skip to main content

AFS_AETHER_CONTROL_SOCKET

Deep-dive reference for:

  • AFS_AETHER_CONTROL_SOCKET

Status​

  • active-or-experimental

Audience​

  • production/user

Type and Default​

  • Type: filesystem path (PathBuf).
  • Default (when unset):
    • <cache>/<session>/content/locks/control.sock

where:

  • <cache> comes from AFS_AETHER_CACHE_DIR / aether.toml / CLI --cache-dir / cache defaults.
  • <session> is the resolved session ID for the running mount or command target.

What It Does​

Sets the local Unix domain socket path used for Aether runtime control IPC.

The running aether mount process listens on this socket, and other CLI commands connect to it to control/query that running mount.

Examples of control-socket backed commands:

  • aether stop
  • aether status
  • aether debug handles
  • aether debug sessions
  • aether trace capture
  • aether journal throttle
  • aether cache inspect / aether cache clear

Input Surfaces​

  • Env: AFS_AETHER_CONTROL_SOCKET=/path/to/control.sock
  • Config file (aether.toml): control_socket = "/path/to/control.sock"
  • CLI mount override: aether mount --control-socket /path/to/control.sock
  • CLI command target override: --socket /path/to/control.sock (for status/debug/cache/journal/trace/stop targeting flows)
    • Compatibility alias: --control-socket is also accepted for aether stop.

Resolution and Override Order​

Mount startup path resolution:

  1. Config defaults
  2. aether.toml
  3. Environment (AFS_AETHER_CONTROL_SOCKET)
  4. CLI aether mount --control-socket ...
  5. If still unset, derive default <cache>/<session>/content/locks/control.sock

Control command target resolution (status, debug, cache, journal, trace, stop):

  1. Command target --socket (or compatible stop alias)
  2. Resolved config control_socket
  3. Derived default from resolved cache/session

Socket Lifecycle and Permissions​

When the mount starts the control server:

  • Parent directory is created if needed.
  • Parent directory is tightened to 0700 on Unix (best effort).
  • Socket is bound and permissions are set to 0600.
  • If a stale socket file exists and no listener is reachable, Aether removes it.
  • If an active listener already exists at the same path, startup fails with socket-in-use.
  • On shutdown, Aether removes the socket file.

Platform Notes​

  • Implemented for Unix-domain sockets; non-Unix platforms return unsupported control-socket operations.
  • Runtime control server is Linux-targeted in mount wiring.

Operational Guidance​

  • Use defaults unless you have a concrete reason to pin a custom path (for example, integrating with external supervisors or running multiple explicit mount contexts).
  • If commands cannot reach a running mount, first verify both sides resolve to the same socket path.

Troubleshooting​

  • failed to connect to control socket ... no such file:
    • mount is not running, or command is targeting the wrong socket path.
  • permission denied:
    • caller UID cannot access socket or parent directory.
  • control socket already in use on mount startup:
    • another mount is already bound to that path, or stale permissions/path collision.

Primary Implementation Sources​

  • packages/aether/src/config/types/model_defaults.rs
  • packages/aether/src/config/types/file_config_loader.rs
  • packages/aether/src/config/types/apply_env.rs
  • packages/aether/src/config/types/config_resolution.rs
  • packages/aether/src/core/control/control_client.rs
  • packages/aether/src/mount/control.rs
  • packages/aether/src/mount/mount_fuse3.rs
  • packages/aether-cli/src/cli/args/cli_option_args.rs
  • packages/aether-cli/src/cli/args/cli_root_commands.rs
  • packages/aether-cli/src/app/dispatch_and_runtime.rs