416 lines
12 KiB
HTML
416 lines
12 KiB
HTML
|
|
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
|
|
<HTML><HEAD><TITLE>Man page of UNSHARE</TITLE>
|
|
</HEAD><BODY>
|
|
<H1>UNSHARE</H1>
|
|
Section: User Commands (1)<BR>Updated: February 2016<BR><A HREF="#index">Index</A>
|
|
<A HREF="/cgi-bin/man/man2html">Return to Main Contents</A><HR>
|
|
|
|
<A NAME="lbAB"> </A>
|
|
<H2>NAME</H2>
|
|
|
|
unshare - run program with some namespaces unshared from parent
|
|
<A NAME="lbAC"> </A>
|
|
<H2>SYNOPSIS</H2>
|
|
|
|
<B>unshare</B>
|
|
|
|
[options]
|
|
[<I>program</I>
|
|
|
|
[<I>arguments</I>]]
|
|
|
|
<A NAME="lbAD"> </A>
|
|
<H2>DESCRIPTION</H2>
|
|
|
|
Unshares the indicated namespaces from the parent process and then executes
|
|
the specified <I>program</I>. If <I>program</I> is not given, then ``${SHELL}'' is
|
|
run (default: /bin/sh).
|
|
<P>
|
|
|
|
The namespaces can optionally be made persistent by bind mounting
|
|
/proc/<I>pid</I>/ns/<I>type</I> files to a filesystem path and entered with
|
|
<B><A HREF="/cgi-bin/man/man2html?1+nsenter">nsenter</A></B>(1)
|
|
|
|
even after the <I>program</I> terminates (except PID namespaces where
|
|
permanently running init process is required).
|
|
Once a persistent namespace is no longer needed, it can be unpersisted with
|
|
<B><A HREF="/cgi-bin/man/man2html?8+umount">umount</A></B>(8).
|
|
|
|
See the <B>EXAMPLES</B> section for more details.
|
|
<P>
|
|
|
|
The namespaces to be unshared are indicated via options. Unshareable namespaces are:
|
|
<DL COMPACT>
|
|
<DT id="1"><B>mount namespace</B>
|
|
|
|
<DD>
|
|
Mounting and unmounting filesystems will not affect the rest of the system,
|
|
except for filesystems which are explicitly marked as
|
|
shared (with <B>mount --make-shared</B>; see <I>/proc/self/mountinfo</I> or
|
|
<B>findmnt -o+PROPAGATION</B> for the <B>shared</B> flags).
|
|
For further details, see
|
|
<B><A HREF="/cgi-bin/man/man2html?7+mount_namespaces">mount_namespaces</A></B>(7)
|
|
|
|
and the discussion of the
|
|
<B>CLONE_NEWNS</B>
|
|
|
|
flag in
|
|
<B><A HREF="/cgi-bin/man/man2html?2+clone">clone</A></B>(2).
|
|
|
|
<P>
|
|
<B>unshare</B>
|
|
|
|
since util-linux version 2.27 automatically sets propagation to <B>private</B>
|
|
in a new mount namespace to make sure that the new namespace is really
|
|
unshared. It's possible to disable this feature with option
|
|
<B>--propagation unchanged</B>.
|
|
Note that <B>private</B> is the kernel default.
|
|
<DT id="2"><B>UTS namespace</B>
|
|
|
|
<DD>
|
|
Setting hostname or domainname will not affect the rest of the system.
|
|
For further details, see
|
|
<B><A HREF="/cgi-bin/man/man2html?7+namespaces">namespaces</A></B>(7)
|
|
|
|
and the discussion of the
|
|
<B>CLONE_NEWUTS</B>
|
|
|
|
flag in
|
|
<B><A HREF="/cgi-bin/man/man2html?2+clone">clone</A></B>(2).
|
|
|
|
<DT id="3"><B>IPC namespace</B>
|
|
|
|
<DD>
|
|
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
|
|
<B><A HREF="/cgi-bin/man/man2html?7+namespaces">namespaces</A></B>(7)
|
|
|
|
and the discussion of the
|
|
<B>CLONE_NEWIPC</B>
|
|
|
|
flag in
|
|
<B><A HREF="/cgi-bin/man/man2html?2+clone">clone</A></B>(2).
|
|
|
|
<DT id="4"><B>network namespace</B>
|
|
|
|
<DD>
|
|
The process will have independent IPv4 and IPv6 stacks, IP routing tables,
|
|
firewall rules, the <I>/proc/net</I> and <I>/sys/class/net</I> directory trees,
|
|
sockets, etc.
|
|
For further details, see
|
|
<B><A HREF="/cgi-bin/man/man2html?7+namespaces">namespaces</A></B>(7)
|
|
|
|
and the discussion of the
|
|
<B>CLONE_NEWNET</B>
|
|
|
|
flag in
|
|
<B><A HREF="/cgi-bin/man/man2html?2+clone">clone</A></B>(2).
|
|
|
|
<DT id="5"><B>PID namespace</B>
|
|
|
|
<DD>
|
|
Children will have a distinct set of PID-to-process mappings from their parent.
|
|
For further details, see
|
|
<B><A HREF="/cgi-bin/man/man2html?7+pid_namespaces">pid_namespaces</A></B>(7)
|
|
|
|
and
|
|
the discussion of the
|
|
<B>CLONE_NEWPID</B>
|
|
|
|
flag in
|
|
<B><A HREF="/cgi-bin/man/man2html?2+clone">clone</A></B>(2).
|
|
|
|
<DT id="6"><B>cgroup namespace</B>
|
|
|
|
<DD>
|
|
The process will have a virtualized view of <I>/proc:/self:/cgroup</I>, and new
|
|
cgroup mounts will be rooted at the namespace cgroup root.
|
|
For further details, see
|
|
<B><A HREF="/cgi-bin/man/man2html?7+cgroup_namespaces">cgroup_namespaces</A></B>(7)
|
|
|
|
and the discussion of the
|
|
<B>CLONE_NEWCGROUP</B>
|
|
|
|
flag in
|
|
<B><A HREF="/cgi-bin/man/man2html?2+clone">clone</A></B>(2).
|
|
|
|
<DT id="7"><B>user namespace</B>
|
|
|
|
<DD>
|
|
The process will have a distinct set of UIDs, GIDs and capabilities.
|
|
For further details, see
|
|
<B><A HREF="/cgi-bin/man/man2html?7+user_namespaces">user_namespaces</A></B>(7)
|
|
|
|
and the discussion of the
|
|
<B>CLONE_NEWUSER</B>
|
|
|
|
flag in
|
|
<B><A HREF="/cgi-bin/man/man2html?2+clone">clone</A></B>(2).
|
|
|
|
</DL>
|
|
<A NAME="lbAE"> </A>
|
|
<H2>OPTIONS</H2>
|
|
|
|
<DL COMPACT>
|
|
<DT id="8"><B>-i</B>,<B> --ipc</B>[<B>=</B><I>file</I>]
|
|
|
|
<DD>
|
|
Unshare the IPC namespace. If <I>file</I> is specified, then a persistent
|
|
namespace is created by a bind mount.
|
|
<DT id="9"><B>-m</B>,<B> --mount</B>[<B>=</B><I>file</I>]
|
|
|
|
<DD>
|
|
Unshare the mount namespace. If <I>file</I> is specified, then a persistent
|
|
namespace is created by a bind mount.
|
|
Note that <I>file</I> has to be located on a filesystem with the propagation
|
|
flag set to <B>private</B>. Use the command <B>findmnt -o+PROPAGATION</B>
|
|
when not sure about the current setting. See also the examples below.
|
|
<DT id="10"><B>-n</B>,<B> --net</B>[<B>=</B><I>file</I>]
|
|
|
|
<DD>
|
|
Unshare the network namespace. If <I>file</I> is specified, then a persistent
|
|
namespace is created by a bind mount.
|
|
<DT id="11"><B>-p</B>,<B> --pid</B>[<B>=</B><I>file</I>]
|
|
|
|
<DD>
|
|
Unshare the PID namespace. If <I>file</I> is specified then persistent
|
|
namespace is created by a bind mount. See also the <B>--fork</B> and
|
|
<B>--mount-proc</B> options.
|
|
<DT id="12"><B>-u</B>,<B> --uts</B>[<B>=</B><I>file</I>]
|
|
|
|
<DD>
|
|
Unshare the UTS namespace. If <I>file</I> is specified, then a persistent
|
|
namespace is created by a bind mount.
|
|
<DT id="13"><B>-U</B>,<B> --user</B>[<B>=</B><I>file</I>]
|
|
|
|
<DD>
|
|
Unshare the user namespace. If <I>file</I> is specified, then a persistent
|
|
namespace is created by a bind mount.
|
|
<DT id="14"><B>-C</B>,<B> --cgroup[=</B><I>file</I>]
|
|
|
|
<DD>
|
|
Unshare the cgroup namespace. If <I>file</I> is specified then persistent namespace is created
|
|
by bind mount.
|
|
<DT id="15"><B>-f</B>,<B> --fork</B>
|
|
|
|
<DD>
|
|
Fork the specified <I>program</I> as a child process of <B>unshare</B> rather than
|
|
running it directly. This is useful when creating a new PID namespace.
|
|
<DT id="16"><B>--kill-child</B>[<B>=</B><I>signame</I>]
|
|
|
|
<DD>
|
|
When <B>unshare</B> terminates, have <I>signame</I> be sent to the forked child process.
|
|
Combined with <B>--pid</B> this allows for an easy and reliable killing of the entire
|
|
process tree below <B>unshare</B>.
|
|
If not given, <I>signame</I> defaults to <B>SIGKILL</B>.
|
|
This option implies <B>--fork</B>.
|
|
<DT id="17"><B>--mount-proc</B>[<B>=</B><I>mountpoint</I>]
|
|
|
|
<DD>
|
|
Just before running the program, mount the proc filesystem at <I>mountpoint</I>
|
|
(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).
|
|
<DT id="18"><B>-r</B>,<B> --map-root-user</B>
|
|
|
|
<DD>
|
|
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 <B>--setgroups=deny</B>.
|
|
<DT id="19"><B>--propagation private</B>|<B>shared</B>|<B>slave</B>|<B>unchanged</B>
|
|
|
|
<DD>
|
|
Recursively set the mount propagation flag in the new mount namespace. The default
|
|
is to set the propagation to <I>private</I>. It is possible to disable this feature
|
|
with the argument <B>unchanged</B>. The option is silently ignored when the mount
|
|
namespace (<B>--mount</B>) is not requested.
|
|
<DT id="20"><B>--setgroups allow</B>|<B>deny</B>
|
|
|
|
<DD>
|
|
Allow or deny the
|
|
<B><A HREF="/cgi-bin/man/man2html?2+setgroups">setgroups</A></B>(2)
|
|
|
|
system call in a user namespace.
|
|
<P>
|
|
To be able to call
|
|
<B><A HREF="/cgi-bin/man/man2html?2+setgroups">setgroups</A></B>(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
|
|
<B><A HREF="/cgi-bin/man/man2html?2+setgroups">setgroups</A></B>(2)
|
|
|
|
only after the GID map (<B>/proc/</B><I>pid</I><B>/gid_map</B>) has been set.
|
|
The GID map is writable by root when
|
|
<B><A HREF="/cgi-bin/man/man2html?2+setgroups">setgroups</A></B>(2)
|
|
|
|
is enabled (i.e. <B>allow</B>, the default), and
|
|
the GID map becomes writable by unprivileged processes when
|
|
<B><A HREF="/cgi-bin/man/man2html?2+setgroups">setgroups</A></B>(2)
|
|
|
|
is permanently disabled (with <B>deny</B>).
|
|
<DT id="21"><B>-R,</B>--root=<I>dir</I>
|
|
|
|
<DD>
|
|
run the command with root directory set to <I>dir</I>.
|
|
<DT id="22"><B>-w,</B>--wd=<I>dir</I>
|
|
|
|
<DD>
|
|
change working directory to <I>dir</I>.
|
|
<DT id="23"><B>-S,</B>--setuid <I>uid</I>
|
|
|
|
<DD>
|
|
Set the user ID which will be used in the entered namespace.
|
|
<DT id="24"><B>-G,</B>--setgid <I>gid</I>
|
|
|
|
<DD>
|
|
Set the group ID which will be used in the entered namespace and drop
|
|
supplementary groups.
|
|
<DT id="25"><B>-V</B>,<B> --version</B>
|
|
|
|
<DD>
|
|
Display version information and exit.
|
|
<DT id="26"><B>-h</B>,<B> --help</B>
|
|
|
|
<DD>
|
|
Display help text and exit.
|
|
</DL>
|
|
<A NAME="lbAF"> </A>
|
|
<H2>NOTES</H2>
|
|
|
|
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.
|
|
<A NAME="lbAG"> </A>
|
|
<H2>EXAMPLES</H2>
|
|
|
|
<DL COMPACT>
|
|
<DT id="27"><B># unshare --fork --pid --mount-proc readlink /proc/self</B>
|
|
|
|
<DD>
|
|
|
|
1
|
|
<BR>
|
|
|
|
Establish a PID namespace, ensure we're PID 1 in it against a newly mounted
|
|
procfs instance.
|
|
<DT id="28"><B>$ unshare --map-root-user --user sh -c whoami</B>
|
|
|
|
<DD>
|
|
|
|
root
|
|
<BR>
|
|
|
|
Establish a user namespace as an unprivileged user with a root user within it.
|
|
<DT id="29"><B># touch /root/uts-ns</B>
|
|
|
|
<DD>
|
|
|
|
<B># unshare --uts=/root/uts-ns hostname FOO</B>
|
|
|
|
|
|
<B># nsenter --uts=/root/uts-ns hostname</B>
|
|
|
|
|
|
FOO
|
|
|
|
<B># umount /root/uts-ns</B>
|
|
|
|
<BR>
|
|
|
|
Establish a persistent UTS namespace, and modify the hostname. The namespace
|
|
is then entered with <B>nsenter</B>. The namespace is destroyed by unmounting
|
|
the bind reference.
|
|
<DT id="30"><B># mount --bind /root/namespaces /root/namespaces</B>
|
|
|
|
<DD>
|
|
|
|
<B># mount --make-private /root/namespaces</B>
|
|
|
|
|
|
<B># touch /root/namespaces/mnt</B>
|
|
|
|
|
|
<B># unshare --mount=/root/namespaces/mnt</B>
|
|
|
|
<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.
|
|
<DT id="31"><B># unshare -pf --kill-child -- bash -c (sleep 999 &) && sleep 1000 &</B>
|
|
|
|
<DD>
|
|
|
|
<B># pid=$!</B>
|
|
|
|
|
|
<B># kill $pid</B>
|
|
|
|
<BR>
|
|
|
|
Reliable killing of subprocesses of the <I>program</I>.
|
|
When <B>unshare</B> gets killed, everything below it gets killed as well.
|
|
Without it, the children of <I>program</I> would have orphaned and
|
|
been re-parented to PID 1.
|
|
<P>
|
|
</DL>
|
|
<A NAME="lbAH"> </A>
|
|
<H2>SEE ALSO</H2>
|
|
|
|
<B><A HREF="/cgi-bin/man/man2html?2+clone">clone</A></B>(2),
|
|
|
|
<B><A HREF="/cgi-bin/man/man2html?2+unshare">unshare</A></B>(2),
|
|
|
|
<B><A HREF="/cgi-bin/man/man2html?7+namespaces">namespaces</A></B>(7),
|
|
|
|
<B><A HREF="/cgi-bin/man/man2html?8+mount">mount</A></B>(8)
|
|
|
|
<A NAME="lbAI"> </A>
|
|
<H2>AUTHORS</H2>
|
|
|
|
|
|
Mikhail Gusarov
|
|
|
|
<BR>
|
|
|
|
|
|
Karel Zak
|
|
|
|
<A NAME="lbAJ"> </A>
|
|
<H2>AVAILABILITY</H2>
|
|
|
|
The unshare command is part of the util-linux package and is available from
|
|
<A HREF="https://www.kernel.org/pub/linux/utils/util-linux/.">https://www.kernel.org/pub/linux/utils/util-linux/.</A>
|
|
<P>
|
|
|
|
<HR>
|
|
<A NAME="index"> </A><H2>Index</H2>
|
|
<DL>
|
|
<DT id="32"><A HREF="#lbAB">NAME</A><DD>
|
|
<DT id="33"><A HREF="#lbAC">SYNOPSIS</A><DD>
|
|
<DT id="34"><A HREF="#lbAD">DESCRIPTION</A><DD>
|
|
<DT id="35"><A HREF="#lbAE">OPTIONS</A><DD>
|
|
<DT id="36"><A HREF="#lbAF">NOTES</A><DD>
|
|
<DT id="37"><A HREF="#lbAG">EXAMPLES</A><DD>
|
|
<DT id="38"><A HREF="#lbAH">SEE ALSO</A><DD>
|
|
<DT id="39"><A HREF="#lbAI">AUTHORS</A><DD>
|
|
<DT id="40"><A HREF="#lbAJ">AVAILABILITY</A><DD>
|
|
</DL>
|
|
<HR>
|
|
This document was created by
|
|
<A HREF="/cgi-bin/man/man2html">man2html</A>,
|
|
using the manual pages.<BR>
|
|
Time: 00:05:29 GMT, March 31, 2021
|
|
</BODY>
|
|
</HTML>
|