Debian Codegraph @

upstream/debian-trixie/man2/mount_setattr.2

raw
1 .\" Copyright (c) 2021 by Christian Brauner <[email protected]>
2 .\"
3 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
4 .\"
5 .TH mount_setattr 2 2024-05-02 "Linux man-pages 6.9.1"
6 .SH NAME
7 mount_setattr \- change properties of a mount or mount tree
8 .SH LIBRARY
9 Standard C library
10 .RI ( libc ", " \-lc )
11 .SH SYNOPSIS
12 .nf
13 .BR "#include <linux/fcntl.h>" " /* Definition of " AT_* " constants */"
14 .BR "#include <linux/mount.h>" " /* Definition of " MOUNT_ATTR_* " constants */"
15 .BR "#include <sys/syscall.h>" " /* Definition of " SYS_* " constants */"
16 .B #include <unistd.h>
17 .P
18 .BI "int syscall(SYS_mount_setattr, int " dirfd ", const char *" pathname ,
19 .BI " unsigned int " flags ", struct mount_attr *" attr \
20 ", size_t " size );
21 .fi
22 .P
23 .IR Note :
24 glibc provides no wrapper for
25 .BR mount_setattr (),
26 necessitating the use of
27 .BR syscall (2).
28 .SH DESCRIPTION
29 The
30 .BR mount_setattr ()
31 system call changes the mount properties of a mount or an entire mount tree.
32 If
33 .I pathname
34 is a relative pathname,
35 then it is interpreted relative to
36 the directory referred to by the file descriptor
37 .IR dirfd .
38 If
39 .I dirfd
40 is the special value
41 .BR AT_FDCWD ,
42 then
43 .I pathname
44 is interpreted relative to
45 the current working directory of the calling process.
46 If
47 .I pathname
48 is the empty string and
49 .B AT_EMPTY_PATH
50 is specified in
51 .IR flags ,
52 then the mount properties of the mount identified by
53 .I dirfd
54 are changed.
55 (See
56 .BR openat (2)
57 for an explanation of why the
58 .I dirfd
59 argument is useful.)
60 .P
61 The
62 .BR mount_setattr ()
63 system call uses an extensible structure
64 .RI ( "struct mount_attr" )
65 to allow for future extensions.
66 Any non-flag extensions to
67 .BR mount_setattr ()
68 will be implemented as new fields appended to the this structure,
69 with a zero value in a new field resulting in the kernel behaving
70 as though that extension field was not present.
71 Therefore,
72 the caller
73 .I must
74 zero-fill this structure on initialization.
75 See the "Extensibility" subsection under
76 .B NOTES
77 for more details.
78 .P
79 The
80 .I size
81 argument should usually be specified as
82 .IR "sizeof(struct mount_attr)" .
83 However, if the caller is using a kernel that supports an extended
84 .IR "struct mount_attr" ,
85 but the caller does not intend to make use of these features,
86 it is possible to pass the size of an earlier
87 version of the structure together with the extended structure.
88 This allows the kernel to not copy later parts of the structure
89 that aren't used anyway.
90 With each extension that changes the size of
91 .IR "struct mount_attr" ,
92 the kernel will expose a definition of the form
93 .BI MOUNT_ATTR_SIZE_VER number\c
94 \&.
95 For example, the macro for the size of the initial version of
96 .I struct mount_attr
97 is
98 .BR MOUNT_ATTR_SIZE_VER0 .
99 .P
100 The
101 .I flags
102 argument can be used to alter the pathname resolution behavior.
103 The supported values are:
104 .TP
105 .B AT_EMPTY_PATH
106 If
107 .I pathname
108 is the empty string,
109 change the mount properties on
110 .I dirfd
111 itself.
112 .TP
113 .B AT_RECURSIVE
114 Change the mount properties of the entire mount tree.
115 .TP
116 .B AT_SYMLINK_NOFOLLOW
117 Don't follow trailing symbolic links.
118 .TP
119 .B AT_NO_AUTOMOUNT
120 Don't trigger automounts.
121 .P
122 The
123 .I attr
124 argument of
125 .BR mount_setattr ()
126 is a structure of the following form:
127 .P
128 .in +4n
129 .EX
130 struct mount_attr {
131 __u64 attr_set; /* Mount properties to set */
132 __u64 attr_clr; /* Mount properties to clear */
133 __u64 propagation; /* Mount propagation type */
134 __u64 userns_fd; /* User namespace file descriptor */
135 };
136 .EE
137 .in
138 .P
139 The
140 .I attr_set
141 and
142 .I attr_clr
143 members are used to specify the mount properties that
144 are supposed to be set or cleared for a mount or mount tree.
145 Flags set in
146 .I attr_set
147 enable a property on a mount or mount tree,
148 and flags set in
149 .I attr_clr
150 remove a property from a mount or mount tree.
151 .P
152 When changing mount properties,
153 the kernel will first clear the flags specified
154 in the
155 .I attr_clr
156 field,
157 and then set the flags specified in the
158 .I attr_set
159 field.
160 For example, these settings:
161 .P
162 .in +4n
163 .EX
164 struct mount_attr attr = {
165 .attr_clr = MOUNT_ATTR_NOEXEC | MOUNT_ATTR_NODEV,
166 .attr_set = MOUNT_ATTR_RDONLY | MOUNT_ATTR_NOSUID,
167 };
168 .EE
169 .in
170 .P
171 are equivalent to the following steps:
172 .P
173 .in +4n
174 .EX
175 unsigned int current_mnt_flags = mnt\->mnt_flags;
176 \&
177 /*
178 * Clear all flags set in .attr_clr,
179 * clearing MOUNT_ATTR_NOEXEC and MOUNT_ATTR_NODEV.
180 */
181 current_mnt_flags &= \(tiattr\->attr_clr;
182 \&
183 /*
184 * Now set all flags set in .attr_set,
185 * applying MOUNT_ATTR_RDONLY and MOUNT_ATTR_NOSUID.
186 */
187 current_mnt_flags |= attr\->attr_set;
188 \&
189 mnt\->mnt_flags = current_mnt_flags;
190 .EE
191 .in
192 .P
193 As a result of this change, the mount or mount tree (a) is read-only;
194 (b) blocks the execution of set-user-ID and set-group-ID programs;
195 (c) allows execution of programs; and (d) allows access to devices.
196 .P
197 Multiple changes with the same set of flags requested
198 in
199 .I attr_clr
200 and
201 .I attr_set
202 are guaranteed to be idempotent after the changes have been applied.
203 .P
204 The following mount attributes can be specified in the
205 .I attr_set
206 or
207 .I attr_clr
208 fields:
209 .TP
210 .B MOUNT_ATTR_RDONLY
211 If set in
212 .IR attr_set ,
213 makes the mount read-only.
214 If set in
215 .IR attr_clr ,
216 removes the read-only setting if set on the mount.
217 .TP
218 .B MOUNT_ATTR_NOSUID
219 If set in
220 .IR attr_set ,
221 causes the mount not to honor the set-user-ID and set-group-ID mode bits and
222 file capabilities when executing programs.
223 If set in
224 .IR attr_clr ,
225 clears the set-user-ID, set-group-ID,
226 and file capability restriction if set on this mount.
227 .TP
228 .B MOUNT_ATTR_NODEV
229 If set in
230 .IR attr_set ,
231 prevents access to devices on this mount.
232 If set in
233 .IR attr_clr ,
234 removes the restriction that prevented accessing devices on this mount.
235 .TP
236 .B MOUNT_ATTR_NOEXEC
237 If set in
238 .IR attr_set ,
239 prevents executing programs on this mount.
240 If set in
241 .IR attr_clr ,
242 removes the restriction that prevented executing programs on this mount.
243 .TP
244 .B MOUNT_ATTR_NOSYMFOLLOW
245 If set in
246 .IR attr_set ,
247 prevents following symbolic links on this mount.
248 If set in
249 .IR attr_clr ,
250 removes the restriction that prevented following symbolic links on this mount.
251 .TP
252 .B MOUNT_ATTR_NODIRATIME
253 If set in
254 .IR attr_set ,
255 prevents updating access time for directories on this mount.
256 If set in
257 .IR attr_clr ,
258 removes the restriction that prevented updating access time for directories.
259 Note that
260 .B MOUNT_ATTR_NODIRATIME
261 can be combined with other access-time settings
262 and is implied by the noatime setting.
263 All other access-time settings are mutually exclusive.
264 .TP
265 .BR MOUNT_ATTR__ATIME " - changing access-time settings"
266 The access-time values listed below are an enumeration that
267 includes the value zero, expressed in the bits defined by the mask
268 .BR MOUNT_ATTR__ATIME .
269 Even though these bits are an enumeration
270 (in contrast to the other mount flags such as
271 .BR MOUNT_ATTR_NOEXEC ),
272 they are nonetheless passed in
273 .I attr_set
274 and
275 .I attr_clr
276 for consistency with
277 .BR fsmount (2),
278 which introduced this behavior.
279 .IP
280 Note that,
281 since the access-time values are an enumeration rather than bit values,
282 a caller wanting to transition to a different access-time setting
283 cannot simply specify the access-time setting in
284 .IR attr_set ,
285 but must also include
286 .B MOUNT_ATTR__ATIME
287 in the
288 .I attr_clr
289 field.
290 The kernel will verify that
291 .B MOUNT_ATTR__ATIME
292 isn't partially set in
293 .I attr_clr
294 (i.e., either all bits in the
295 .B MOUNT_ATTR__ATIME
296 bit field are either set or clear), and that
297 .I attr_set
298 doesn't have any access-time bits set if
299 .B MOUNT_ATTR__ATIME
300 isn't set in
301 .IR attr_clr .
302 .RS
303 .TP
304 .B MOUNT_ATTR_RELATIME
305 When a file is accessed via this mount,
306 update the file's last access time (atime)
307 only if the current value of atime is less than or equal to
308 the file's last modification time (mtime) or last status change time (ctime).
309 .IP
310 To enable this access-time setting on a mount or mount tree,
311 .B MOUNT_ATTR_RELATIME
312 must be set in
313 .I attr_set
314 and
315 .B MOUNT_ATTR__ATIME
316 must be set in the
317 .I attr_clr
318 field.
319 .TP
320 .B MOUNT_ATTR_NOATIME
321 Do not update access times for (all types of) files on this mount.
322 .IP
323 To enable this access-time setting on a mount or mount tree,
324 .B MOUNT_ATTR_NOATIME
325 must be set in
326 .I attr_set
327 and
328 .B MOUNT_ATTR__ATIME
329 must be set in the
330 .I attr_clr
331 field.
332 .TP
333 .B MOUNT_ATTR_STRICTATIME
334 Always update the last access time (atime)
335 when files are accessed on this mount.
336 .IP
337 To enable this access-time setting on a mount or mount tree,
338 .B MOUNT_ATTR_STRICTATIME
339 must be set in
340 .I attr_set
341 and
342 .B MOUNT_ATTR__ATIME
343 must be set in the
344 .I attr_clr
345 field.
346 .RE
347 .TP
348 .B MOUNT_ATTR_IDMAP
349 If set in
350 .IR attr_set ,
351 creates an ID-mapped mount.
352 The ID mapping is taken from the user namespace specified in
353 .I userns_fd
354 and attached to the mount.
355 .IP
356 Since it is not supported to
357 change the ID mapping of a mount after it has been ID mapped,
358 it is invalid to specify
359 .B MOUNT_ATTR_IDMAP
360 in
361 .IR attr_clr .
362 .IP
363 For further details, see the subsection "ID-mapped mounts" under NOTES.
364 .P
365 The
366 .I propagation
367 field is used to specify the propagation type of the mount or mount tree.
368 This field either has the value zero,
369 meaning leave the propagation type unchanged, or it has one of
370 the following values:
371 .TP
372 .B MS_PRIVATE
373 Turn all mounts into private mounts.
374 .TP
375 .B MS_SHARED
376 Turn all mounts into shared mounts.
377 .TP
378 .B MS_SLAVE
379 Turn all mounts into dependent mounts.
380 .TP
381 .B MS_UNBINDABLE
382 Turn all mounts into unbindable mounts.
383 .P
384 For further details on the above propagation types, see
385 .BR mount_namespaces (7).
386 .SH RETURN VALUE
387 On success,
388 .BR mount_setattr ()
389 returns zero.
390 On error,
391 \-1 is returned and
392 .I errno
393 is set to indicate the cause of the error.
394 .SH ERRORS
395 .TP
396 .B EBADF
397 .I pathname
398 is relative but
399 .I dirfd
400 is neither
401 .B AT_FDCWD
402 nor a valid file descriptor.
403 .TP
404 .B EBADF
405 .I userns_fd
406 is not a valid file descriptor.
407 .TP
408 .B EBUSY
409 The caller tried to change the mount to
410 .BR MOUNT_ATTR_RDONLY ,
411 but the mount still holds files open for writing.
412 .TP
413 .B EBUSY
414 The caller tried to create an ID-mapped mount raising
415 .B MOUNT_ATTR_IDMAP
416 and specifying
417 .I userns_fd
418 but the mount still holds files open for writing.
419 .TP
420 .B EINVAL
421 The pathname specified via the
422 .I dirfd
423 and
424 .I pathname
425 arguments to
426 .BR mount_setattr ()
427 isn't a mount point.
428 .TP
429 .B EINVAL
430 An unsupported value was set in
431 .IR flags .
432 .TP
433 .B EINVAL
434 An unsupported value was specified in the
435 .I attr_set
436 field of
437 .IR mount_attr .
438 .TP
439 .B EINVAL
440 An unsupported value was specified in the
441 .I attr_clr
442 field of
443 .IR mount_attr .
444 .TP
445 .B EINVAL
446 An unsupported value was specified in the
447 .I propagation
448 field of
449 .IR mount_attr .
450 .TP
451 .B EINVAL
452 More than one of
453 .BR MS_SHARED ,
454 .BR MS_SLAVE ,
455 .BR MS_PRIVATE ,
456 or
457 .B MS_UNBINDABLE
458 was set in the
459 .I propagation
460 field of
461 .IR mount_attr .
462 .TP
463 .B EINVAL
464 An access-time setting was specified in the
465 .I attr_set
466 field without
467 .B MOUNT_ATTR__ATIME
468 being set in the
469 .I attr_clr
470 field.
471 .TP
472 .B EINVAL
473 .B MOUNT_ATTR_IDMAP
474 was specified in
475 .IR attr_clr .
476 .TP
477 .B EINVAL
478 A file descriptor value was specified in
479 .I userns_fd
480 which exceeds
481 .BR INT_MAX .
482 .TP
483 .B EINVAL
484 A valid file descriptor value was specified in
485 .IR userns_fd ,
486 but the file descriptor did not refer to a user namespace.
487 .TP
488 .B EINVAL
489 The underlying filesystem does not support ID-mapped mounts.
490 .TP
491 .B EINVAL
492 The mount that is to be ID mapped is not a detached mount;
493 that is, the mount has not previously been visible in a mount namespace.
494 .TP
495 .B EINVAL
496 A partial access-time setting was specified in
497 .I attr_clr
498 instead of
499 .B MOUNT_ATTR__ATIME
500 being set.
501 .TP
502 .B EINVAL
503 The mount is located outside the caller's mount namespace.
504 .TP
505 .B EINVAL
506 The underlying filesystem has been mounted in a mount namespace that is
507 owned by a noninitial user namespace
508 .TP
509 .B ENOENT
510 A pathname was empty or had a nonexistent component.
511 .TP
512 .B ENOMEM
513 When changing mount propagation to
514 .BR MS_SHARED ,
515 a new peer group ID needs to be allocated for all mounts without a peer group
516 ID set.
517 This allocation failed because there was not
518 enough memory to allocate the relevant internal structures.
519 .TP
520 .B ENOSPC
521 When changing mount propagation to
522 .BR MS_SHARED ,
523 a new peer group ID needs to be allocated for all mounts without a peer group
524 ID set.
525 This allocation failed because
526 the kernel has run out of IDs.
527 .\" Christian Brauner: i.e. someone has somehow managed to
528 .\" allocate so many peer groups and managed to keep the kernel running
529 .\" (???) that the ida has ran out of ids
530 .\" Note that technically further error codes are possible that are
531 .\" specific to the ID allocation implementation used.
532 .TP
533 .B EPERM
534 One of the mounts had at least one of
535 .BR MOUNT_ATTR_NOATIME ,
536 .BR MOUNT_ATTR_NODEV ,
537 .BR MOUNT_ATTR_NODIRATIME ,
538 .BR MOUNT_ATTR_NOEXEC ,
539 .BR MOUNT_ATTR_NOSUID ,
540 or
541 .B MOUNT_ATTR_RDONLY
542 set and the flag is locked.
543 Mount attributes become locked on a mount if:
544 .RS
545 .IP \[bu] 3
546 A new mount or mount tree is created causing mount propagation across user
547 namespaces
548 (i.e., propagation to a mount namespace owned by a different user namespace).
549 The kernel will lock the aforementioned flags to prevent these sensitive
550 properties from being altered.
551 .IP \[bu]
552 A new mount and user namespace pair is created.
553 This happens for example when specifying
554 .B CLONE_NEWUSER | CLONE_NEWNS
555 in
556 .BR unshare (2),
557 .BR clone (2),
558 or
559 .BR clone3 (2).
560 The aforementioned flags become locked in the new mount namespace
561 to prevent sensitive mount properties from being altered.
562 Since the newly created mount namespace will be owned by the
563 newly created user namespace,
564 a calling process that is privileged in the new
565 user namespace would\[em]in the absence of such locking\[em]be
566 able to alter sensitive mount properties (e.g., to remount a mount
567 that was marked read-only as read-write in the new mount namespace).
568 .RE
569 .TP
570 .B EPERM
571 A valid file descriptor value was specified in
572 .IR userns_fd ,
573 but the file descriptor refers to the initial user namespace.
574 .TP
575 .B EPERM
576 An attempt was made to add an ID mapping to a mount that is already ID mapped.
577 .TP
578 .B EPERM
579 The caller does not have
580 .B CAP_SYS_ADMIN
581 in the initial user namespace.
582 .SH STANDARDS
583 Linux.
584 .SH HISTORY
585 Linux 5.12.
586 .\" commit 7d6beb71da3cc033649d641e1e608713b8220290
587 .\" commit 2a1867219c7b27f928e2545782b86daaf9ad50bd
588 .\" commit 9caccd41541a6f7d6279928d9f971f6642c361af
589 .SH NOTES
590 .SS ID-mapped mounts
591 Creating an ID-mapped mount makes it possible to
592 change the ownership of all files located under a mount.
593 Thus, ID-mapped mounts make it possible to
594 change ownership in a temporary and localized way.
595 It is a localized change because the ownership changes are
596 visible only via a specific mount.
597 All other users and locations where the filesystem is exposed are unaffected.
598 It is a temporary change because
599 the ownership changes are tied to the lifetime of the mount.
600 .P
601 Whenever callers interact with the filesystem through an ID-mapped mount,
602 the ID mapping of the mount will be applied to
603 user and group IDs associated with filesystem objects.
604 This encompasses the user and group IDs associated with inodes
605 and also the following
606 .BR xattr (7)
607 keys:
608 .IP \[bu] 3
609 .IR security.capability ,
610 whenever filesystem capabilities
611 are stored or returned in the
612 .B VFS_CAP_REVISION_3
613 format,
614 which stores a root user ID alongside the capabilities
615 (see
616 .BR capabilities (7)).
617 .IP \[bu]
618 .I system.posix_acl_access
619 and
620 .IR system.posix_acl_default ,
621 whenever user IDs or group IDs are stored in
622 .B ACL_USER
623 or
624 .B ACL_GROUP
625 entries.
626 .P
627 The following conditions must be met in order to create an ID-mapped mount:
628 .IP \[bu] 3
629 The caller must have the
630 .B CAP_SYS_ADMIN
631 capability in the user namespace the filesystem was mounted in.
632 .\" commit bd303368b776eead1c29e6cdda82bde7128b82a7
633 .\" Christian Brauner
634 .\" Note, currently no filesystems mountable in non-initial user namespaces
635 .\" support ID-mapped mounts.
636 .IP \[bu]
637 The underlying filesystem must support ID-mapped mounts.
638 Currently, the following filesystems support ID-mapped mounts:
639 .\" fs_flags = FS_ALLOW_IDMAP in kernel sources
640 .RS
641 .IP \[bu] 3
642 .PD 0
643 .BR xfs (5)
644 (since Linux 5.12)
645 .IP \[bu]
646 .BR ext4 (5)
647 (since Linux 5.12)
648 .IP \[bu]
649 .B FAT
650 (since Linux 5.12)
651 .IP \[bu]
652 .BR btrfs (5)
653 (since Linux 5.15)
654 .\" commit 5b9b26f5d0b88b74001dcfe4ab8a8f2f4e744112
655 .IP \[bu]
656 .B ntfs3
657 (since Linux 5.15)
658 .\" commit 82cae269cfa953032fbb8980a7d554d60fb00b17
659 .IP \[bu]
660 .B f2fs
661 (since Linux 5.18)
662 .\" commit 984fc4e76d63345499f01c0c198a4b44860cf027
663 .IP \[bu]
664 .B erofs
665 (since Linux 5.19)
666 .\" commit 6c459b78d4793afbba6d864c466cc5cd2932459d
667 .IP \[bu]
668 .B overlayfs
669 (ID-mapped lower and upper layers supported since Linux 5.19)
670 .IP \[bu]
671 .B squashfs
672 (since Linux 6.2)
673 .IP \[bu]
674 .B tmpfs
675 (since Linux 6.3)
676 .IP \[bu]
677 .B cephfs
678 (since Linux 6.7)
679 .IP \[bu]
680 .B hugetlbfs
681 (since Linux 6.9)
682 .PD
683 .RE
684 .IP \[bu]
685 The mount must not already be ID-mapped.
686 This also implies that the ID mapping of a mount cannot be altered.
687 .IP \[bu]
688 The mount must not have any writers.
689 .\" commit 1bbcd277a53e08d619ffeec56c5c9287f2bf42f
690 .IP \[bu]
691 The mount must be a detached mount;
692 that is,
693 it must have been created by calling
694 .BR open_tree (2)
695 with the
696 .B OPEN_TREE_CLONE
697 flag and it must not already have been visible in a mount namespace.
698 (To put things another way:
699 the mount must not have been attached to the filesystem hierarchy
700 with a system call such as
701 .BR move_mount (2).)
702 .P
703 ID mappings can be created for user IDs, group IDs, and project IDs.
704 An ID mapping is essentially a mapping of a range of user or group IDs into
705 another or the same range of user or group IDs.
706 ID mappings are written to map files as three numbers
707 separated by white space.
708 The first two numbers specify the starting user or group ID
709 in each of the two user namespaces.
710 The third number specifies the range of the ID mapping.
711 For example,
712 a mapping for user IDs such as "1000\ 1001\ 1" would indicate that
713 user ID 1000 in the caller's user namespace is mapped to
714 user ID 1001 in its ancestor user namespace.
715 Since the map range is 1,
716 only user ID 1000 is mapped.
717 .P
718 It is possible to specify up to 340 ID mappings for each ID mapping type.
719 If any user IDs or group IDs are not mapped,
720 all files owned by that unmapped user or group ID will appear as
721 being owned by the overflow user ID or overflow group ID respectively.
722 .P
723 Further details on setting up ID mappings can be found in
724 .BR user_namespaces (7).
725 .P
726 In the common case, the user namespace passed in
727 .I userns_fd
728 (together with
729 .B MOUNT_ATTR_IDMAP
730 in
731 .IR attr_set )
732 to create an ID-mapped mount will be the user namespace of a container.
733 In other scenarios it will be a dedicated user namespace associated with
734 a user's login session as is the case for portable home directories in
735 .BR systemd-homed.service (8)).
736 It is also perfectly fine to create a dedicated user namespace
737 for the sake of ID mapping a mount.
738 .P
739 ID-mapped mounts can be useful in the following
740 and a variety of other scenarios:
741 .IP \[bu] 3
742 Sharing files or filesystems
743 between multiple users or multiple machines,
744 especially in complex scenarios.
745 For example,
746 ID-mapped mounts are used to implement portable home directories in
747 .BR systemd-homed.service (8),
748 where they allow users to move their home directory
749 to an external storage device
750 and use it on multiple computers
751 where they are assigned different user IDs and group IDs.
752 This effectively makes it possible to
753 assign random user IDs and group IDs at login time.
754 .IP \[bu]
755 Sharing files or filesystems
756 from the host with unprivileged containers.
757 This allows a user to avoid having to change ownership permanently through
758 .BR chown (2).
759 .IP \[bu]
760 ID mapping a container's root filesystem.
761 Users don't need to change ownership permanently through
762 .BR chown (2).
763 Especially for large root filesystems, using
764 .BR chown (2)
765 can be prohibitively expensive.
766 .IP \[bu]
767 Sharing files or filesystems
768 between containers with non-overlapping ID mappings.
769 .IP \[bu]
770 Implementing discretionary access (DAC) permission checking
771 for filesystems lacking a concept of ownership.
772 .IP \[bu]
773 Efficiently changing ownership on a per-mount basis.
774 In contrast to
775 .BR chown (2),
776 changing ownership of large sets of files is instantaneous with
777 ID-mapped mounts.
778 This is especially useful when ownership of
779 an entire root filesystem of a virtual machine or container
780 is to be changed as mentioned above.
781 With ID-mapped mounts,
782 a single
783 .BR mount_setattr ()
784 system call will be sufficient to change the ownership of all files.
785 .IP \[bu]
786 Taking the current ownership into account.
787 ID mappings specify precisely
788 what a user or group ID is supposed to be mapped to.
789 This contrasts with the
790 .BR chown (2)
791 system call which cannot by itself
792 take the current ownership of the files it changes into account.
793 It simply changes the ownership to the specified user ID and group ID.
794 .IP \[bu]
795 Locally and temporarily restricted ownership changes.
796 ID-mapped mounts make it possible to change ownership locally,
797 restricting the ownership changes to specific mounts,
798 and temporarily as the ownership changes only apply as long as the mount exists.
799 By contrast,
800 changing ownership via the
801 .BR chown (2)
802 system call changes the ownership globally and permanently.
803 .\"
804 .SS Extensibility
805 In order to allow for future extensibility,
806 .BR mount_setattr ()
807 requires the user-space application to specify the size of the
808 .I mount_attr
809 structure that it is passing.
810 By providing this information, it is possible for
811 .BR mount_setattr ()
812 to provide both forwards- and backwards-compatibility, with
813 .I size
814 acting as an implicit version number.
815 (Because new extension fields will always
816 be appended, the structure size will always increase.)
817 This extensibility design is very similar to other system calls such as
818 .BR perf_setattr (2),
819 .BR perf_event_open (2),
820 .BR clone3 (2)
821 and
822 .BR openat2 (2).
823 .P
824 Let
825 .I usize
826 be the size of the structure as specified by the user-space application,
827 and let
828 .I ksize
829 be the size of the structure which the kernel supports,
830 then there are three cases to consider:
831 .IP \[bu] 3
832 If
833 .I ksize
834 equals
835 .IR usize ,
836 then there is no version mismatch and
837 .I attr
838 can be used verbatim.
839 .IP \[bu]
840 If
841 .I ksize
842 is larger than
843 .IR usize ,
844 then there are some extension fields that the kernel supports
845 which the user-space application is unaware of.
846 Because a zero value in any added extension field signifies a no-op,
847 the kernel treats all of the extension fields
848 not provided by the user-space application
849 as having zero values.
850 This provides backwards-compatibility.
851 .IP \[bu]
852 If
853 .I ksize
854 is smaller than
855 .IR usize ,
856 then there are some extension fields which the user-space application is aware
857 of but which the kernel does not support.
858 Because any extension field must have its zero values signify a no-op,
859 the kernel can safely ignore the unsupported extension fields
860 if they are all zero.
861 If any unsupported extension fields are non-zero,
862 then \-1 is returned and
863 .I errno
864 is set to
865 .BR E2BIG .
866 This provides forwards-compatibility.
867 .P
868 Because the definition of
869 .I struct mount_attr
870 may change in the future
871 (with new fields being added when system headers are updated),
872 user-space applications should zero-fill
873 .I struct mount_attr
874 to ensure that recompiling the program with new headers will not result in
875 spurious errors at run time.
876 The simplest way is to use a designated initializer:
877 .P
878 .in +4n
879 .EX
880 struct mount_attr attr = {
881 .attr_set = MOUNT_ATTR_RDONLY,
882 .attr_clr = MOUNT_ATTR_NODEV
883 };
884 .EE
885 .in
886 .P
887 Alternatively, the structure can be zero-filled using
888 .BR memset (3)
889 or similar functions:
890 .P
891 .in +4n
892 .EX
893 struct mount_attr attr;
894 memset(&attr, 0, sizeof(attr));
895 attr.attr_set = MOUNT_ATTR_RDONLY;
896 attr.attr_clr = MOUNT_ATTR_NODEV;
897 .EE
898 .in
899 .P
900 A user-space application that wishes to determine which extensions the running
901 kernel supports can do so by conducting a binary search on
902 .I size
903 with a structure which has every byte nonzero
904 (to find the largest value which doesn't produce an error of
905 .BR E2BIG ).
906 .SH EXAMPLES
907 .\" SRC BEGIN (mount_setattr.c)
908 .EX
909 /*
910 * This program allows the caller to create a new detached mount
911 * and set various properties on it.
912 */
913 #define _GNU_SOURCE
914 #include <err.h>
915 #include <fcntl.h>
916 #include <getopt.h>
917 #include <linux/mount.h>
918 #include <linux/types.h>
919 #include <stdbool.h>
920 #include <stdio.h>
921 #include <stdlib.h>
922 #include <string.h>
923 #include <sys/syscall.h>
924 #include <unistd.h>
925 \&
926 static inline int
927 mount_setattr(int dirfd, const char *pathname, unsigned int flags,
928 struct mount_attr *attr, size_t size)
929 {
930 return syscall(SYS_mount_setattr, dirfd, pathname, flags,
931 attr, size);
932 }
933 \&
934 static inline int
935 open_tree(int dirfd, const char *filename, unsigned int flags)
936 {
937 return syscall(SYS_open_tree, dirfd, filename, flags);
938 }
939 \&
940 static inline int
941 move_mount(int from_dirfd, const char *from_pathname,
942 int to_dirfd, const char *to_pathname, unsigned int flags)
943 {
944 return syscall(SYS_move_mount, from_dirfd, from_pathname,
945 to_dirfd, to_pathname, flags);
946 }
947 \&
948 static const struct option longopts[] = {
949 {"map\-mount", required_argument, NULL, \[aq]a\[aq]},
950 {"recursive", no_argument, NULL, \[aq]b\[aq]},
951 {"read\-only", no_argument, NULL, \[aq]c\[aq]},
952 {"block\-setid", no_argument, NULL, \[aq]d\[aq]},
953 {"block\-devices", no_argument, NULL, \[aq]e\[aq]},
954 {"block\-exec", no_argument, NULL, \[aq]f\[aq]},
955 {"no\-access\-time", no_argument, NULL, \[aq]g\[aq]},
956 { NULL, 0, NULL, 0 },
957 };
958 \&
959 int
960 main(int argc, char *argv[])
961 {
962 int fd_userns = \-1;
963 int fd_tree;
964 int index = 0;
965 int ret;
966 bool recursive = false;
967 const char *source;
968 const char *target;
969 struct mount_attr *attr = &(struct mount_attr){};
970 \&
971 while ((ret = getopt_long_only(argc, argv, "",
972 longopts, &index)) != \-1) {
973 switch (ret) {
974 case \[aq]a\[aq]:
975 fd_userns = open(optarg, O_RDONLY | O_CLOEXEC);
976 if (fd_userns == \-1)
977 err(EXIT_FAILURE, "open(%s)", optarg);
978 break;
979 case \[aq]b\[aq]:
980 recursive = true;
981 break;
982 case \[aq]c\[aq]:
983 attr\->attr_set |= MOUNT_ATTR_RDONLY;
984 break;
985 case \[aq]d\[aq]:
986 attr\->attr_set |= MOUNT_ATTR_NOSUID;
987 break;
988 case \[aq]e\[aq]:
989 attr\->attr_set |= MOUNT_ATTR_NODEV;
990 break;
991 case \[aq]f\[aq]:
992 attr\->attr_set |= MOUNT_ATTR_NOEXEC;
993 break;
994 case \[aq]g\[aq]:
995 attr\->attr_set |= MOUNT_ATTR_NOATIME;
996 attr\->attr_clr |= MOUNT_ATTR__ATIME;
997 break;
998 default:
999 errx(EXIT_FAILURE, "Invalid argument specified");
1000 }
1001 }
1002 \&
1003 if ((argc \- optind) < 2)
1004 errx(EXIT_FAILURE, "Missing source or target mount point");
1005 \&
1006 source = argv[optind];
1007 target = argv[optind + 1];
1008 \&
1009 /* In the following, \-1 as the \[aq]dirfd\[aq] argument ensures that
1010 open_tree() fails if \[aq]source\[aq] is not an absolute pathname. */
1011 .\" Christian Brauner
1012 .\" When writing programs I like to never use relative paths with AT_FDCWD
1013 .\" because. Because making assumptions about the current working directory
1014 .\" of the calling process is just too easy to get wrong; especially when
1015 .\" pivot_root() or chroot() are in play.
1016 .\" My absolut preference (joke intended) is to open a well-known starting
1017 .\" point with an absolute path to get a dirfd and then scope all future
1018 .\" operations beneath that dirfd. This already works with old-style
1019 .\" openat() and _very_ cautious programming but openat2() and its
1020 .\" resolve-flag space have made this **chef's kiss**.
1021 .\" If I can't operate based on a well-known dirfd I use absolute paths
1022 .\" with a -EBADF dirfd passed to *at() functions.
1023 \&
1024 fd_tree = open_tree(\-1, source,
1025 OPEN_TREE_CLONE | OPEN_TREE_CLOEXEC |
1026 AT_EMPTY_PATH | (recursive ? AT_RECURSIVE : 0));
1027 if (fd_tree == \-1)
1028 err(EXIT_FAILURE, "open(%s)", source);
1029 \&
1030 if (fd_userns >= 0) {
1031 attr\->attr_set |= MOUNT_ATTR_IDMAP;
1032 attr\->userns_fd = fd_userns;
1033 }
1034 \&
1035 ret = mount_setattr(fd_tree, "",
1036 AT_EMPTY_PATH | (recursive ? AT_RECURSIVE : 0),
1037 attr, sizeof(struct mount_attr));
1038 if (ret == \-1)
1039 err(EXIT_FAILURE, "mount_setattr");
1040 \&
1041 close(fd_userns);
1042 \&
1043 /* In the following, \-1 as the \[aq]to_dirfd\[aq] argument ensures that
1044 open_tree() fails if \[aq]target\[aq] is not an absolute pathname. */
1045 \&
1046 ret = move_mount(fd_tree, "", \-1, target,
1047 MOVE_MOUNT_F_EMPTY_PATH);
1048 if (ret == \-1)
1049 err(EXIT_FAILURE, "move_mount() to %s", target);
1050 \&
1051 close(fd_tree);
1052 \&
1053 exit(EXIT_SUCCESS);
1054 }
1055 .EE
1056 .\" SRC END
1057 .SH SEE ALSO
1058 .BR newgidmap (1),
1059 .BR newuidmap (1),
1060 .BR clone (2),
1061 .BR mount (2),
1062 .BR unshare (2),
1063 .BR proc (5),
1064 .BR capabilities (7),
1065 .BR mount_namespaces (7),
1066 .BR user_namespaces (7),
1067 .BR xattr (7)