fsconfig(2)

🌸 NAME 🌸

fsconfig — configure new or existing filesystem context

(it lives in section 2 of the Linux manual, aka the System Calls Manual, so yeah bestie, this is kernel business 💅)

---

📚 LIBRARY 📚

Standard C library (libc, -lc)

---

✨ SYNOPSIS ✨

#include <sys/mount.h>

int fsconfig(int fd, unsigned int cmd,
             const char *_Nullable key,
             const void *_Nullable value, int aux);

---

💖 DESCRIPTION 💖

Okay so fsconfig() is part of the whole suite of file-descriptor-based mount facilities in Linux. Think of it as the girl in the group chat who actually knows what's going on with your mounts.

fsconfig() is how you supply parameters to — and issue commands against — the filesystem configuration context that's hanging out behind the file descriptor fd. And where do those contexts come from? Two places, bestie:

• You can create one with fsopen(2), or
• you can instantiate one from a filesystem instance that already exists, using fspick(2).

The cmd argument is the command getting issued. Some commands just feed parameters into the context (this is the equivalent of mount options you'd pass to mount(8)), and the other ones are meta-operations on the filesystem context itself. Here's the full list of valid cmd values, no gatekeeping:

• FSCONFIG_SET_FLAG — Sets the flag parameter named by key. value must be NULL, and aux must be 0.
• FSCONFIG_SET_STRING — Sets the string parameter named by key to the value you point at with value. value points to a null-terminated string, and aux must be 0.
• FSCONFIG_SET_BINARY — Sets the blob parameter named by key to the contents of the binary blob in value. value points to the start of a buffer that is aux bytes long.
• FSCONFIG_SET_FD — Sets the file parameter named by key to the open file description referenced by the file descriptor aux. value must be NULL.

You can also use FSCONFIG_SET_STRING for file parameters, with value set to a null-terminated string holding a base-10 representation of the file descriptor number. This route exists mainly for compatibility with older mount(2)-based programs, and it only works for parameters that accept nothing but file descriptor arguments. iykyk.

• FSCONFIG_SET_PATH — Sets the path parameter named by key to the object at a provided path, resolved in a way that's similar to openat(2). value points to a null-terminated pathname string, and aux is equivalent to the dirfd argument of openat(2). Go read openat(2) for why FSCONFIG_SET_PATH even needs to exist.

You can also use FSCONFIG_SET_STRING for path parameters — that behaves exactly like FSCONFIG_SET_PATH with aux set to AT_FDCWD.

• FSCONFIG_SET_PATH_EMPTY — Same as FSCONFIG_SET_PATH, except that if value is an empty string, the file descriptor specified by aux is operated on directly and can be any type of file — not just a directory. This is equivalent to what AT_EMPTY_PATH does with most "*at()" system calls. And if aux is AT_FDCWD, the parameter gets set to the current working directory of the calling process.
• FSCONFIG_CMD_CREATE — This one tells the filesystem driver to instantiate an instance of the filesystem in the kernel, using the parameters sitting 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. No reruns, bestie. If it succeeds, the filesystem context behind file descriptor fd now references the created filesystem instance, and it drops into a special "awaiting-mount" mode that lets you use fsmount(2) to make a mount object from that filesystem instance. If it fails, in most cases the filesystem context goes into failed mode and is done — you can't use it for any further fsconfig() operations (you can still pull diagnostic messages through the message retrieval interface though, 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). And to create a filesystem instance at all, the calling process needs the CAP_SYS_ADMIN capability.

Now here's the important tea: the Linux kernel will silently reuse extant filesystem instances depending on the filesystem type and the parameters you configured (every filesystem driver has its own policy about how instances get reused). Which means the filesystem instance "created" by FSCONFIG_CMD_CREATE might, in fact, just be a reference to a filesystem instance that was already chilling in the kernel. (For reference, this behavior applies to mount(2) too.)

One side-effect of that: if an extant filesystem instance gets reused, all the parameters you configured for this filesystem configuration context are silently ignored — with the exception of the ro and rw flag parameters. And if the state of the read-only flag in the extant filesystem instance and the one in the filesystem configuration context don't match, this operation returns EBUSY. It also means any FSCONFIG_CMD_RECONFIGURE commands issued against the "created" filesystem instance will affect every mount object associated with that extant instance too. 😭

So if a program genuinely needs a brand-new filesystem instance with specific parameters — especially security-related ones like acl, which enables POSIX ACLs as described in acl(5) — it should use FSCONFIG_CMD_CREATE_EXCL instead. Periodt.

• FSCONFIG_CMD_CREATE_EXCL (since Linux 6.6) — Same as FSCONFIG_CMD_CREATE, except the kernel is told not to reuse extant filesystem instances. If the operation would be forced to reuse one anyway, it returns EBUSY instead.

And as a result (unlike FSCONFIG_CMD_CREATE), if this operation succeeds, the calling process can be sure that every parameter it successfully configured with fsconfig() will actually be applied to the created filesystem instance. King behavior, honestly. 👑

• FSCONFIG_CMD_RECONFIGURE — This one tells the filesystem driver to apply the parameters in the filesystem configuration context to the extant filesystem instance that the context references. key and value must be NULL, and aux must be 0.

It's mainly meant to be used with fspick(2), but you can also use it to modify the parameters of a filesystem instance after FSCONFIG_CMD_CREATE was used to create it and a mount object was created with fsmount(2). To reconfigure an extant filesystem instance, the calling process needs the CAP_SYS_ADMIN capability.

If it succeeds, the filesystem context gets reset but stays in reconfiguration mode, so you can reuse it for subsequent FSCONFIG_CMD_RECONFIGURE commands. If it fails, in most cases the filesystem context goes into failed mode and can't be used for any more fsconfig() operations (you can still retrieve diagnostic messages through the message retrieval interface though, as described in the corresponding subsection of fsopen(2)).

---

🫶 Heads up bestie: parameters you set with any FSCONFIG_SET_* command do not take effect until a corresponding FSCONFIG_CMD_CREATE or FSCONFIG_CMD_RECONFIGURE command gets issued. They're just vibing in the context until then.

---

🦋 RETURN VALUE 🦋

On success, fsconfig() returns 0. On error, it returns -1, and errno is set to indicate the error. Slay when it's 0, cry when it's -1.

---

✨ to be continued… ✨

💥 ERRORS 💥

Okay so when something goes sideways, bestie, the filesystem driver might have more to say about it. Like, it can drop extra deets about the error through the message retrieval interface for filesystem configuration contexts. You can grab that extra info whenever you want by calling read(2) on the filesystem instance or the filesystem configuration context that fd points at. (Peep the "Message retrieval interface" subsection over in fsopen(2) for the whole tea on the message format.) 🫖

And here's the iconically forgiving part: even after an error happens, the filesystem configuration context is not invalidated. She lives! So you can keep using her with other fsconfig() commands. Which means users can literally probe support for filesystem parameters one at a time, parameter by parameter, and vibe-check which ones they actually wanna set. 🌸

The error values down below are the filesystem-type-independent ones. Every filesystem type can have its own special little errors and its own special behavior — check the Linux kernel source code for those ✨

• EACCES — a component of a path you passed as a path parameter was not searchable. (Also see path_resolution(7).)
• EACCES — FSCONFIG_CMD_CREATE was attempted for a read-only filesystem without specifying the ro flag parameter.
• EACCES — a specified block device parameter is located on a filesystem mounted with the MS_NODEV option.
• EBADF — the file descriptor given by fd (or possibly by aux, depending on the command) is invalid.
• EBUSY — the filesystem context associated with fd is in the wrong state for the given command.
• EBUSY — the filesystem instance cannot be reconfigured as read-only with FSCONFIG_CMD_RECONFIGURE because some programs still hold files open for writing.
• EBUSY — a new filesystem instance was requested with FSCONFIG_CMD_CREATE_EXCL but a matching superblock already existed.
• EFAULT — one of the pointer arguments points to a location outside the calling process's accessible address space.
• EINVAL — fd does not refer to a filesystem configuration context or filesystem instance.
• EINVAL — one of the values of key, value, and/or aux were set to a non-zero value when cmd required that they be zero (or NULL).
• EINVAL — the parameter named by key cannot be set using the type specified with cmd.
• EINVAL — one of the source parameters referred to an invalid superblock.
• ELOOP — too many links encountered during pathname resolution of a path argument.
• ENAMETOOLONG — a path argument was longer than PATH_MAX.
• ENOENT — a path argument had a non-existent component.
• ENOENT — a path argument is an empty string, but cmd is not FSCONFIG_SET_PATH_EMPTY.
• ENOMEM — the kernel could not allocate sufficient memory to complete the operation.
• ENOTBLK — the parameter named by key must be a block device, but the provided parameter value was not a block device.
• ENOTDIR — a component of the path prefix of a path argument was not a directory.
• EOPNOTSUPP — the command given by cmd is not valid.
• ENXIO — the major number of a block device parameter is out of range.
• EPERM — the command given by cmd was FSCONFIG_CMD_CREATE, FSCONFIG_CMD_CREATE_EXCL, or FSCONFIG_CMD_RECONFIGURE, but the calling process does not have the required CAP_SYS_ADMIN capability.

---

📜 STANDARDS 📜

Linux. That's it. That's the standard. 💅

---

🕰️ HISTORY 🕰️

Linux 5.2. glibc 2.36. Ancient history in tech years, honestly. 👑

---

📝 NOTES 📝

🧬 Generic filesystem parameters 🧬

So here's the thing: each filesystem driver is the one responsible for parsing most parameters you specify with fsconfig(). Meaning individual filesystems can act completely differently when they run into parameters with the same name. In general, do not assume that what fsconfig() does when you hand a parameter to one filesystem type will match what the same parameter does on a different filesystem type. It's giving "everyone's got their own rules." 😭

However — the following generic parameters apply to all filesystems and have unified behavior. You set them using the listed FSCONFIG_SET_* command. Slay, consistency! ✨

• ro and rw (FSCONFIG_SET_FLAG) — configure whether the filesystem instance is read-only.
• dirsync (FSCONFIG_SET_FLAG) — make directory changes on this filesystem instance synchronous.
• sync and async (FSCONFIG_SET_FLAG) — configure whether writes on this filesystem instance will be made synchronous (as though the O_SYNC flag to open(2) was specified for all file opens in this filesystem instance).
• lazytime and nolazytime (FSCONFIG_SET_FLAG) — configure whether to reduce on-disk updates of inode timestamps on this filesystem instance (as described in the MS_LAZYTIME section of mount(2)).
• mand and nomand (FSCONFIG_SET_FLAG) — configure whether the filesystem instance should permit mandatory locking. Since Linux 5.15, mandatory locking has been deprecated and setting this flag is a no-op. 💀
• source (FSCONFIG_SET_STRING) — this parameter is equivalent to the source parameter passed to mount(2) for the same filesystem type, and is usually the pathname of a block device containing the filesystem. This parameter may only be set once per filesystem configuration context transaction.

Plus! Any filesystem parameters associated with Linux Security Modules (LSMs) are also generic with respect to the underlying filesystem. See the documentation for the LSM you wish to configure for more details. 🔐

🗂️ Mount attributes and filesystem parameters 🗂️

Some filesystem parameters (traditionally associated with mount(8)-style options) have a sibling mount attribute with superficially similar user-facing behavior. Lowkey they look alike, highkey they're not the same thing.

For a full description of the distinction between mount attributes and filesystem parameters, go read the "Mount attributes and filesystem parameters" subsection of mount_setattr(2). 🦋

---

⚠️ CAVEATS ⚠️

🎭 Filesystem parameter types 🎭

Because each filesystem driver is responsible for parsing most parameters specified with fsconfig(), some filesystem drivers may have unintuitive behavior with regards to which FSCONFIG_SET_* commands are permitted to configure a given parameter. Not them being mysterious about it. 🙈

In order for filesystem parameters to be backwards compatible with mount(2), they must be parseable as strings; this almost universally means that FSCONFIG_SET_STRING can also be used to configure them. However, other FSCONFIG_SET_* commands need to be opted into by each filesystem driver's parameter parser.

One of the most user-visible instances of this inconsistency is that many filesystems do not support configuring path parameters with FSCONFIG_SET_PATH (despite the name, bestie, make it make sense), which can lead to somewhat confusing EINVAL errors. (For example, the generic source parameter — which is usually a path — can only be configured with FSCONFIG_SET_STRING.) 😤

When writing programs that use fsconfig() to configure parameters with commands other than FSCONFIG_SET_STRING, users should verify that the FSCONFIG_SET_* commands used to configure each parameter are supported by the corresponding filesystem driver. No cap, always check first. 🫶

---

🍓 EXAMPLES 🍓

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. Main character filesystems don't follow the rules: 👑

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);

---

👀 SEE ALSO 👀

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

---

OK bestie that's the whole page, we ate and left no crumbs. 🍽️✨ This one's from Linux man-pages 6.20, dated 2025-12-25, and it's all about fsconfig(2). Go mount something iconic. 💖