fsconfig - configure new or existing filesystem context

#include <sys/mount.h>
int fsconfig(int fd, unsigned int cmd,
 const char *_Nullable key,
 const void *_Nullable value, int aux);

The fsconfig() system call is part of the suite of file-descriptor-based mount facilities in Linux.

fsconfig() is used to supply parameters to and issue commands against the filesystem configuration context associated with the file descriptor fd. Filesystem configuration contexts can be created with fsopen(2) or be instantiated from an extant filesystem instance with fspick(2).

The cmd argument indicates the command to be issued. Some commands supply parameters to the context (equivalent to mount options specified with mount(8)), while others are meta-operations on the filesystem context. The list of valid cmd values are:

FSCONFIG_SET_FLAG

Set the flag parameter named by key. value must be NULL, and aux must be 0.

FSCONFIG_SET_STRING

Set the string parameter named by key to the value specified by value. value points to a null-terminated string, and aux must be 0.

FSCONFIG_SET_BINARY

Set the blob parameter named by key to the contents of the binary blob specified by value. value points to the start of a buffer that is aux bytes in length.

FSCONFIG_SET_FD

Set the file parameter named by key to the open file description referenced by the file descriptor aux. value must be NULL.

You may also use FSCONFIG_SET_STRING for file parameters, with value set to a null-terminated string containing a base-10 representation of the file descriptor number. This mechanism is primarily intended for compatibility with older mount(2)-based programs, and only works for parameters that only accept file descriptor arguments.

FSCONFIG_SET_PATH

Set the path parameter named by key to the object at a provided path, resolved in a similar manner to openat(2). value points to a null-terminated pathname string, and aux is equivalent to the dirfd argument to openat(2). See openat(2) for an explanation of the need for FSCONFIG_SET_PATH.

You may also use FSCONFIG_SET_STRING for path parameters, the behavior of which is equivalent to FSCONFIG_SET_PATH with aux set to AT_FDCWD.

FSCONFIG_SET_PATH_EMPTY

As with FSCONFIG_SET_PATH, except that if value is an empty string, the file descriptor specified by aux is operated on directly and may be any type of file (not just a directory). This is equivalent to the behavior of AT_EMPTY_PATH with most "*at()" system calls. If aux is AT_FDCWD, the parameter will be set to the current working directory of the calling process.

FSCONFIG_CMD_CREATE

This command instructs the filesystem driver to instantiate an instance of the filesystem in the kernel with the parameters specified in the filesystem configuration context. key and value must be NULL, and aux must be 0.

This command can only be issued once in the lifetime of a filesystem context. If the operation succeeds, the filesystem context associated with file descriptor fd now references the created filesystem instance, and is placed into a special "awaiting-mount" mode that allows you to use fsmount(2) to create a mount object from the filesystem instance. If the operation fails, in most cases the filesystem context is placed in a failed mode and cannot be used for any further fsconfig() operations (though you may still retrieve diagnostic messages through the message retrieval interface, as described in the corresponding subsection of fsopen(2)).

This command can only be issued against filesystem configuration contexts that were created with fsopen(2). In order to create a filesystem instance, the calling process must have the CAP_SYS_ADMIN capability.

An important thing to be aware of is that the Linux kernel will silently reuse extant filesystem instances depending on the filesystem type and the configured parameters (each filesystem driver has its own policy for how filesystem instances are reused). This means that the filesystem instance "created" by FSCONFIG_CMD_CREATE may, in fact, be a reference to an extant filesystem instance in the kernel. (For reference, this behavior also applies to mount(2).)

One side-effect of this behavior is that if an extant filesystem instance is reused, all parameters configured for this filesystem configuration context are silently ignored (with the exception of the ro and rw flag parameters; if the state of the read-only flag in the extant filesystem instance and the filesystem configuration context do not match, this operation will return EBUSY). This also means that FSCONFIG_CMD_RECONFIGURE commands issued against the "created" filesystem instance will also affect any mount objects associated with the extant filesystem instance.

Programs that need to ensure that they create a new filesystem instance with specific parameters (notably, security-related parameters such as acl to enable POSIX ACLs— as described in acl(5)) should use FSCONFIG_CMD_CREATE_EXCL instead.

FSCONFIG_CMD_CREATE_EXCL (since Linux 6.6)

As with FSCONFIG_CMD_CREATE, except that the kernel is instructed to not reuse extant filesystem instances. If the operation would be forced to reuse an extant filesystem instance, this operation will return EBUSY instead.

As a result (unlike FSCONFIG_CMD_CREATE), if this operation succeeds then the calling process can be sure that all of the parameters successfully configured with fsconfig() will actually be applied to the created filesystem instance.

FSCONFIG_CMD_RECONFIGURE

This command instructs the filesystem driver to apply the parameters specified in the filesystem configuration context to the extant filesystem instance referenced by the filesystem configuration context. key and value must be NULL, and aux must be 0.

This is primarily intended for use with fspick(2), but may also be used to modify the parameters of a filesystem instance after FSCONFIG_CMD_CREATE was used to create it and a mount object was created using fsmount(2). In order to reconfigure an extant filesystem instance, the calling process must have the CAP_SYS_ADMIN capability.

If the operation succeeds, the filesystem context is reset but remains in reconfiguration mode and thus can be reused for subsequent FSCONFIG_CMD_RECONFIGURE commands. If the operation fails, in most cases the filesystem context is placed in a failed mode and cannot be used for any further fsconfig() operations (though you may still retrieve diagnostic messages through the message retrieval interface, as described in the corresponding subsection of fsopen(2)).

Parameters specified with FSCONFIG_SET_* do not take effect until a corresponding FSCONFIG_CMD_CREATE or FSCONFIG_CMD_RECONFIGURE command is issued.

On success, fsconfig() returns 0. On error, -1 is returned, and errno is set to indicate the error.

To illustrate the different kinds of flags that can be configured with fsconfig(), here are a few examples of some different filesystems being created:

int fsfd, mntfd;
fsfd = fsopen("tmpfs", FSOPEN_CLOEXEC);
fsconfig(fsfd, FSCONFIG_SET_FLAG, "inode64", NULL, 0);
fsconfig(fsfd, FSCONFIG_SET_STRING, "uid", "1234", 0);
fsconfig(fsfd, FSCONFIG_SET_STRING, "huge", "never", 0);
fsconfig(fsfd, FSCONFIG_SET_FLAG, "casefold", NULL, 0);
fsconfig(fsfd, FSCONFIG_CMD_CREATE, NULL, NULL, 0);
mntfd = fsmount(fsfd, FSMOUNT_CLOEXEC, MOUNT_ATTR_NOEXEC);
move_mount(mntfd, "", AT_FDCWD, "/tmp", MOVE_MOUNT_F_EMPTY_PATH);
fsfd = fsopen("erofs", FSOPEN_CLOEXEC);
fsconfig(fsfd, FSCONFIG_SET_STRING, "source", "/dev/loop0", 0);
fsconfig(fsfd, FSCONFIG_SET_FLAG, "acl", NULL, 0);
fsconfig(fsfd, FSCONFIG_SET_FLAG, "user_xattr", NULL, 0);
fsconfig(fsfd, FSCONFIG_CMD_CREATE_EXCL, NULL, NULL, 0);
mntfd = fsmount(fsfd, FSMOUNT_CLOEXEC, MOUNT_ATTR_NOSUID);
move_mount(mntfd, "", AT_FDCWD, "/mnt", MOVE_MOUNT_F_EMPTY_PATH);

Usually, specifying the same parameter named by key multiple times with fsconfig() causes the parameter value to be replaced. However, some filesystems may have unique behavior:

int fsfd, mntfd;
int lowerdirfd = open("/o/ctr/lower1", O_DIRECTORY | O_CLOEXEC);
fsfd = fsopen("overlay", FSOPEN_CLOEXEC);
/* "lowerdir+" appends to the lower dir stack each time */
fsconfig(fsfd, FSCONFIG_SET_FD, "lowerdir+", NULL, lowerdirfd);
fsconfig(fsfd, FSCONFIG_SET_STRING, "lowerdir+", "/o/ctr/lower2", 0);
fsconfig(fsfd, FSCONFIG_SET_STRING, "lowerdir+", "/o/ctr/lower3", 0);
fsconfig(fsfd, FSCONFIG_SET_STRING, "lowerdir+", "/o/ctr/lower4", 0);
fsconfig(fsfd, FSCONFIG_SET_STRING, "xino", "auto", 0);
fsconfig(fsfd, FSCONFIG_SET_STRING, "nfs_export", "off", 0);
fsconfig(fsfd, FSCONFIG_CMD_CREATE, NULL, NULL, 0);
mntfd = fsmount(fsfd, FSMOUNT_CLOEXEC, 0);
move_mount(mntfd, "", AT_FDCWD, "/mnt", MOVE_MOUNT_F_EMPTY_PATH);

And here is an example of how fspick(2) can be used with fsconfig() to reconfigure the parameters of an extant filesystem instance attached to /proc:

int fsfd = fspick(AT_FDCWD, "/proc", FSPICK_CLOEXEC);
fsconfig(fsfd, FSCONFIG_SET_STRING, "hidepid", "ptraceable", 0);
fsconfig(fsfd, FSCONFIG_SET_STRING, "subset", "pid", 0);
fsconfig(fsfd, FSCONFIG_CMD_RECONFIGURE, NULL, NULL, 0);

fsmount(2), fsopen(2), fspick(2), mount(2), mount_setattr(2), move_mount(2), open_tree(2), mount_namespaces(7)