1UNSHARE(1)                       User Commands                      UNSHARE(1)
2
3
4

NAME

6       unshare - run program with some namespaces unshared from parent
7

SYNOPSIS

9       unshare [options] [program [arguments]]
10

DESCRIPTION

12       Unshares the indicated namespaces from the parent process and then exe‐
13       cutes the specified program. If program is not given, then ``${SHELL}''
14       is run (default: /bin/sh).
15
16       The  namespaces  can  optionally  be  made  persistent by bind mounting
17       /proc/pid/ns/type  files  to  a  filesystem  path  and   entered   with
18       nsenter(1)  even  after  the  program terminates (except PID namespaces
19       where permanently running init process is required).  Once a persistent
20       namespace  is  no  longer needed, it can be unpersisted with umount(8).
21       See the EXAMPLES section for more details.
22
23       The namespaces to be unshared are indicated via  options.   Unshareable
24       namespaces are:
25
26       mount namespace
27              Mounting  and unmounting filesystems will not affect the rest of
28              the system, except for filesystems which are  explicitly  marked
29              as shared (with mount --make-shared; see /proc/self/mountinfo or
30              findmnt -o+PROPAGATION  for  the  shared  flags).   For  further
31              details,  see  mount_namespaces(7)  and  the  discussion  of the
32              CLONE_NEWNS flag in clone(2).
33
34              unshare since util-linux version 2.27 automatically sets  propa‐
35              gation to private in a new mount namespace to make sure that the
36              new namespace is really unshared.  It's possible to disable this
37              feature  with option --propagation unchanged.  Note that private
38              is the kernel default.
39
40       UTS namespace
41              Setting hostname or domainname will not affect the rest  of  the
42              system.   For further details, see namespaces(7) and the discus‐
43              sion of the CLONE_NEWUTS flag in clone(2).
44
45       IPC namespace
46              The process will have an independent namespace for POSIX message
47              queues  as  well  as System V message queues, semaphore sets and
48              shared memory segments.  For further details, see  namespaces(7)
49              and the discussion of the CLONE_NEWIPC flag in clone(2).
50
51       network namespace
52              The process will have independent IPv4 and IPv6 stacks, IP rout‐
53              ing tables, firewall rules,  the  /proc/net  and  /sys/class/net
54              directory  trees, sockets, etc.  For further details, see names‐
55              paces(7)  and  the  discussion  of  the  CLONE_NEWNET  flag   in
56              clone(2).
57
58       PID namespace
59              Children  will  have  a  distinct set of PID-to-process mappings
60              from their parent.  For further details,  see  pid_namespaces(7)
61              and the discussion of the CLONE_NEWPID flag in clone(2).
62
63       cgroup namespace
64              The  process  will have a virtualized view of /proc/self/cgroup,
65              and new cgroup mounts will be rooted  at  the  namespace  cgroup
66              root.   For  further  details,  see cgroup_namespaces(7) and the
67              discussion of the CLONE_NEWCGROUP flag in clone(2).
68
69       user namespace
70              The process will have a distinct set of UIDs, GIDs and capabili‐
71              ties.   For further details, see user_namespaces(7) and the dis‐
72              cussion of the CLONE_NEWUSER flag in clone(2).
73

OPTIONS

75       -i, --ipc[=file]
76              Unshare the IPC namespace.  If file is specified, then a persis‐
77              tent namespace is created by a bind mount.
78
79       -m, --mount[=file]
80              Unshare  the mount namespace.  If file is specified, then a per‐
81              sistent namespace is created by a bind mount.   Note  that  file
82              has  to be located on a filesystem with the propagation flag set
83              to private.  Use the command  findmnt  -o+PROPAGATION  when  not
84              sure about the current setting.  See also the examples below.
85
86       -n, --net[=file]
87              Unshare  the  network  namespace.   If file is specified, then a
88              persistent namespace is created by a bind mount.
89
90       -p, --pid[=file]
91              Unshare the PID namespace.  If file is specified then persistent
92              namespace  is  created by a bind mount.  See also the --fork and
93              --mount-proc options.
94
95       -u, --uts[=file]
96              Unshare the UTS namespace.  If file is specified, then a persis‐
97              tent namespace is created by a bind mount.
98
99       -U, --user[=file]
100              Unshare  the  user namespace.  If file is specified, then a per‐
101              sistent namespace is created by a bind mount.
102
103       -C, --cgroup[=file]
104              Unshare the cgroup namespace. If file is specified then  persis‐
105              tent namespace is created by bind mount.
106
107       -f, --fork
108              Fork  the specified program as a child process of unshare rather
109              than running it directly.  This is useful when  creating  a  new
110              PID namespace.
111
112       --kill-child[=signame]
113              When  unshare  terminates,  have  signame  be sent to the forked
114              child process.  Combined with --pid this allows for an easy  and
115              reliable  killing  of the entire process tree below unshare.  If
116              not given, signame defaults to  SIGKILL.   This  option  implies
117              --fork.
118
119       --mount-proc[=mountpoint]
120              Just  before  running  the program, mount the proc filesystem at
121              mountpoint (default is /proc).  This is useful when  creating  a
122              new  PID namespace.  It also implies creating a new mount names‐
123              pace since the /proc mount would otherwise mess up existing pro‐
124              grams  on  the  system.   The  new proc filesystem is explicitly
125              mounted as private (with MS_PRIVATE|MS_REC).
126
127       -r, --map-root-user
128              Run the program only after the current effective user and  group
129              IDs  have  been mapped to the superuser UID and GID in the newly
130              created user namespace.  This makes it possible to  conveniently
131              gain  capabilities needed to manage various aspects of the newly
132              created namespaces (such as configuring interfaces in  the  net‐
133              work  namespace  or mounting filesystems in the mount namespace)
134              even when run unprivileged.  As a mere convenience  feature,  it
135              does  not  support more sophisticated use cases, such as mapping
136              multiple ranges of UIDs and GIDs.  This  option  implies  --set‐
137              groups=deny.
138
139       --propagation private|shared|slave|unchanged
140              Recursively  set  the  mount  propagation  flag in the new mount
141              namespace.  The default is to set the  propagation  to  private.
142              It  is  possible  to  disable  this  feature  with  the argument
143              unchanged.  The option is silently ignored when the mount names‐
144              pace (--mount) is not requested.
145
146       --setgroups allow|deny
147              Allow or deny the setgroups(2) system call in a user namespace.
148
149              To  be  able  to  call setgroups(2), the calling process must at
150              least have CAP_SETGID.  But since Linux 3.19 a further  restric‐
151              tion  applies:  the kernel gives permission to call setgroups(2)
152              only after the GID map (/proc/pid/gid_map) has  been  set.   The
153              GID  map  is writable by root when setgroups(2) is enabled (i.e.
154              allow, the default), and the GID map becomes writable by unpriv‐
155              ileged processes when setgroups(2) is permanently disabled (with
156              deny).
157
158       -V, --version
159              Display version information and exit.
160
161       -h, --help
162              Display help text and exit.
163

NOTES

165       The proc and sysfs filesystems mounting as root  in  a  user  namespace
166       have  to  be restricted so that a less privileged user can not get more
167       access to sensitive files that a more privileged user made unavailable.
168       In  short  the  rule  for proc and sysfs is as close to a bind mount as
169       possible.
170

EXAMPLES

172       # unshare --fork --pid --mount-proc readlink /proc/self
173       1
174              Establish a PID namespace, ensure we're PID 1 in  it  against  a
175              newly mounted procfs instance.
176
177       $ unshare --map-root-user --user sh -c whoami
178       root
179              Establish  a  user namespace as an unprivileged user with a root
180              user within it.
181
182       # touch /root/uts-ns
183       # unshare --uts=/root/uts-ns hostname FOO
184       # nsenter --uts=/root/uts-ns hostname
185       FOO
186       # umount /root/uts-ns
187              Establish a persistent UTS namespace, and modify  the  hostname.
188              The  namespace  is  then entered with nsenter.  The namespace is
189              destroyed by unmounting the bind reference.
190
191       # mount --bind /root/namespaces /root/namespaces
192       # mount --make-private /root/namespaces
193       # touch /root/namespaces/mnt
194       # unshare --mount=/root/namespaces/mnt
195              Establish a persistent mount namespace referenced  by  the  bind
196              mount /root/namespaces/mnt.  This example shows a portable solu‐
197              tion, because it makes sure that the bind mount is created on  a
198              shared filesystem.
199
200       # unshare -pf --kill-child -- bash -c (sleep 999 &) && sleep 1000 &
201       # pid=$!
202       # kill $pid
203              Reliable  killing  of subprocesses of the program.  When unshare
204              gets killed, everything below it gets killed as  well.   Without
205              it, the children of program would have orphaned and been re-par‐
206              ented to PID 1.
207
208

SEE ALSO

210       clone(2), unshare(2), namespaces(7), mount(8)
211

AUTHORS

213       Mikhail Gusarov ⟨dottedmag@dottedmag.net⟩
214       Karel Zak ⟨kzak@redhat.com⟩
215

AVAILABILITY

217       The unshare command is part of the util-linux package and is  available
218       from https://www.kernel.org/pub/linux/utils/util-linux/.
219
220
221
222util-linux                       February 2016                      UNSHARE(1)
Impressum