Adding upstream version 2.33.1.upstream/2.33.1upstream

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 266 insertions, 0 deletions

diff --git a/sys-utils/unshare.1 b/sys-utils/unshare.1
new file mode 100644
index 0000000..746c411
--- /dev/null
+++ b/sys-utils/unshare.1
@@ -0,0 +1,266 @@
+.TH UNSHARE 1 "February 2016" "util-linux" "User Commands"
+.SH NAME
+unshare \- run program with some namespaces unshared from parent
+.SH SYNOPSIS
+.B unshare
+[options]
+.RI [ program
+.RI [ arguments ]]
+.SH DESCRIPTION
+Unshares the indicated namespaces from the parent process and then executes
+the specified \fIprogram\fR. If \fIprogram\fR is not given, then ``${SHELL}'' is
+run (default: /bin/sh).
+.PP
+The namespaces can optionally be made persistent by bind mounting
+/proc/\fIpid\fR/ns/\fItype\fR files to a filesystem path and entered with
+.BR \%nsenter (1)
+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.
+.PP
+The namespaces to be unshared are indicated via options.  Unshareable namespaces are:
+.TP
+.B mount namespace
+Mounting and unmounting filesystems will not affect the rest of the system,
+except for filesystems which are explicitly marked as
+shared (with \fBmount --make-shared\fP; see \fI/proc/self/mountinfo\fP or
+\fBfindmnt -o+PROPAGATION\fP for the \fBshared\fP flags).
+For further details, see
+.BR mount_namespaces (7)
+and the discussion of the
+.B CLONE_NEWNS
+flag in
+.BR clone (2).
+.sp
+.B unshare
+since util-linux version 2.27 automatically sets propagation to \fBprivate\fP
+in a new mount namespace to make sure that the new namespace is really
+unshared.  It's possible to disable this feature with option
+\fB\-\-propagation unchanged\fP.
+Note that \fBprivate\fP is the kernel default.
+.TP
+.B UTS namespace
+Setting hostname or domainname will not affect the rest of the system.
+For further details, see
+.BR namespaces (7)
+and the discussion of the
+.B CLONE_NEWUTS
+flag in
+.BR clone (2).
+.TP
+.B IPC namespace
+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)
+and the discussion of the
+.B CLONE_NEWIPC
+flag in
+.BR clone (2).
+.TP
+.B network namespace
+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)
+and the discussion of the
+.B CLONE_NEWNET
+flag in
+.BR clone (2).
+.TP
+.B PID namespace
+Children will have a distinct set of PID-to-process mappings from their parent.
+For further details, see
+.BR pid_namespaces (7)
+and
+the discussion of the
+.B CLONE_NEWPID
+flag in
+.BR clone (2).
+.TP
+.B cgroup namespace
+The process will have a virtualized view of \fI/proc\:/self\:/cgroup\fP, and new
+cgroup mounts will be rooted at the namespace cgroup root.
+For further details, see
+.BR cgroup_namespaces (7)
+and the discussion of the
+.B CLONE_NEWCGROUP
+flag in
+.BR clone (2).
+.TP
+.B user namespace
+The process will have a distinct set of UIDs, GIDs and capabilities.
+For further details, see
+.BR user_namespaces (7)
+and the discussion of the
+.B CLONE_NEWUSER
+flag in
+.BR clone (2).
+.SH OPTIONS
+.TP
+.BR \-i , " \-\-ipc" [ =\fIfile ]
+Unshare the IPC namespace.  If \fIfile\fP is specified, then a persistent
+namespace is created by a bind mount.
+.TP
+.BR \-m , " \-\-mount" [ =\fIfile ]
+Unshare the mount namespace.  If \fIfile\fP is specified, then a persistent
+namespace is created by a bind mount.
+Note that \fIfile\fP has to be located on a filesystem with the propagation
+flag set to \fBprivate\fP.  Use the command \fBfindmnt -o+PROPAGATION\fP
+when not sure about the current setting.  See also the examples below.
+.TP
+.BR \-n , " \-\-net" [ =\fIfile ]
+Unshare the network namespace.  If \fIfile\fP is specified, then a persistent
+namespace is created by a bind mount.
+.TP
+.BR \-p , " \-\-pid" [ =\fIfile ]
+Unshare the PID namespace.  If \fIfile\fP is specified then persistent
+namespace is created by a bind mount.  See also the \fB--fork\fP and
+\fB--mount-proc\fP options.
+.TP
+.BR \-u , " \-\-uts" [ =\fIfile ]
+Unshare the UTS namespace.  If \fIfile\fP is specified, then a persistent
+namespace is created by a bind mount.
+.TP
+.BR \-U , " \-\-user" [ =\fIfile ]
+Unshare the user namespace.  If \fIfile\fP is specified, then a persistent
+namespace is created by a bind mount.
+.TP
+.BR \-C , " \-\-cgroup"[=\fIfile\fP]
+Unshare the cgroup namespace. If \fIfile\fP is specified then persistent namespace is created
+by bind mount.
+.TP
+.BR \-f , " \-\-fork"
+Fork the specified \fIprogram\fR as a child process of \fBunshare\fR rather than
+running it directly.  This is useful when creating a new PID namespace.
+.TP
+.BR \-\-kill\-child [ =\fIsigname ]
+When \fBunshare\fR terminates, have \fIsigname\fP be sent to the forked child process.
+Combined with \fB--pid\fR this allows for an easy and reliable killing of the entire
+process tree below \fBunshare\fR.
+If not given, \fIsigname\fP defaults to \fBSIGKILL\fR.
+This option implies \fB--fork\fR.
+.TP
+.BR \-\-mount\-proc [ =\fImountpoint ]
+Just before running the program, mount the proc filesystem at \fImountpoint\fP
+(default is /proc).  This is useful when creating a new PID namespace.  It also
+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
+.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
+conveniently gain capabilities needed to manage various aspects of the newly created
+namespaces (such as configuring interfaces in the network namespace or mounting filesystems in
+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.
+.TP
+.BR "\-\-propagation private" | shared | slave | unchanged
+Recursively set the mount propagation flag in the new mount namespace.  The default
+is to set the propagation to \fIprivate\fP.  It is possible to disable this feature
+with the argument \fBunchanged\fR.  The option is silently ignored when the mount
+namespace (\fB\-\-mount\fP) is not requested.
+.TP
+.BR "\-\-setgroups allow" | deny
+Allow or deny the
+.BR setgroups (2)
+system call in a user namespace.
+.sp
+To be able to call
+.BR setgroups (2),
+the calling process must at least have CAP_SETGID.
+But since Linux 3.19 a further restriction applies:
+the kernel gives permission to call
+.BR \%setgroups (2)
+only after the GID map (\fB/proc/\fIpid\fB/gid_map\fR) has been set.
+The GID map is writable by root when
+.BR \%setgroups (2)
+is enabled (i.e. \fBallow\fR, the default), and
+the GID map becomes writable by unprivileged processes when
+.BR \%setgroups (2)
+is permanently disabled (with \fBdeny\fR).
+.TP
+.BR \-V , " \-\-version"
+Display version information and exit.
+.TP
+.BR \-h , " \-\-help"
+Display help text and exit.
+.SH NOTES
+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
+.TP
+.B # unshare --fork --pid --mount-proc readlink /proc/self
+.TQ
+1
+.br
+Establish a PID namespace, ensure we're PID 1 in it against a newly mounted
+procfs instance.
+.TP
+.B $ unshare --map-root-user --user sh -c whoami
+.TQ
+root
+.br
+Establish a user namespace as an unprivileged user with a root user within it.
+.TP
+.B # touch /root/uts-ns
+.TQ
+.B # unshare --uts=/root/uts-ns hostname FOO
+.TQ
+.B # nsenter --uts=/root/uts-ns hostname
+.TQ
+FOO
+.TQ
+.B # umount /root/uts-ns
+.br
+Establish a persistent UTS namespace, and modify the hostname.  The namespace
+is then entered with \fBnsenter\fR.  The namespace is destroyed by unmounting
+the bind reference.
+.TP
+.B # mount --bind /root/namespaces /root/namespaces
+.TQ
+.B # mount --make-private /root/namespaces
+.TQ
+.B # touch /root/namespaces/mnt
+.TQ
+.B # unshare --mount=/root/namespaces/mnt
+.br
+Establish a persistent mount namespace referenced by the bind mount
+/root/namespaces/mnt.  This example shows a portable solution, because it
+makes sure that the bind mount is created on a shared filesystem.
+.TP
+.B # unshare -pf --kill-child -- bash -c "(sleep 999 &) && sleep 1000" &
+.TQ
+.B # pid=$!
+.TQ
+.B # kill $pid
+.br
+Reliable killing of subprocesses of the \fIprogram\fR.
+When \fBunshare\fR gets killed, everything below it gets killed as well.
+Without it, the children of \fIprogram\fR would have orphaned and
+been re-parented to PID 1.
+
+.SH SEE ALSO
+.BR clone (2),
+.BR unshare (2),
+.BR namespaces (7),
+.BR mount (8)
+.SH AUTHORS
+.UR dottedmag@dottedmag.net
+Mikhail Gusarov
+.UE
+.br
+.UR kzak@redhat.com
+Karel Zak
+.UE
+.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/.