Skip to main content

AFS_AETHER_MOUNT_OPTIONS

Deep-dive reference for:

  • AFS_AETHER_MOUNT_OPTIONS

Status​

  • active

Audience​

  • production/user

Type and Default​

  • Type: list of mount-option tokens.
  • Default: empty list ([]).

Scope​

  • Consumed by local Aether mount startup (aether mount) on Linux/fuse3.
  • Not a global server setting.
  • Applied at mount startup; existing mounts do not hot-reload this setting.

Input Surfaces​

  • Env: AFS_AETHER_MOUNT_OPTIONS="token1,token2,token3".
  • Config file: mount_options = ["token1", "token2"] in aether.toml.
  • CLI: repeat --mount-option, for example:
    • aether mount --mount-option allow_other --mount-option max_pages=256

Resolution and Override Order​

  • Defaults < aether.toml < environment < CLI.
  • Higher-priority sources replace lower-priority lists (they are not merged).
  • Same-key duplicates: last token wins.
  • custom_option / custom: additive (each token appends another raw -o option).

Token Parsing Rules​

  • Env form splits on commas.
  • Whitespace is trimmed.
  • Empty tokens are ignored.
  • Key matching is case-insensitive.
  • Key normalization converts - to _.

Example equivalence:

  • no-open-dir-support == no_open_dir_support

Boolean Forms​

  • flag => flag=true
  • flag=true|false|1|0|yes|no|on|off
  • no_flag => flag=false
  • no_flag=<value> is invalid

Validation and Error Handling​

  • Validation occurs in aether before mount options are handed to fuse3.
  • Unknown tokens are ignored with warnings.
  • Malformed tokens are ignored with warnings.
  • Numeric parsing is strict by expected type:
    • u16, u32, u64, usize
  • rootmode accepts:
    • decimal
    • hex (0x...)
    • octal (0o...)

Baseline Before Tokens​

  • Aether starts with fuse3-safe defaults, then applies validated tokens.
  • Baseline includes:
    • default_permissions=true
    • fs_name="aetherfs"
    • allow_other from the main mount setting (--allow-other / config file), before token overrides
    • writeback fallback logic based on writeback_cache_mode (--writeback-cache / config file)

Important Interactions and Precedence​

  • allow_other=true|false token can override the baseline allow_other mount setting.
  • write_back=true|false token has highest precedence for writeback-cache request.
  • If no write_back token is present, Aether falls back to:
    1. writeback_cache_mode=off => disable
    2. writeback_cache_mode=on => enable
    3. writeback_cache_mode=auto => enable only when kernel capability probe marks big_writes as supported.
  • custom_option=<value> appends raw option text; repeated entries all apply in order.

Capability Negotiation Model​

  • Init/capability-oriented tokens are capability requests.
  • Unsupported kernel capabilities are not negotiated.
  • Effective behavior is the intersection of:
    • token intent,
    • init flag toggles,
    • kernel-supported FUSE flags.

Supported Core Boolean Tokens​

  • allow_other: allow access by users other than the mounting user.
  • allow_root: allow access by root in addition to the mounting user.
  • read_only / ro: request read-only mount semantics.
  • nonempty: allow mounting over a non-empty mountpoint.
  • default_permissions: kernel permission checks.
  • dont_mask: request FUSE_DONT_MASK behavior (with init_dont_mask).
  • no_open_support: request zero-message open support.
  • no_open_dir_support / no_opendir_support: request zero-message opendir support.
  • handle_killpriv: request killpriv behavior on write/chown/truncate paths.
  • write_back / writeback / writeback_cache: request writeback cache.
  • force_readdir_plus: force readdirplus-only mode.
  • async_read / init_async_read: toggle async-read capability.
  • passthrough: request FUSE passthrough mode (kernel/userland prerequisites apply).

Supported init_* Boolean Tokens​

  • init_file_ops
  • init_atomic_o_trunc
  • init_export_support
  • init_big_writes
  • init_dont_mask
  • init_splice_write
  • init_splice_move
  • init_splice_read
  • init_auto_inval_data
  • init_do_readdirplus
  • init_readdirplus_auto
  • init_async_dio
  • init_writeback_cache
  • init_parallel_dirops
  • init_handle_killpriv
  • init_posix_acl
  • init_max_pages
  • init_cache_symlinks
  • init_no_open_support
  • init_no_open_dir_support

Supported Value Tokens​

  • uid=<u32>: explicit mount user id.
  • gid=<u32>: explicit mount group id.
  • fs_name=<string> / fsname=<string>: visible fs name.
  • rootmode=<u32>: root inode mode bits (decimal/hex/octal).
  • max_pages=<u16>: max pages per request when FUSE_MAX_PAGES is negotiated.
  • operation_timeout_ms=<u64>: fuse3 operation-timeout value (0 disables timeout in apply path).
  • max_concurrent_ops=<usize>: data-path concurrency cap (clamped to 8..=4096 by fuse3).
  • control_plane_permits=<usize>: reserved control-plane permits (clamped to 4..=64 by fuse3).
  • custom_option=<text> / custom=<text>: append raw fuse -o option text.

Edge Cases and Clamping​

  • max_concurrent_ops and control_plane_permits are clamped by fuse3.
  • Repeated custom_option tokens append in order.
  • Env form splits on commas, so one custom_option value cannot carry embedded commas.
  • If embedded commas are needed, use CLI/config array token forms.
  • Any token not recognized by the validator never reaches fuse3 option construction.

Worked Examples​

  • Conservative read-only:
    • AFS_AETHER_MOUNT_OPTIONS="ro,default_permissions,no_write_back,no_force_readdir_plus"
  • Throughput-oriented:
    • AFS_AETHER_MOUNT_OPTIONS="write_back,init_writeback_cache,max_pages=256,max_concurrent_ops=1024,control_plane_permits=32"
  • Explicit identity + custom option:
    • AFS_AETHER_MOUNT_OPTIONS="uid=1000,gid=1000,fs_name=aetherfs-dev,custom_option=auto_unmount"

Primary Implementation Sources​

  • packages/aether/src/mount/flags.rs
  • packages/aether/src/mount/mount_main.rs
  • packages/aether/src/config/types/parse_helpers.rs
  • packages/aether/src/config/types/config_resolution.rs
  • packages/afs-fuse3/src/mount/mounted_session.rs