Debian Codegraph @

upstream/debian-unstable/man2/fsconfig.2

raw
1 .\" Copyright, the authors of the Linux man-pages project
2 .\"
3 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
4 .\"
5 .TH fsconfig 2 2025-12-25 "Linux man-pages 6.18"
6 .SH NAME
7 fsconfig \- configure new or existing filesystem context
8 .SH LIBRARY
9 Standard C library
10 .RI ( libc ,\~ \-lc )
11 .SH SYNOPSIS
12 .nf
13 .B #include <sys/mount.h>
14 .P
15 .BI "int fsconfig(int " fd ", unsigned int " cmd ,
16 .BI " const char *_Nullable " key ,
17 .BI " const void *_Nullable " value ", int " aux );
18 .fi
19 .SH DESCRIPTION
20 The
21 .BR fsconfig ()
22 system call is part of
23 the suite of file-descriptor-based mount facilities in Linux.
24 .P
25 .BR fsconfig ()
26 is used to supply parameters to
27 and issue commands against
28 the filesystem configuration context
29 associated with the file descriptor
30 .IR fd .
31 Filesystem configuration contexts can be created with
32 .BR fsopen (2)
33 or be instantiated from an extant filesystem instance with
34 .BR fspick (2).
35 .P
36 The
37 .I cmd
38 argument indicates the command to be issued.
39 Some commands supply parameters to the context
40 (equivalent to mount options specified with
41 .BR mount (8)),
42 while others are meta-operations on the filesystem context.
43 The list of valid
44 .I cmd
45 values are:
46 .RS
47 .TP
48 .B FSCONFIG_SET_FLAG
49 Set the flag parameter named by
50 .IR key .
51 .I value
52 must be NULL,
53 and
54 .I aux
55 must be 0.
56 .TP
57 .B FSCONFIG_SET_STRING
58 Set the string parameter named by
59 .I key
60 to the value specified by
61 .IR value .
62 .I value
63 points to a null-terminated string,
64 and
65 .I aux
66 must be 0.
67 .TP
68 .B FSCONFIG_SET_BINARY
69 Set the blob parameter named by
70 .I key
71 to the contents of the binary blob
72 specified by
73 .IR value .
74 .I value
75 points to
76 the start of a buffer
77 that is
78 .I aux
79 bytes in length.
80 .TP
81 .B FSCONFIG_SET_FD
82 Set the file parameter named by
83 .I key
84 to the open file description
85 referenced by the file descriptor
86 .IR aux .
87 .I value
88 must be NULL.
89 .IP
90 You may also use
91 .B \%FSCONFIG_SET_STRING
92 for file parameters,
93 with
94 .I value
95 set to a null-terminated string
96 containing a base-10 representation
97 of the file descriptor number.
98 This mechanism is primarily intended for compatibility
99 with older
100 .BR mount (2)-based
101 programs,
102 and only works for parameters
103 that
104 .I only
105 accept file descriptor arguments.
106 .TP
107 .B FSCONFIG_SET_PATH
108 Set the path parameter named by
109 .I key
110 to the object at a provided path,
111 resolved in a similar manner to
112 .BR openat (2).
113 .I value
114 points to a null-terminated pathname string,
115 and
116 .I aux
117 is equivalent to the
118 .I dirfd
119 argument to
120 .BR openat (2).
121 See
122 .BR openat (2)
123 for an explanation of the need for
124 .BR \%FSCONFIG_SET_PATH .
125 .IP
126 You may also use
127 .B \%FSCONFIG_SET_STRING
128 for path parameters,
129 the behavior of which is equivalent to
130 .B \%FSCONFIG_SET_PATH
131 with
132 .I aux
133 set to
134 .BR \%AT_FDCWD .
135 .TP
136 .B FSCONFIG_SET_PATH_EMPTY
137 As with
138 .BR \%FSCONFIG_SET_PATH ,
139 except that if
140 .I value
141 is an empty string,
142 the file descriptor specified by
143 .I aux
144 is operated on directly
145 and may be any type of file
146 (not just a directory).
147 This is equivalent to the behavior of
148 .B \%AT_EMPTY_PATH
149 with most "*at()" system calls.
150 If
151 .I aux
152 is
153 .BR \%AT_FDCWD ,
154 the parameter will be set to
155 the current working directory
156 of the calling process.
157 .TP
158 .B FSCONFIG_CMD_CREATE
159 This command instructs the filesystem driver
160 to instantiate an instance of the filesystem in the kernel
161 with the parameters specified in the filesystem configuration context.
162 .I key
163 and
164 .I value
165 must be NULL,
166 and
167 .I aux
168 must be 0.
169 .IP
170 This command can only be issued once
171 in the lifetime of a filesystem context.
172 If the operation succeeds,
173 the filesystem context
174 associated with file descriptor
175 .I fd
176 now references the created filesystem instance,
177 and is placed into a special "awaiting-mount" mode
178 that allows you to use
179 .BR fsmount (2)
180 to create a mount object from the filesystem instance.
181 .\" FS_CONTEXT_AWAITING_MOUNT is the term the kernel uses for this.
182 If the operation fails,
183 in most cases
184 the filesystem context is placed in a failed mode
185 and cannot be used for any further
186 .BR fsconfig ()
187 operations
188 (though you may still retrieve diagnostic messages
189 through the message retrieval interface,
190 as described in
191 the corresponding subsection of
192 .BR fsopen (2)).
193 .IP
194 This command can only be issued against
195 filesystem configuration contexts
196 that were created with
197 .BR fsopen (2).
198 In order to create a filesystem instance,
199 the calling process must have the
200 .B \%CAP_SYS_ADMIN
201 capability.
202 .IP
203 An important thing to be aware of is that
204 the Linux kernel will
205 .I silently
206 reuse extant filesystem instances
207 depending on the filesystem type
208 and the configured parameters
209 (each filesystem driver has
210 its own policy for
211 how filesystem instances are reused).
212 This means that
213 the filesystem instance "created" by
214 .B \%FSCONFIG_CMD_CREATE
215 may, in fact, be a reference
216 to an extant filesystem instance in the kernel.
217 (For reference,
218 this behavior also applies to
219 .BR mount (2).)
220 .IP
221 One side-effect of this behavior is that
222 if an extant filesystem instance is reused,
223 .I all
224 parameters configured
225 for this filesystem configuration context
226 are
227 .I silently ignored
228 (with the exception of the
229 .I ro
230 and
231 .I rw
232 flag parameters;
233 if the state of the read-only flag in the
234 extant filesystem instance and the filesystem configuration context
235 do not match, this operation will return
236 .BR EBUSY ).
237 This also means that
238 .B \%FSCONFIG_CMD_RECONFIGURE
239 commands issued against
240 the "created" filesystem instance
241 will also affect any mount objects associated with
242 the extant filesystem instance.
243 .IP
244 Programs that need to ensure
245 that they create a new filesystem instance
246 with specific parameters
247 (notably, security-related parameters
248 such as
249 .I acl
250 to enable POSIX ACLs\[em]\c
251 as described in
252 .BR acl (5))
253 should use
254 .B \%FSCONFIG_CMD_CREATE_EXCL
255 instead.
256 .TP
257 .BR FSCONFIG_CMD_CREATE_EXCL " (since Linux 6.6)"
258 .\" commit 22ed7ecdaefe0cac0c6e6295e83048af60435b13
259 .\" commit 84ab1277ce5a90a8d1f377707d662ac43cc0918a
260 As with
261 .BR \%FSCONFIG_CMD_CREATE ,
262 except that the kernel is instructed
263 to not reuse extant filesystem instances.
264 If the operation
265 would be forced to
266 reuse an extant filesystem instance,
267 this operation will return
268 .B EBUSY
269 instead.
270 .IP
271 As a result (unlike
272 .BR \%FSCONFIG_CMD_CREATE ),
273 if this operation succeeds
274 then the calling process can be sure that
275 all of the parameters successfully configured with
276 .BR fsconfig ()
277 will actually be applied
278 to the created filesystem instance.
279 .TP
280 .B FSCONFIG_CMD_RECONFIGURE
281 This command instructs the filesystem driver
282 to apply the parameters specified in the filesystem configuration context
283 to the extant filesystem instance
284 referenced by the filesystem configuration context.
285 .I key
286 and
287 .I value
288 must be NULL,
289 and
290 .I aux
291 must be 0.
292 .IP
293 This is primarily intended for use with
294 .BR fspick (2),
295 but may also be used to modify
296 the parameters of a filesystem instance
297 after
298 .B \%FSCONFIG_CMD_CREATE
299 was used to create it
300 and a mount object was created using
301 .BR fsmount (2).
302 In order to reconfigure an extant filesystem instance,
303 the calling process must have the
304 .B CAP_SYS_ADMIN
305 capability.
306 .IP
307 If the operation succeeds,
308 the filesystem context is reset
309 but remains in reconfiguration mode
310 and thus can be reused for subsequent
311 .B \%FSCONFIG_CMD_RECONFIGURE
312 commands.
313 If the operation fails,
314 in most cases
315 the filesystem context is placed in a failed mode
316 and cannot be used for any further
317 .BR fsconfig ()
318 operations
319 (though you may still retrieve diagnostic messages
320 through the message retrieval interface,
321 as described in
322 the corresponding subsection of
323 .BR fsopen (2)).
324 .RE
325 .P
326 Parameters specified with
327 .BI FSCONFIG_SET_ *
328 do not take effect
329 until a corresponding
330 .B \%FSCONFIG_CMD_CREATE
331 or
332 .B \%FSCONFIG_CMD_RECONFIGURE
333 command is issued.
334 .SH RETURN VALUE
335 On success,
336 .BR fsconfig ()
337 returns 0.
338 On error, \-1 is returned, and
339 .I errno
340 is set to indicate the error.
341 .SH ERRORS
342 If an error occurs, the filesystem driver may provide
343 additional information about the error
344 through the message retrieval interface for filesystem configuration contexts.
345 This additional information can be retrieved at any time by calling
346 .BR read (2)
347 on the filesystem instance or filesystem configuration context
348 referenced by the file descriptor
349 .IR fd .
350 (See the "Message retrieval interface" subsection in
351 .BR fsopen (2)
352 for more details on the message format.)
353 .P
354 Even after an error occurs,
355 the filesystem configuration context is
356 .I not
357 invalidated,
358 and thus can still be used with other
359 .BR fsconfig ()
360 commands.
361 This means that users can probe support for filesystem parameters
362 on a per-parameter basis,
363 and adjust which parameters they wish to set.
364 .P
365 The error values given below result from
366 filesystem type independent errors.
367 Each filesystem type may have its own special errors
368 and its own special behavior.
369 See the Linux kernel source code for details.
370 .TP
371 .B EACCES
372 A component of a path
373 provided as a path parameter
374 was not searchable.
375 (See also
376 .BR path_resolution (7).)
377 .TP
378 .B EACCES
379 .B \%FSCONFIG_CMD_CREATE
380 was attempted
381 for a read-only filesystem
382 without specifying the
383 .RB ' ro '
384 flag parameter.
385 .TP
386 .B EACCES
387 A specified block device parameter
388 is located on a filesystem
389 mounted with the
390 .B \%MS_NODEV
391 option.
392 .TP
393 .B EBADF
394 The file descriptor given by
395 .I fd
396 (or possibly by
397 .IR aux ,
398 depending on the command)
399 is invalid.
400 .TP
401 .B EBUSY
402 The filesystem context associated with
403 .I fd
404 is in the wrong state
405 for the given command.
406 .TP
407 .B EBUSY
408 The filesystem instance cannot be reconfigured as read-only
409 with
410 .B \%FSCONFIG_CMD_RECONFIGURE
411 because some programs
412 still hold files open for writing.
413 .TP
414 .B EBUSY
415 A new filesystem instance was requested with
416 .B \%FSCONFIG_CMD_CREATE_EXCL
417 but a matching superblock already existed.
418 .TP
419 .B EFAULT
420 One of the pointer arguments
421 points to a location
422 outside the calling process's accessible address space.
423 .TP
424 .B EINVAL
425 .I fd
426 does not refer to
427 a filesystem configuration context
428 or filesystem instance.
429 .TP
430 .B EINVAL
431 One of the values of
432 .IR key ,
433 .IR value ,
434 and/or
435 .I aux
436 were set to a non-zero value when
437 .I cmd
438 required that they be zero
439 (or NULL).
440 .TP
441 .B EINVAL
442 The parameter named by
443 .I key
444 cannot be set
445 using the type specified with
446 .IR cmd .
447 .TP
448 .B EINVAL
449 One of the source parameters
450 referred to
451 an invalid superblock.
452 .TP
453 .B ELOOP
454 Too many links encountered
455 during pathname resolution
456 of a path argument.
457 .TP
458 .B ENAMETOOLONG
459 A path argument was longer than
460 .BR PATH_MAX .
461 .TP
462 .B ENOENT
463 A path argument had a non-existent component.
464 .TP
465 .B ENOENT
466 A path argument is an empty string,
467 but
468 .I cmd
469 is not
470 .BR \%FSCONFIG_SET_PATH_EMPTY .
471 .TP
472 .B ENOMEM
473 The kernel could not allocate sufficient memory to complete the operation.
474 .TP
475 .B ENOTBLK
476 The parameter named by
477 .I key
478 must be a block device,
479 but the provided parameter value was not a block device.
480 .TP
481 .B ENOTDIR
482 A component of the path prefix
483 of a path argument
484 was not a directory.
485 .TP
486 .B EOPNOTSUPP
487 The command given by
488 .I cmd
489 is not valid.
490 .TP
491 .B ENXIO
492 The major number
493 of a block device parameter
494 is out of range.
495 .TP
496 .B EPERM
497 The command given by
498 .I cmd
499 was
500 .BR \%FSCONFIG_CMD_CREATE ,
501 .BR \%FSCONFIG_CMD_CREATE_EXCL ,
502 or
503 .BR \%FSCONFIG_CMD_RECONFIGURE ,
504 but the calling process does not have the required
505 .B \%CAP_SYS_ADMIN
506 capability.
507 .SH STANDARDS
508 Linux.
509 .SH HISTORY
510 Linux 5.2.
511 .\" commit ecdab150fddb42fe6a739335257949220033b782
512 .\" commit 400913252d09f9cfb8cce33daee43167921fc343
513 glibc 2.36.
514 .SH NOTES
515 .SS Generic filesystem parameters
516 Each filesystem driver is responsible for
517 parsing most parameters specified with
518 .BR fsconfig (),
519 meaning that individual filesystems
520 may have very different behavior
521 when encountering parameters with the same name.
522 In general,
523 you should not assume that the behavior of
524 .BR fsconfig ()
525 when specifying a parameter to one filesystem type
526 will match the behavior of the same parameter
527 with a different filesystem type.
528 .P
529 However,
530 the following generic parameters
531 apply to all filesystems and have unified behavior.
532 They are set using the listed
533 .BI \%FSCONFIG_SET_ *
534 command.
535 .TP
536 .BR ro \~and\~ rw \~( FSCONFIG_SET_FLAG )
537 Configure whether the filesystem instance is read-only.
538 .TP
539 .BR dirsync \~( FSCONFIG_SET_FLAG )
540 Make directory changes on this filesystem instance synchronous.
541 .TP
542 .BR sync \~and\~ async \~( FSCONFIG_SET_FLAG )
543 Configure whether writes on this filesystem instance
544 will be made synchronous
545 (as though the
546 .B O_SYNC
547 flag to
548 .BR open (2)
549 was specified for
550 all file opens in this filesystem instance).
551 .TP
552 .BR lazytime \~and\~ nolazytime \~( FSCONFIG_SET_FLAG )
553 Configure whether to reduce on-disk updates
554 of inode timestamps on this filesystem instance
555 (as described in the
556 .B \%MS_LAZYTIME
557 section of
558 .BR mount (2)).
559 .TP
560 .BR mand \~and\~ nomand \~( FSCONFIG_SET_FLAG )
561 Configure whether the filesystem instance should permit mandatory locking.
562 Since Linux 5.15,
563 .\" commit f7e33bdbd6d1bdf9c3df8bba5abcf3399f957ac3
564 mandatory locking has been deprecated
565 and setting this flag is a no-op.
566 .TP
567 .BR source \~( FSCONFIG_SET_STRING )
568 This parameter is equivalent to the
569 .I source
570 parameter passed to
571 .BR mount (2)
572 for the same filesystem type,
573 and is usually the pathname of a block device
574 containing the filesystem.
575 This parameter may only be set once
576 per filesystem configuration context transaction.
577 .P
578 In addition,
579 any filesystem parameters associated with
580 Linux Security Modules (LSMs)
581 are also generic with respect to the underlying filesystem.
582 See the documentation for the LSM you wish to configure for more details.
583 .SS Mount attributes and filesystem parameters
584 Some filesystem parameters
585 (traditionally associated with
586 .BR mount (8)-style
587 options)
588 have a sibling mount attribute
589 with superficially similar user-facing behavior.
590 .P
591 For a description of the distinction between
592 mount attributes and filesystem parameters,
593 see the "Mount attributes and filesystem parameters" subsection of
594 .BR mount_setattr (2).
595 .SH CAVEATS
596 .SS Filesystem parameter types
597 As a result of
598 each filesystem driver being responsible for
599 parsing most parameters specified with
600 .BR fsconfig (),
601 some filesystem drivers
602 may have unintuitive behavior
603 with regards to which
604 .BI \%FSCONFIG_SET_ *
605 commands are permitted
606 to configure a given parameter.
607 .P
608 In order for
609 filesystem parameters to be backwards compatible with
610 .BR mount (2),
611 they must be parseable as strings;
612 this almost universally means that
613 .B \%FSCONFIG_SET_STRING
614 can also be used to configure them.
615 .\" Aleksa Sarai
616 .\" Theoretically, a filesystem could check fc->oldapi and refuse
617 .\" FSCONFIG_SET_STRING if the operation is coming from the new API, but no
618 .\" filesystems do this (and probably never will).
619 However, other
620 .BI \%FSCONFIG_SET_ *
621 commands need to be opted into
622 by each filesystem driver's parameter parser.
623 .P
624 One of the most user-visible instances of
625 this inconsistency is that
626 many filesystems do not support
627 configuring path parameters with
628 .B \%FSCONFIG_SET_PATH
629 (despite the name),
630 which can lead to somewhat confusing
631 .B EINVAL
632 errors.
633 (For example, the generic
634 .I source
635 parameter\[em]\c
636 which is usually a path\[em]\c
637 can only be configured
638 with
639 .BR \%FSCONFIG_SET_STRING .)
640 .P
641 When writing programs that use
642 .BR fsconfig ()
643 to configure parameters
644 with commands other than
645 .BR \%FSCONFIG_SET_STRING ,
646 users should verify
647 that the
648 .BI \%FSCONFIG_SET_ *
649 commands used to configure each parameter
650 are supported by the corresponding filesystem driver.
651 .\" Aleksa Sarai
652 .\" While this (quite confusing) inconsistency in behavior is true today
653 .\" (and has been true since this was merged), this appears to mostly be an
654 .\" unintended consequence of filesystem drivers hand-coding fsparam parsing.
655 .\" Path parameters are the most eggregious causes of confusion.
656 .\" Hopefully we can make this no longer the case in a future kernel.
657 .SH EXAMPLES
658 To illustrate the different kinds of flags that can be configured with
659 .BR fsconfig (),
660 here are a few examples of some different filesystems being created:
661 .P
662 .in +4n
663 .EX
664 int fsfd, mntfd;
665 \&
666 fsfd = fsopen("tmpfs", FSOPEN_CLOEXEC);
667 fsconfig(fsfd, FSCONFIG_SET_FLAG, "inode64", NULL, 0);
668 fsconfig(fsfd, FSCONFIG_SET_STRING, "uid", "1234", 0);
669 fsconfig(fsfd, FSCONFIG_SET_STRING, "huge", "never", 0);
670 fsconfig(fsfd, FSCONFIG_SET_FLAG, "casefold", NULL, 0);
671 fsconfig(fsfd, FSCONFIG_CMD_CREATE, NULL, NULL, 0);
672 mntfd = fsmount(fsfd, FSMOUNT_CLOEXEC, MOUNT_ATTR_NOEXEC);
673 move_mount(mntfd, "", AT_FDCWD, "/tmp", MOVE_MOUNT_F_EMPTY_PATH);
674 \&
675 fsfd = fsopen("erofs", FSOPEN_CLOEXEC);
676 fsconfig(fsfd, FSCONFIG_SET_STRING, "source", "/dev/loop0", 0);
677 fsconfig(fsfd, FSCONFIG_SET_FLAG, "acl", NULL, 0);
678 fsconfig(fsfd, FSCONFIG_SET_FLAG, "user_xattr", NULL, 0);
679 fsconfig(fsfd, FSCONFIG_CMD_CREATE_EXCL, NULL, NULL, 0);
680 mntfd = fsmount(fsfd, FSMOUNT_CLOEXEC, MOUNT_ATTR_NOSUID);
681 move_mount(mntfd, "", AT_FDCWD, "/mnt", MOVE_MOUNT_F_EMPTY_PATH);
682 .EE
683 .in
684 .P
685 Usually,
686 specifying the same parameter named by
687 .I key
688 multiple times with
689 .BR fsconfig ()
690 causes the parameter value to be replaced.
691 However, some filesystems may have unique behavior:
692 .P
693 .in +4n
694 .EX
695 \&
696 int fsfd, mntfd;
697 int lowerdirfd = open("/o/ctr/lower1", O_DIRECTORY | O_CLOEXEC);
698 \&
699 fsfd = fsopen("overlay", FSOPEN_CLOEXEC);
700 /* "lowerdir+" appends to the lower dir stack each time */
701 fsconfig(fsfd, FSCONFIG_SET_FD, "lowerdir+", NULL, lowerdirfd);
702 fsconfig(fsfd, FSCONFIG_SET_STRING, "lowerdir+", "/o/ctr/lower2", 0);
703 fsconfig(fsfd, FSCONFIG_SET_STRING, "lowerdir+", "/o/ctr/lower3", 0);
704 fsconfig(fsfd, FSCONFIG_SET_STRING, "lowerdir+", "/o/ctr/lower4", 0);
705 .\" fsconfig(fsfd, FSCONFIG_SET_PATH, "lowerdir+", "/o/ctr/lower5", AT_FDCWD);
706 .\" fsconfig(fsfd, FSCONFIG_SET_PATH_EMPTY, "lowerdir+", "", lowerdirfd);
707 .\" Aleksa Sarai: Hopefully these will also be supported in the future.
708 fsconfig(fsfd, FSCONFIG_SET_STRING, "xino", "auto", 0);
709 fsconfig(fsfd, FSCONFIG_SET_STRING, "nfs_export", "off", 0);
710 fsconfig(fsfd, FSCONFIG_CMD_CREATE, NULL, NULL, 0);
711 mntfd = fsmount(fsfd, FSMOUNT_CLOEXEC, 0);
712 move_mount(mntfd, "", AT_FDCWD, "/mnt", MOVE_MOUNT_F_EMPTY_PATH);
713 .EE
714 .in
715 .P
716 And here is an example of how
717 .BR fspick (2)
718 can be used with
719 .BR fsconfig ()
720 to reconfigure the parameters
721 of an extant filesystem instance
722 attached to
723 .IR /proc :
724 .P
725 .in +4n
726 .EX
727 int fsfd = fspick(AT_FDCWD, "/proc", FSPICK_CLOEXEC);
728 fsconfig(fsfd, FSCONFIG_SET_STRING, "hidepid", "ptraceable", 0);
729 fsconfig(fsfd, FSCONFIG_SET_STRING, "subset", "pid", 0);
730 fsconfig(fsfd, FSCONFIG_CMD_RECONFIGURE, NULL, NULL, 0);
731 .EE
732 .in
733 .SH SEE ALSO
734 .BR fsmount (2),
735 .BR fsopen (2),
736 .BR fspick (2),
737 .BR mount (2),
738 .BR mount_setattr (2),
739 .BR move_mount (2),
740 .BR open_tree (2),
741 .BR mount_namespaces (7)