1 .\" Copyright (c) 2021 by Christian Brauner <christian.brauner@ubuntu.com>
3 .\" %%%LICENSE_START(VERBATIM)
4 .\" Permission is granted to make and distribute verbatim copies of this
5 .\" manual provided the copyright notice and this permission notice are
6 .\" preserved on all copies.
8 .\" Permission is granted to copy and distribute modified versions of this
9 .\" manual under the conditions for verbatim copying, provided that the
10 .\" entire resulting derived work is distributed under the terms of a
11 .\" permission notice identical to this one.
13 .\" Since the Linux kernel and libraries are constantly changing, this
14 .\" manual page may be incorrect or out-of-date. The author(s) assume no
15 .\" responsibility for errors or omissions, or for damages resulting from
16 .\" the use of the information contained herein. The author(s) may not
17 .\" have taken the same level of care in the production of this manual,
18 .\" which is licensed free of charge, as they might when working
21 .\" Formatted or processed versions of this manual, if unaccompanied by
22 .\" the source, must acknowledge the copyright and authors of this work.
25 .TH MOUNT_SETATTR 2 2021-03-22 "Linux" "Linux Programmer's Manual"
27 mount_setattr \- change mount properties of a mount or mount tree
32 .BR "#include <linux/fcntl.h>" " /* Definition of " AT_* " constants */"
33 .BR "#include <linux/mount.h>" " /* Definition of " MOUNT_ATTR_* " constants */"
34 .BR "#include <sys/syscall.h>" " /* Definition of " SYS_* " constants */"
35 .B #include <unistd.h>
37 .BI "int syscall(SYS_mount_setattr, int " dfd ", const char *" path ,
38 .BI " unsigned int " flags ", struct mount_attr *" attr \
43 glibc provides no wrapper for
45 necessitating the use of
50 system call changes the mount properties of a mount or an entire mount tree.
53 is a relative pathname,
54 then it is interpreted relative to
55 the directory referred to by the file descriptor
63 is interpreted relative to
64 the current working directory of the calling process.
67 is the empty string and
71 then the mount properties of the mount identified by
77 system call uses an extensible structure
78 .RI ( "struct mount_attr" )
79 to allow for future extensions.
80 Any non-flag extensions to
82 will be implemented as new fields appended to the this structure,
83 with a zero value in a new field resulting in the kernel behaving
84 as though that extension field was not present.
88 zero-fill this structure on initialization.
89 See the "Extensibility" subsection under
95 argument should usually be specified as
96 .IR "sizeof(struct mount_attr)" .
98 if the caller does not intend to make use of features that
99 got introduced after the initial version of
100 .IR "struct mount_attr" ,
101 it is possible to pass
102 the size of the initial struct together with the larger struct.
103 This allows the kernel to not copy later parts of the struct
104 that aren't used anyway.
105 With each extension that changes the size of
106 .IR "struct mount_attr" ,
107 the kernel will expose a definition of the form
108 .BI MOUNT_ATTR_SIZE_VER number\c
110 For example, the macro for the size of the initial version of
113 .BR MOUNT_ATTR_SIZE_VER0 .
117 argument can be used to alter the path resolution behavior.
118 The supported values are:
124 change the mount properties on
129 Change the mount properties of the entire mount tree.
131 .B AT_SYMLINK_NOFOLLOW
132 Don't follow trailing symbolic links.
135 Don't trigger automounts.
141 is a structure of the following form:
146 __u64 attr_set; /* Mount properties to set */
147 __u64 attr_clr; /* Mount properties to clear */
148 __u64 propagation; /* Mount propagation type */
149 __u64 userns_fd; /* User namespace file descriptor */
158 members are used to specify the mount properties that
159 are supposed to be set or cleared for a mount or mount tree.
162 enable a property on a mount or mount tree,
165 remove a property from a mount or mount tree.
167 When changing mount properties,
168 the kernel will first clear the flags specified
172 and then set the flags specified in the
178 struct mount_attr attr = {
179 .attr_clr = MOUNT_ATTR_NOEXEC | MOUNT_ATTR_NODEV,
180 .attr_set = MOUNT_ATTR_RDONLY | MOUNT_ATTR_NOSUID,
182 unsigned int current_mnt_flags = mnt->mnt_flags;
185 * Clear all flags set in .attr_clr,
186 * clearing MOUNT_ATTR_NOEXEC and MOUNT_ATTR_NODEV.
188 current_mnt_flags &= ~attr->attr_clr;
191 * Now set all flags set in .attr_set,
192 * applying MOUNT_ATTR_RDONLY and MOUNT_ATTR_NOSUID.
194 current_mnt_flags |= attr->attr_set;
196 mnt->mnt_flags = current_mnt_flags;
200 As a rsult of this change, the mount or mount tree (a) is read-only;
201 (b) blocks the execution of set-user-ID and set-group-ID programs;
202 (c) allows execution of programs; and (d) allows access to devices.
204 Multiple changes with the same set of flags requested
209 are guaranteed to be idempotent after the changes have been applied.
211 The following mount attributes can be specified in the
220 makes the mount read-only.
223 removes the read-only setting if set on the mount.
228 causes the mount not to honor the set-user-ID and set-group-ID mode bits and
229 file capabilities when executing programs.
232 clears the set-user-ID, set-group-ID,
233 and file capability restriction if set on this mount.
238 prevents access to devices on this mount.
241 removes the restriction that prevented accessing devices on this mount.
246 prevents executing programs on this mount.
249 removes the restriction that prevented executing programs on this mount.
251 .B MOUNT_ATTR_NOSYMFOLLOW
254 prevents following symbolic links on this mount.
257 removes the restriction that prevented following symbolic links on this mount.
259 .B MOUNT_ATTR_NODIRATIME
262 prevents updating access time for directories on this mount.
265 removes the restriction that prevented updating access time for directories.
267 .B MOUNT_ATTR_NODIRATIME
268 can be combined with other access-time settings
269 and is implied by the noatime setting.
270 All other access-time settings are mutually exclusive.
272 .BR MOUNT_ATTR__ATIME " - changing access-time settings"
273 In the new mount API, the access-time values are an enum starting from 0.
274 Even though they are an enum (in contrast to the other mount flags such as
275 .BR MOUNT_ATTR_NOEXEC ),
276 they are nonetheless passed in
282 which introduced this behavior.
285 since access times are an enum
287 users wanting to transition to a different access-time setting cannot simply
288 specify the access-time setting in
295 The kernel will verify that
297 isn't partially set in
301 doesn't have any access-time bits set if
307 .B MOUNT_ATTR_RELATIME
308 When a file is accessed via this mount,
309 update the file's last access time (atime)
310 only if the current value of atime is less than or equal to
311 the file's last modification time (mtime) or last status change time (ctime).
313 To enable this access-time setting on a mount or mount tree,
314 .B MOUNT_ATTR_RELATIME
323 .B MOUNT_ATTR_NOATIME
324 Do not update access times for (all types of) files on this mount.
326 To enable this access-time setting on a mount or mount tree,
327 .B MOUNT_ATTR_NOATIME
336 .B MOUNT_ATTR_STRICTATIME
337 Always update the last access time (atime)
338 when files are accessed on this mount.
340 To enable this access-time setting on a mount or mount tree,
341 .B MOUNT_ATTR_STRICTATIME
354 creates an ID-mapped mount.
355 The ID mapping is taken from the user namespace specified in
357 and attached to the mount.
359 Since it is not supported to
360 change the ID mapping of a mount after it has been ID mapped,
361 it is invalid to specify
366 Creating an ID-mapped mount makes it possible to
367 change the ownership of all files located under a mount.
368 Thus, ID-mapped mounts make it possible to
369 change ownership in a temporary and localized way.
370 It is a localized change because
371 ownership changes are restricted to a specific mount.
372 All other users and locations where the filesystem is exposed are unaffected.
373 And it is a temporary change because
374 ownership changes are tied to the lifetime of the mount.
376 Whenever callers interact with the filesystem through an ID-mapped mount,
377 the ID mapping of the mount will be applied to
378 user and group IDs associated with filesystem objects.
379 This encompasses the user and group IDs associated with inodes
380 and also the following
385 .IR security.capability ,
386 whenever filesystem capabilities
387 are stored or returned in the
388 .B VFS_CAP_REVISION_3
390 which stores a root user ID alongside the capabilities
392 .BR capabilities (7)).
394 .I system.posix_acl_access
396 .IR system.posix_acl_default ,
397 whenever user IDs or group IDs are stored in
404 The following conditions must be met in order to create an ID-mapped mount:
407 The caller must have the
409 capability in the initial user namespace.
411 The filesystem must be mounted in the initial user namespace.
413 The underlying filesystem must support ID-mapped mounts.
419 filesystems support ID-mapped mounts
420 with more filesystems being actively worked on.
422 The mount must not already be ID-mapped.
423 This also implies that the ID mapping of a mount cannot be altered.
425 The mount must be a detached/anonymous mount;
427 it must have been created by calling
431 flag and it must not already have been visible in the filesystem.
434 ID mappings can be created for user IDs, group IDs, and project IDs.
435 An ID mapping is essentially a mapping of a range of user or group IDs into
436 another or the same range of user or group IDs.
437 ID mappings are usually written as three numbers
438 either separated by white space or a full stop.
439 The first two numbers specify the starting user or group ID
440 in each of the two user namespaces.
441 The third number specifies the range of the ID mapping.
442 For example, a mapping for user IDs such as 1000:1001:1 would indicate that
443 user ID 1000 in the caller's user namespace is mapped to
444 user ID 1001 in its ancestor user namespace.
445 Since the map range is 1,
446 only user ID 1000 is mapped.
448 It is possible to specify up to 340 ID mappings for each ID mapping type.
449 If any user IDs or group IDs are not mapped,
450 all files owned by that unmapped user or group ID will appear as
451 being owned by the overflow user ID or overflow group ID respectively.
453 Further details and instructions for setting up ID mappings can be found in the
454 .BR user_namespaces (7)
457 In the common case, the user namespace passed in
463 to create an ID-mapped mount will be the user namespace of a container.
464 In other scenarios it will be a dedicated user namespace associated with
465 a user's login session as is the case for portable home directories in
466 .BR systemd-homed.service (8)).
467 It is also perfectly fine to create a dedicated user namespace
468 for the sake of ID mapping a mount.
470 ID-mapped mounts can be useful in the following
471 and a variety of other scenarios:
474 Sharing files between multiple users or multiple machines,
475 especially in complex scenarios.
477 ID-mapped mounts are used to implement portable home directories in
478 .BR systemd-homed.service (8),
479 where they allow users to move their home directory
480 to an external storage device
481 and use it on multiple computers
482 where they are assigned different user IDs and group IDs.
483 This effectively makes it possible to
484 assign random user IDs and group IDs at login time.
486 Sharing files from the host with unprivileged containers.
487 This allows a user to avoid having to change ownership permanently through
490 ID mapping a container's root filesystem.
491 Users don't need to change ownership permanently through
493 Especially for large root filesystems, using
495 can be prohibitively expensive.
497 Sharing files between containers with non-overlapping ID mappings.
499 Implementing discretionary access (DAC) permission checking
500 for filesystems lacking a concept of ownership.
502 Efficiently changing ownership on a per-mount basis.
505 changing ownership of large sets of files is instantaneous with
507 This is especially useful when ownership of
508 an entire root filesystem of a virtual machine or container
509 is to be changed as mentioned above.
510 With ID-mapped mounts,
513 system call will be sufficient to change the ownership of all files.
515 Taking the current ownership into account.
516 ID mappings specify precisely
517 what a user or group ID is supposed to be mapped to.
518 This contrasts with the
520 system call which cannot by itself
521 take the current ownership of the files it changes into account.
522 It simply changes the ownership to the specified user ID and group ID.
524 Locally and temporarily restricted ownership changes.
525 ID-mapped mounts make it possible to change ownership locally,
526 restricting it to specific mounts,
527 and temporarily as the ownership changes only apply as long as the mount exists.
529 changing ownership via the
531 system call changes the ownership globally and permanently.
536 field is used to specify the propagation type of the mount or mount tree.
537 Mount propagation options are mutually exclusive;
539 the propagation values behave like an enum.
540 The supported mount propagation types are:
543 Turn all mounts into private mounts.
544 Mount and unmount events do not propagate into or out of this mount point.
547 Turn all mounts into shared mounts.
548 Mount points share events with members of a peer group.
549 Mount and unmount events immediately under this mount point
550 will propagate to the other mount points that are members of the peer group.
551 Propagation here means that the same mount or unmount will automatically occur
552 under all of the other mount points in the peer group.
554 mount and unmount events that take place under peer mount points
555 will propagate to this mount point.
558 Turn all mounts into dependent mounts.
559 Mount and unmount events propagate into this mount point
560 from a shared peer group.
561 Mount and unmount events under this mount point do not propagate to any peer.
564 This is like a private mount,
565 and in addition this mount can't be bind mounted.
566 Attempts to bind mount this mount will fail.
567 When a recursive bind mount is performed on a directory subtree,
568 any bind mounts within the subtree are automatically pruned
569 (i.e., not replicated)
570 when replicating that subtree to produce the target subtree.
578 is set to indicate the cause of the error.
583 is not a valid file descriptor.
587 is not a valid file descriptor.
590 The caller tried to change the mount to
591 .BR MOUNT_ATTR_RDONLY ,
592 but the mount still holds files open for writing.
595 The path specified via the
604 An unsupported value was set in
608 An unsupported value was specified in the
614 An unsupported value was specified in the
620 An unsupported value was specified in the
638 An access-time setting was specified in the
652 A file descriptor value was specified in
658 A valid file descriptor value was specified in
660 but the file descriptor wasn't a namespace file descriptor
661 or did not refer to a user namespace.
664 The underlying filesystem does not support ID-mapped mounts.
667 The mount that is to be ID mapped is not a detached/anonymous mount;
668 that is, the mount is already visible in the filesystem.
671 A partial access-time setting was specified in
678 The mount is located outside the caller's mount namespace.
681 The underlying filesystem is mounted in a user namespace.
684 A pathname was empty or had a nonexistent component.
687 When changing mount propagation to
689 a new peer group ID needs to be allocated for all mounts without a peer group
691 Allocation of this peer group ID has failed.
694 When changing mount propagation to
696 a new peer group ID needs to be allocated for all mounts without a peer group
698 Allocation of this peer group ID can fail.
699 Note that technically further error codes are possible that are specific to the
700 ID allocation implementation used.
703 One of the mounts had at least one of
704 .BR MOUNT_ATTR_NOATIME ,
705 .BR MOUNT_ATTR_NODEV ,
706 .BR MOUNT_ATTR_NODIRATIME ,
707 .BR MOUNT_ATTR_NOEXEC ,
708 .BR MOUNT_ATTR_NOSUID ,
711 set and the flag is locked.
712 Mount attributes become locked on a mount if:
715 A new mount or mount tree is created causing mount propagation across user
717 The kernel will lock the aforementioned flags to protect these sensitive
718 properties from being altered.
720 A new mount and user namespace pair is created.
721 This happens for example when specifying
722 .B CLONE_NEWUSER | CLONE_NEWNS
728 The aforementioned flags become locked to protect user namespaces from altering
729 sensitive mount properties.
733 A valid file descriptor value was specified in
735 but the file descriptor refers to the initial user namespace.
738 An already ID-mapped mount was supposed to be ID mapped.
741 The caller does not have
743 in the initial user namespace.
746 first appeared in Linux 5.12.
747 .\" commit 7d6beb71da3cc033649d641e1e608713b8220290
748 .\" commit 2a1867219c7b27f928e2545782b86daaf9ad50bd
749 .\" commit 9caccd41541a6f7d6279928d9f971f6642c361af
755 In order to allow for future extensibility,
757 requires the user-space application to specify the size of the
759 structure that it is passing.
760 By providing this information, it is possible for
762 to provide both forwards- and backwards-compatibility, with
764 acting as an implicit version number.
765 (Because new extension fields will always
766 be appended, the structure size will always increase.)
767 This extensibility design is very similar to other system calls such as
768 .BR perf_setattr (2),
769 .BR perf_event_open (2),
776 be the size of the structure as specified by the user-space application,
779 be the size of the structure which the kernel supports,
780 then there are three cases to consider:
786 then there is no version mismatch and
788 can be used verbatim.
794 then there are some extension fields that the kernel supports
795 which the user-space application is unaware of.
796 Because a zero value in any added extension field signifies a no-op,
797 the kernel treats all of the extension fields
798 not provided by the user-space application
799 as having zero values.
800 This provides backwards-compatibility.
806 then there are some extension fields which the user-space application is aware
807 of but which the kernel does not support.
808 Because any extension field must have its zero values signify a no-op,
809 the kernel can safely ignore the unsupported extension fields
810 if they are all zero.
811 If any unsupported extension fields are non-zero,
812 then \-1 is returned and
816 This provides forwards-compatibility.
818 Because the definition of
820 may change in the future
821 (with new fields being added when system headers are updated),
822 user-space applications should zero-fill
824 to ensure that recompiling the program with new headers will not result in
825 spurious errors at runtime.
826 The simplest way is to use a designated initializer:
830 struct mount_attr attr = {
831 .attr_set = MOUNT_ATTR_RDONLY,
832 .attr_clr = MOUNT_ATTR_NODEV
837 Alternatively, the structure can be zero-filled using
839 or similar functions:
843 struct mount_attr attr;
844 memset(&attr, 0, sizeof(attr));
845 attr.attr_set = MOUNT_ATTR_RDONLY;
846 attr.attr_clr = MOUNT_ATTR_NODEV;
850 A user-space application that wishes to determine which extensions the running
851 kernel supports can do so by conducting a binary search on
853 with a structure which has every byte nonzero
854 (to find the largest value which doesn't produce an error of
859 * This program allows the caller to create a new detached mount
860 * and set various properties on it.
866 #include <linux/mount.h>
867 #include <linux/types.h>
872 #include <sys/syscall.h>
876 mount_setattr(int dfd, const char *path, unsigned int flags,
877 struct mount_attr *attr, size_t size)
879 return syscall(SYS_mount_setattr, dfd, path, flags, attr, size);
883 open_tree(int dfd, const char *filename,
886 return syscall(SYS_open_tree, dfd, filename, flags);
890 move_mount(int from_dfd, const char *from_pathname,
891 int to_dfd, const char *to_pathname, unsigned int flags)
893 return syscall(SYS_move_mount, from_dfd, from_pathname,
894 to_dfd, to_pathname, flags);
897 static const struct option longopts[] = {
898 {"map-mount", required_argument, NULL, 'a'},
899 {"recursive", no_argument, NULL, 'b'},
900 {"read-only", no_argument, NULL, 'c'},
901 {"block-setid", no_argument, NULL, 'd'},
902 {"block-devices", no_argument, NULL, 'e'},
903 {"block-exec", no_argument, NULL, 'f'},
904 {"no-access-time", no_argument, NULL, 'g'},
905 { NULL, 0, NULL, 0 },
908 #define exit_log(format, ...) do \e
910 fprintf(stderr, format, ##__VA_ARGS__); \e
911 exit(EXIT_FAILURE); \e
915 main(int argc, char *argv[])
917 int fd_userns = \-EBADF;
919 bool recursive = false;
920 struct mount_attr *attr = &(struct mount_attr){};
921 const char *source, *target;
922 int fd_tree, new_argc, ret;
923 const char *const *new_argv;
925 while ((ret = getopt_long_only(argc, argv, "",
926 longopts, &index)) != \-1) {
929 fd_userns = open(optarg, O_RDONLY | O_CLOEXEC);
930 if (fd_userns == \-1)
931 exit_log("%m \- Failed top open %s\en", optarg);
937 attr->attr_set |= MOUNT_ATTR_RDONLY;
940 attr->attr_set |= MOUNT_ATTR_NOSUID;
943 attr->attr_set |= MOUNT_ATTR_NODEV;
946 attr->attr_set |= MOUNT_ATTR_NOEXEC;
949 attr->attr_set |= MOUNT_ATTR_NOATIME;
950 attr->attr_clr |= MOUNT_ATTR__ATIME;
953 exit_log("Invalid argument specified");
957 new_argv = &argv[optind];
958 new_argc = argc \- optind;
960 exit_log("Missing source or target mount point\en");
961 source = new_argv[0];
962 target = new_argv[1];
964 fd_tree = open_tree(\-EBADF, source,
968 (recursive ? AT_RECURSIVE : 0));
970 exit_log("%m \- Failed to open %s\en", source);
972 if (fd_userns >= 0) {
973 attr->attr_set |= MOUNT_ATTR_IDMAP;
974 attr->userns_fd = fd_userns;
976 ret = mount_setattr(fd_tree, "",
978 (recursive ? AT_RECURSIVE : 0),
979 attr, sizeof(struct mount_attr));
981 exit_log("%m - Failed to change mount attributes\en");
984 ret = move_mount(fd_tree, "", \-EBADF, target,
985 MOVE_MOUNT_F_EMPTY_PATH);
987 exit_log("%m \- Failed to attach mount to %s\en", target);
1000 .BR mount_namespaces (7),
1001 .BR capabilities (7),
1002 .BR user_namespaces (7),