dfuse reference

usage: dfuse [OPTIONS] [mountpoint [pool container]]

Options:

-m --mountpoint=<path>  Mount point to use (deprecated, use positional argument)

    --pool=name          pool UUID/label
    --container=name     container UUID/label
    --path=<path>        Path to load UNS pool/container data
    --sys-name=STR       DAOS system name context for servers

-S --singlethread       Single threaded
-t --thread-count=count Total number of threads to use
-e --eq-count=count     Number of event queues to use
-f --foreground         Run in foreground
    --enable-caching     Enable all caching (default)
    --enable-wb-cache    Use write-back cache rather than write-through (default)
    --disable-caching    Disable all caching
    --disable-wb-cache   Use write-through rather than write-back cache
-o options              mount style options string

    --multi-user         Run dfuse in multi user mode

-h --help               Show this help
-v --version            Show version

dfuse performs a user space mount of a DAOS POSIX container at the mountpoint directory that is specified as the first positional argument. This directory has to exist and has to be accessible to the user, or the mount will fail. Alternatively, the mountpoint directory can also be specified with the -m or --mountpoint= option but this usage is deprecated.

The DAOS pool and container can be specified in several different ways. Only one way of specifying the pool and container should be used:

  • The DAOS pool and container can be explicitly specified on the command line as positional arguments, using either UUIDs or labels. This is the most common way to use dfuse to mount a POSIX container.
  • The DAOS pool and container can be explicitly specified on the command line using the --pool and --container options, with either UUIDs or labels. This usage is deprecated in favor of using positional arguments.
  • When the --path option is used, DAOS namespace attributes are loaded from that filesystem path, including the DAOS pool and container information.
  • When the --path option is not used, then the mountpoint directory will also be checked and DAOS namespace attributes will be loaded from there if present.
  • When using the -o mount option string, pool= and container= keys in the mount option string identify the DAOS pool and container.

  • When the pool and container are not specified through any of these methods, dfuse will construct filesystem pathnames under the mountpoint by using the pool and container UUIDs (not labels) of all pools and POSIX containers to which the user running dfuse has access as pathname components.

    • A path to a POSIX container that is mounted this way can be traversed to access the root of that container, for example by changing directory to /mountpoint/pool_uuid/cont_uuid/.
    • However, listing the /mountpoint/ directory is not supported and will not show the pool UUIDs that are mounted there.
    • Similarly, while the user can change directory into a /mountpoint/pool_uuid/ directory, listing that directory is not supported and will not show the container UUIDs that are mounted there.
    • Running fusermount3 -u /mountpoint will unmount all POSIX containers that have been mounted this way, as well as the /mountpoint/pool_uuid/ directories.

Threading and resource usage:

dfuse has two types of threads: fuse threads which accept and process requests from the kernel, and progress threads which complete asynchronous read/write operations.

Each asynchronous progress thread uses one DAOS event queue to consume additional network resources. As all metadata operations are blocking, the level of concurrency in dfuse is limited by the number of fuse threads.

By default, the total thread count is one per available core to allow maximum throughput. If hyperthreading is enabled, then one thread per hyperthread core is used. This can be modified in two ways: Reducing the number of available cores by running dfuse in a cpuset via numactl or similar tools, or by using the --thread-count, --eq-count or --singlethread options:

  • The --thread-count option controls the total number of threads.
  • Increasing the --eq-count option at a fixed --thread-count will reduce the number of fuse threads accordingly. The default value for --eq-count is 1.
  • The --singlethread mode will use one thread for handling fuse requests and a second thread for a single event queue, for a total of two threads.

If dfuse is running in background mode (the default unless launched via mpirun) then it will stay in the foreground until the mount is registered with the kernel to allow appropriate error reporting.

The -o option can be used to run dfuse via fstab or similar and accepts standard mount options. This will be treated as a comma separated list of key=value pairs, and dfuse will use pool= and container= keys from this string.

Caching is on by default. The caching behavior for a dfuse mount can be controlled by command line options. Further caching controls can be set on a per-container basis through container attributes.

  • If the --disable-caching option is used then no caching will be performed, and the container attributes are not used. The default is --enable-caching.
  • If --disable-wb-cache is used then the write operations for the whole mount are performed in write-through mode, and the container attributes are still used. The default is --enable-wb-cache.
  • If --disable-caching and --enable-wb-cache are both specified, the --enable-wb-cache option is ignored and no caching is performed.