171 lines
6.0 KiB
Groff
171 lines
6.0 KiB
Groff
.TH UNSHARE 1 "July 2014" "util-linux" "User Commands"
|
|
.SH NAME
|
|
unshare \- run program with some namespaces unshared from parent
|
|
.SH SYNOPSIS
|
|
.B unshare
|
|
[options]
|
|
.I program
|
|
.RI [ arguments ]
|
|
.SH DESCRIPTION
|
|
Unshares the indicated namespaces from the parent process and then executes
|
|
the specified \fIprogram\fR.
|
|
.PP
|
|
The namespaces can optionally be persisted by bind mounting /proc/[pid]/ns/[type] files
|
|
to a filesystem path and entered with
|
|
.BR nsenter (1)
|
|
even after \fIprogram\fR terminates.
|
|
Once a persistent namespace is no longer needed it can be unpersisted with
|
|
.BR umount (8).
|
|
See EXAMPLES section for more details.
|
|
.PP
|
|
The namespaces to be unshared are indicated via options. Unshareable namespaces are:
|
|
.TP
|
|
.BR "mount namespace"
|
|
Mounting and unmounting filesystems will not affect the rest of the system
|
|
(\fBCLONE_NEWNS\fP flag), 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).
|
|
.sp
|
|
.B unshare
|
|
since util-linux version 2.27 automatically sets propagation to \fBprivate\fP
|
|
in the new mount namespace to make sure that the new namespace is really
|
|
unshared. This feature is possible to disable by option \fB\-\-propagation unchanged\fP.
|
|
Note that \fBprivate\fP is the kernel default.
|
|
.TP
|
|
.BR "UTS namespace"
|
|
Setting hostname or domainname will not affect the rest of the system.
|
|
(\fBCLONE_NEWUTS\fP flag)
|
|
.TP
|
|
.BR "IPC namespace"
|
|
The process will have an independent namespace for System V message queues,
|
|
semaphore sets and shared memory segments. (\fBCLONE_NEWIPC\fP flag)
|
|
.TP
|
|
.BR "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. (\fBCLONE_NEWNET\fP flag)
|
|
.TP
|
|
.BR "pid namespace"
|
|
Children will have a distinct set of PID to process mappings from their parent.
|
|
(\fBCLONE_NEWPID\fP flag)
|
|
.TP
|
|
.BR "user namespace"
|
|
The process will have a distinct set of UIDs, GIDs and capabilities.
|
|
(\fBCLONE_NEWUSER\fP flag)
|
|
.PP
|
|
See \fBclone\fR(2) for the exact semantics of the flags.
|
|
.SH OPTIONS
|
|
.TP
|
|
.BR \-i , " \-\-ipc"[=\fIfile\fP]
|
|
Unshare the IPC namespace. If \fIfile\fP is specified then persistent namespace is created
|
|
by bind mount.
|
|
.TP
|
|
.BR \-m , " \-\-mount"[=\fIfile\fP]
|
|
Unshare the mount namespace. If \fIfile\fP is specified then persistent namespace is created
|
|
by bind mount.
|
|
.TP
|
|
.BR \-n , " \-\-net"[=\fIfile\fP]
|
|
Unshare the network namespace. If \fIfile\fP is specified then persistent namespace is created
|
|
by bind mount.
|
|
.TP
|
|
.BR \-p , " \-\-pid"[=\fIfile\fP]
|
|
Unshare the pid namespace. If \fIfile\fP is specified then persistent namespace is created
|
|
by bind mount. See also the \fB--fork\fP and \fB--mount-proc\fP options.
|
|
.TP
|
|
.BR \-u , " \-\-uts"[=\fIfile\fP]
|
|
Unshare the UTS namespace. If \fIfile\fP is specified then persistent namespace is created
|
|
by bind mount.
|
|
.TP
|
|
.BR \-U , " \-\-user"[=\fIfile\fP]
|
|
Unshare the user 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 \-\-mount\-proc "[=\fImountpoint\fP]"
|
|
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 (by 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 --setgroups=deny.
|
|
.TP
|
|
.BR "\-\-propagation \fIprivate|shared|slave|unchanged\fP"
|
|
Recursively sets mount propagation flag in the new mount namespace. The default
|
|
is to set the propagation to \fIprivate\fP, this feature is possible to disable
|
|
by \fIunchanged\fP argument. The options is silently ignored when mount namespace (\fB\-\-mount\fP)
|
|
is not requested.
|
|
.TP
|
|
.BR "\-\-setgroups \fIallow|deny\fP"
|
|
Allow or deny
|
|
.BR setgroups (2)
|
|
syscall in user namespaces.
|
|
|
|
.BR setgroups(2)
|
|
is only callable with CAP_SETGID and CAP_SETGID in a user
|
|
namespace (since Linux 3.19) does not give you permission to call setgroups(2)
|
|
until after GID map has been set. The GID map is writable by root when
|
|
.BR setgroups(2)
|
|
is enabled and GID map becomes writable by unprivileged processes when
|
|
.BR setgroups(2)
|
|
is permanently disabled.
|
|
.TP
|
|
.BR \-V , " \-\-version"
|
|
Display version information and exit.
|
|
.TP
|
|
.BR \-h , " \-\-help"
|
|
Display help text and exit.
|
|
.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 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
|
|
.TQ
|
|
.B # touch /root/uts-ns
|
|
.TQ
|
|
.B # unshare --uts=/root/uts-ns hostanme FOO
|
|
.TQ
|
|
.B # nsenter --uts=/root/uts-ns hostname
|
|
.TQ
|
|
FOO
|
|
.TQ
|
|
.B # umount /root/uts-ns
|
|
.br
|
|
Establish a persistent UTS namespace, modify hostname. The namespace maybe later entered
|
|
by nsenter. The namespace is destroyed by umount the bind reference.
|
|
.SH SEE ALSO
|
|
.BR unshare (2),
|
|
.BR clone (2),
|
|
.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
|
|
ftp://ftp.kernel.org/pub/linux/utils/util-linux/.
|