Manual pages: nsenter.1, unshare.1: add a reference to time_namespaces(7)

[thirdparty/util-linux.git] / sys-utils / unshare.1

diff --git a/sys-utils/unshare.1 b/sys-utils/unshare.1
index 957f7017182f82bbf627c1eb62a067c6e700953b..db67b0d4c23b5df350b5f8dbd148db10348fc203 100644 (file)
--- a/sys-utils/unshare.1
+++ b/sys-utils/unshare.1
@@ -18,7 +18,11 @@ even after the \fIprogram\fR terminates (except PID namespaces where
 permanently running init process is required).
 Once a persistent \%namespace is no longer needed, it can be unpersisted with
 .BR umount (8).
-See the \fBEXAMPLES\fR section for more details.
+See the \fBEXAMPLE\fR section for more details.
+.PP
+.B unshare
+since util-linux version 2.36 uses /\fIproc/[pid]/ns/pid_for_children\fP and \fI/proc/[pid]/ns/time_for_children\fP
+files for persistent PID and TIME namespaces. This change requires Linux kernel 4.17 or newer.
 .PP
 The namespaces to be unshared are indicated via options.  Unshareable namespaces are:
 .TP
@@ -44,7 +48,7 @@ Note that \fBprivate\fP is the kernel default.
 .B UTS namespace
 Setting hostname or domainname will not affect the rest of the system.
 For further details, see
-.BR namespaces (7)
+.BR uts_namespaces (7)
 and the discussion of the
 .B CLONE_NEWUTS
 flag in
@@ -55,7 +59,7 @@ The process will have an independent namespace for POSIX message queues
 as well as System V \%message queues,
 semaphore sets and shared memory segments.
 For further details, see
-.BR namespaces (7)
+.BR ipc_namespaces (7)
 and the discussion of the
 .B CLONE_NEWIPC
 flag in
@@ -66,7 +70,7 @@ The process will have independent IPv4 and IPv6 stacks, IP routing tables,
 firewall rules, the \fI/proc/net\fP and \fI/sys/class/net\fP directory trees,
 sockets, etc.
 For further details, see
-.BR namespaces (7)
+.BR network_namespaces (7)
 and the discussion of the
 .B CLONE_NEWNET
 flag in
@@ -107,6 +111,8 @@ The process can have a distinct view of
 and/or
 .B CLOCK_BOOTTIME
 which can be changed using \fI/proc/self/timens_offsets\fP.
+For further details, see
+.BR time_namespaces (7).
 .SH OPTIONS
 .TP
 .BR \-i , " \-\-ipc" [ =\fIfile ]
@@ -169,6 +175,16 @@ implies creating a new mount namespace since the /proc mount would otherwise
 mess up existing programs on the system.  The new proc filesystem is explicitly
 mounted as private (with MS_PRIVATE|MS_REC).
 .TP
+.BI \-\-map\-user= uid|name
+Run the program only after the current effective user ID has been mapped to \fIuid\fP.
+If this option is specified multiple times, the last occurrence takes precedence.
+This option implies \fB\-\-user\fR.
+.TP
+.BI \-\-map\-group= gid|name
+Run the program only after the current effective group ID has been mapped to \fIgid\fP.
+If this option is specified multiple times, the last occurrence takes precedence.
+This option implies \fB\-\-setgroups=deny\fR and \fB\-\-user\fR.
+.TP
 .BR \-r , " \-\-map\-root\-user"
 Run the program only after the current effective user and group IDs have been mapped to
 the superuser UID and GID in the newly created user namespace.  This makes it possible to
@@ -177,11 +193,13 @@ namespaces (such as configuring interfaces in the network namespace or mounting
 the mount namespace) even when run unprivileged.  As a mere convenience feature, it does not support
 more sophisticated use cases, such as mapping multiple ranges of UIDs and GIDs.
 This option implies \fB\-\-setgroups=deny\fR and \fB\-\-user\fR.
+This option is equivalent to \fB\-\-map-user=0 \-\-map-group=0\fR.
 .TP
 .BR \-c , " \-\-map\-current\-user"
 Run the program only after the current effective user and group IDs have been mapped to
 the same UID and GID in the newly created user namespace. This option implies
 \fB\-\-setgroups=deny\fR and \fB\-\-user\fR.
+This option is equivalent to \fB\-\-map-user=$(id -ru) \-\-map-group=$(id -rg)\fR.
 .TP
 .BR "\-\-propagation private" | shared | slave | unchanged
 Recursively set the mount propagation flag in the new mount namespace.  The default
@@ -221,13 +239,13 @@ Set the user ID which will be used in the entered namespace.
 Set the group ID which will be used in the entered namespace and drop
 supplementary groups.
 .TP
-.BR "\-\-monotonic \fIoffset"
+.BI \-\-monotonic " offset"
 Set the offset of
 .B CLOCK_MONOTONIC
 which will be used in the entered time namespace. This option requires
 unsharing a time namespace with \fB\-\-time\fP.
 .TP
-.BR "\-\-boottime \fIoffset"
+.BI \-\-boottime " offset"
 Set the offset of
 .B CLOCK_BOOTTIME
 which will be used in the entered time namespace. This option requires
@@ -243,7 +261,7 @@ The proc and sysfs filesystems mounting as root in a user namespace have to be
 restricted so that a less privileged user can not get more access to sensitive
 files that a more privileged user made unavailable. In short the rule for proc
 and sysfs is as close to a bind mount as possible.
-.SH EXAMPLES
+.SH EXAMPLE
 .TP
 .B # unshare \-\-fork \-\-pid \-\-mount-proc readlink /proc/self
 .TQ
@@ -299,11 +317,6 @@ been re-parented to PID 1.
 .TQ
  10:58:48 up 1158 days,  6:05,  1 user,  load average: 0.00, 0.00, 0.00
 
-.SH SEE ALSO
-.BR clone (2),
-.BR unshare (2),
-.BR namespaces (7),
-.BR mount (8)
 .SH AUTHORS
 .UR dottedmag@dottedmag.net
 Mikhail Gusarov
@@ -312,6 +325,11 @@ Mikhail Gusarov
 .UR kzak@redhat.com
 Karel Zak
 .UE
+.SH SEE ALSO
+.BR clone (2),
+.BR unshare (2),
+.BR namespaces (7),
+.BR mount (8)
 .SH AVAILABILITY
 The unshare command is part of the util-linux package and is available from
 https://www.kernel.org/pub/linux/utils/util-linux/.