sys-utils/unshare.1.adoc

   1 //po4a: entry man manual
   2 = unshare(1)
   3 :doctype: manpage
   4 :man manual: User Commands
   5 :man source: util-linux {release-version}
   6 :page-layout: base
   7 :command: unshare
   8
   9 == NAME
  10
  11 unshare - run program in new namespaces
  12
  13 == SYNOPSIS
  14
  15 *unshare* [options] [_program_ [_arguments_]]
  16
  17 == DESCRIPTION
  18
  19 The *unshare* command creates new namespaces (as specified by the command-line options described below) and then executes the specified _program_. If _program_ is not given, then "${SHELL}" is run (default: _/bin/sh_).
  20
  21 By default, a new namespace persists only as long as it has member processes. A new namespace can be made persistent even when it has no member processes by bind mounting /proc/_pid_/ns/_type_ files to a filesystem path. A namespace that has been made persistent in this way can subsequently be entered with *nsenter*(1) even after the _program_ terminates (except PID namespaces where a permanently running init process is required). Once a persistent namespace is no longer needed, it can be unpersisted by using *umount*(8) to remove the bind mount. See the *EXAMPLES* section for more details.
  22
  23 *unshare* since util-linux version 2.36 uses _/proc/[pid]/ns/pid_for_children_ and _/proc/[pid]/ns/time_for_children_ files for persistent PID and TIME namespaces. This change requires Linux kernel 4.17 or newer.
  24
  25 The following types of namespaces can be created with *unshare*:
  26
  27 *mount namespace*::
  28 Mounting and unmounting filesystems will not affect the rest of the system, except for filesystems which are explicitly marked as shared (with *mount --make-shared*; see _/proc/self/mountinfo_ or *findmnt -o+PROPAGATION* for the *shared* flags). For further details, see *mount_namespaces*(7).
  29 +
  30 *unshare* since util-linux version 2.27 automatically sets propagation to *private* in a new mount namespace to make sure that the new namespace is really unshared. It's possible to disable this feature with option *--propagation unchanged*. Note that *private* is the kernel default.
  31
  32 *UTS namespace*::
  33 Setting hostname or domainname will not affect the rest of the system. For further details, see *uts_namespaces*(7).
  34
  35 *IPC namespace*::
  36 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 *ipc_namespaces*(7).
  37
  38 *network namespace*::
  39 The process will have independent IPv4 and IPv6 stacks, IP routing tables, firewall rules, the _/proc/net_ and _/sys/class/net_ directory trees, sockets, etc. For further details, see *network_namespaces*(7).
  40
  41 *PID namespace*::
  42 Children will have a distinct set of PID-to-process mappings from their parent. For further details, see *pid_namespaces*(7).
  43
  44 *cgroup namespace*::
  45 The process will have a virtualized view of _/proc/self/cgroup_, and new cgroup mounts will be rooted at the namespace cgroup root. For further details, see *cgroup_namespaces*(7).
  46
  47 *user namespace*::
  48 The process will have a distinct set of UIDs, GIDs and capabilities. For further details, see *user_namespaces*(7).
  49
  50 *time namespace*::
  51 The process can have a distinct view of *CLOCK_MONOTONIC* and/or *CLOCK_BOOTTIME* which can be changed using _/proc/self/timens_offsets_. For further details, see *time_namespaces*(7).
  52
  53 == OPTIONS
  54
  55 *-i*, *--ipc*[**=**__file__]::
  56 Create a new IPC namespace. If _file_ is specified, then the namespace is made persistent by creating a bind mount at _file_.
  57
  58 *-m*, *--mount*[**=**__file__]::
  59 Create a new mount namespace. If _file_ is specified, then the namespace is made persistent by creating a bind mount at _file_. Note that _file_ must be located on a mount whose propagation type is not *shared* (or an error results). Use the command *findmnt -o+PROPAGATION* when not sure about the current setting. See also the examples below.
  60
  61 *-n*, *--net*[**=**__file__]::
  62 Create a new network namespace. If _file_ is specified, then the namespace is made persistent by creating a bind mount at _file_.
  63
  64 *-p*, *--pid*[**=**__file__]::
  65 Create a new PID namespace. If _file_ is specified, then the namespace is made persistent by creating a bind mount at _file_. (Creation of a persistent PID namespace will fail if the *--fork* option is not also specified.)
  66 +
  67 See also the *--fork* and *--mount-proc* options.
  68
  69 *-u*, *--uts*[**=**__file__]::
  70 Create a new UTS namespace. If _file_ is specified, then the namespace is made persistent by creating a bind mount at _file_.
  71
  72 *-U*, *--user*[**=**__file__]::
  73 Create a new user namespace. If _file_ is specified, then the namespace is made persistent by creating a bind mount at _file_.
  74
  75 *-C*, *--cgroup*[**=**__file__]::
  76 Create a new cgroup namespace. If _file_ is specified, then the namespace is made persistent by creating a bind mount at _file_.
  77
  78 *-T*, *--time*[**=**__file__]::
  79 Create a new time namespace. If _file_ is specified, then the namespace is made persistent by creating a bind mount at _file_. The *--monotonic* and *--boottime* options can be used to specify the corresponding offset in the time namespace.
  80
  81 *-f*, *--fork*::
  82 Fork the specified _program_ as a child process of *unshare* rather than running it directly. This is useful when creating a new PID namespace. Note that when *unshare* is waiting for the child process, then it ignores *SIGINT* and *SIGTERM* and does not forward any signals to the child. It is necessary to send signals to the child process.
  83
  84 *--keep-caps*::
  85 When the *--user* option is given, ensure that capabilities granted in the user namespace are preserved in the child process.
  86
  87 *--kill-child*[**=**__signame__]::
  88 When *unshare* terminates, have _signame_ be sent to the forked child process. Combined with *--pid* this allows for an easy and reliable killing of the entire process tree below *unshare*. If not given, _signame_ defaults to *SIGKILL*. This option implies *--fork*.
  89
  90 *--mount-proc*[**=**__mountpoint__]::
  91 Just before running the program, mount the proc filesystem at _mountpoint_ (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*).
  92
  93 **--map-user=**__uid|name__::
  94 Run the program only after the current effective user ID has been mapped to _uid_. If this option is specified multiple times, the last occurrence takes precedence. This option implies *--user*.
  95
  96 **--map-users=**__inneruid:outeruid:count__|**auto**|**all**::
  97 Run the program only after the block of user IDs of size _count_ beginning at _outeruid_ has been mapped to the block of user IDs beginning at _inneruid_. This mapping is created with **newuidmap**(1) if *unshare* was run unprivileged. If the range of user IDs overlaps with the mapping specified by *--map-user*, then a "hole" will be removed from the mapping. This may result in the highest user ID of the mapping not being mapped. Use *--map-users* multiple times to map more than one block of user IDs. The special value *auto* will map the first block of user IDs owned by the effective user from _/etc/subuid_ to a block starting at user ID 0. The special value *all* will create a pass-through map for every user ID available in the parent namespace. This option implies *--user*.
  98 +
  99 Before util-linux version 2.39, this option expected a comma-separated argument of the form _outeruid,inneruid,count_ but that format is now deprecated for consistency with the ordering used in _/proc/[pid]/uid_map_ and the _X-mount.idmap_ mount option.
 100
 101 **--map-group=**__gid|name__::
 102 Run the program only after the current effective group ID has been mapped to _gid_. If this option is specified multiple times, the last occurrence takes precedence. This option implies *--setgroups=deny* and *--user*.
 103
 104 **--map-groups=**__innergid:outergid:count__|**auto**|**all**::
 105 Run the program only after the block of group IDs of size _count_ beginning at _outergid_ has been mapped to the block of group IDs beginning at _innergid_. This mapping is created with **newgidmap**(1) if *unshare* was run unprivileged. If the range of group IDs overlaps with the mapping specified by *--map-group*, then a "hole" will be removed from the mapping. This may result in the highest group ID of the mapping not being mapped. Use *--map-groups* multiple times to map more than one block of group IDs. The special value *auto* will map the first block of user IDs owned by the effective user from _/etc/subgid_ to a block starting at group ID 0. The special value *all* will create a pass-through map for every group ID available in the parent namespace. This option implies *--user*.
 106 +
 107 Before util-linux version 2.39, this option expected a comma-separated argument of the form _outergid,innergid,count_ but that format is now deprecated for consistency with the ordering used in _/proc/[pid]/gid_map_ and the _X-mount.idmap_ mount option.
 108
 109 **--map-auto**::
 110 Map the first block of user IDs owned by the effective user from _/etc/subuid_ to a block starting at user ID 0. In the same manner, also map the first block of group IDs owned by the effective group from _/etc/subgid_ to a block starting at group ID 0. This option is intended to handle the common case where the first block of subordinate user and group IDs can map the whole user and group ID space. This option is equivalent to specifying *--map-users=auto* and *--map-groups=auto*.
 111
 112 *-r*, *--map-root-user*::
 113 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* and *--user*. This option is equivalent to *--map-user=0 --map-group=0*.
 114
 115 *-c*, *--map-current-user*::
 116 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 *--setgroups=deny* and *--user*. This option is equivalent to *--map-user=$(id -ru) --map-group=$(id -rg)*.
 117
 118 **--propagation private**|**shared**|**slave**|*unchanged*::
 119 Recursively set the mount propagation flag in the new mount namespace. The default is to set the propagation to _private_. It is possible to disable this feature with the argument *unchanged*. The option is silently ignored when the mount namespace (*--mount*) is not requested.
 120
 121 **--setgroups allow**|*deny*::
 122 Allow or deny the *setgroups*(2) system call in a user namespace.
 123 +
 124 To be able to call *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 *setgroups*(2) only after the GID map (**/proc/**__pid__*/gid_map*) has been set. The GID map is writable by root when *setgroups*(2) is enabled (i.e., *allow*, the default), and the GID map becomes writable by unprivileged processes when *setgroups*(2) is permanently disabled (with *deny*).
 125
 126 *-R*, **--root=**__dir__::
 127 run the command with root directory set to _dir_.
 128
 129 *-w*, **--wd=**__dir__::
 130 change working directory to _dir_.
 131
 132 *-S*, *--setuid* _uid_::
 133 Set the user ID which will be used in the entered namespace.
 134
 135 *-G*, *--setgid* _gid_::
 136 Set the group ID which will be used in the entered namespace and drop supplementary groups.
 137
 138 *--monotonic* _offset_::
 139 Set the offset of *CLOCK_MONOTONIC* which will be used in the entered time namespace. This option requires unsharing a time namespace with *--time*.
 140
 141 *--boottime* _offset_::
 142 Set the offset of *CLOCK_BOOTTIME* which will be used in the entered time namespace. This option requires unsharing a time namespace with *--time*.
 143
 144 include::man-common/help-version.adoc[]
 145
 146 == NOTES
 147
 148 The proc and sysfs filesystems mounting as root in a user namespace have to be restricted so that a less privileged user cannot 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.
 149
 150 == EXAMPLES
 151
 152 The following command creates a PID namespace, using *--fork* to ensure that the executed command is performed in a child process that (being the first process in the namespace) has PID 1. The *--mount-proc* option ensures that a new mount namespace is also simultaneously created and that a new *proc*(5) filesystem is mounted that contains information corresponding to the new PID namespace. When the *readlink*(1) command terminates, the new namespaces are automatically torn down.
 153
 154 ....
 155 # unshare --fork --pid --mount-proc readlink /proc/self
 156 1
 157 ....
 158
 159 As an unprivileged user, create a new user namespace where the user's credentials are mapped to the root IDs inside the namespace:
 160
 161 ....
 162 $ id -u; id -g
 163 1000
 164 1000
 165 $ unshare --user --map-root-user \
 166         sh -c 'whoami; cat /proc/self/uid_map /proc/self/gid_map'
 167 root
 168          0       1000          1
 169          0       1000          1
 170 ....
 171
 172 As an unprivileged user, create a user namespace where the first 65536 IDs are all mapped, and the user's credentials are mapped to the root IDs inside the namespace. The map is determined by the subordinate IDs assigned in *subuid*(5) and *subgid*(5). Demonstrate this mapping by creating a file with user ID 1 and group ID 1. For brevity, only the user ID mappings are shown:
 173
 174 ....
 175 $ id -u
 176 1000
 177 $ cat /etc/subuid
 178 1000:100000:65536
 179 $ unshare --user --map-auto --map-root-user
 180 # id -u
 181 0
 182 # cat /proc/self/uid_map
 183          0       1000          1
 184          1     100000      65535
 185 # touch file; chown 1:1 file
 186 # ls -ln --time-style=+ file
 187 -rw-r--r-- 1 1 1 0  file
 188 # exit
 189 $ ls -ln --time-style=+ file
 190 -rw-r--r-- 1 100000 100000 0  file
 191 ....
 192
 193 The first of the following commands creates a new persistent UTS namespace and modifies the hostname as seen in that namespace. The namespace is then entered with *nsenter*(1) in order to display the modified hostname; this step demonstrates that the UTS namespace continues to exist even though the namespace had no member processes after the *unshare* command terminated. The namespace is then destroyed by removing the bind mount.
 194
 195 ....
 196 # touch /root/uts-ns
 197 # unshare --uts=/root/uts-ns hostname FOO
 198 # nsenter --uts=/root/uts-ns hostname
 199 FOO
 200 # umount /root/uts-ns
 201 ....
 202
 203 The following commands establish a persistent mount namespace referenced by the bind mount _/root/namespaces/mnt_. In order to ensure that the creation of that bind mount succeeds, the parent directory (_/root/namespaces_) is made a bind mount whose propagation type is not *shared*.
 204
 205 ....
 206 # mount --bind /root/namespaces /root/namespaces
 207 # mount --make-private /root/namespaces
 208 # touch /root/namespaces/mnt
 209 # unshare --mount=/root/namespaces/mnt
 210 ....
 211
 212 The following commands demonstrate the use of the *--kill-child* option when creating a PID namespace, in order to ensure that when *unshare* is killed, all of the processes within the PID namespace are killed.
 213
 214 ....
 215 # set +m                # Don't print job status messages
 216
 217 # unshare --pid --fork --mount-proc --kill-child -- \
 218        bash --norc -c '(sleep 555 &) && (ps a &) && sleep 999' &
 219 [1] 53456
 220 #     PID TTY      STAT   TIME COMMAND
 221       1 pts/3    S+     0:00 sleep 999
 222       3 pts/3    S+     0:00 sleep 555
 223       5 pts/3    R+     0:00 ps a
 224
 225 # ps h -o 'comm' $!     # Show that background job is unshare(1)
 226 unshare
 227 # kill $!               # Kill unshare(1)
 228 # pidof sleep
 229 ....
 230
 231 The *pidof*(1) command prints no output, because the *sleep* processes have been killed. More precisely, when the *sleep* process that has PID 1 in the namespace (i.e., the namespace's init process) was killed, this caused all other processes in the namespace to be killed. By contrast, a similar series of commands where the *--kill-child* option is not used shows that when *unshare* terminates, the processes in the PID namespace are not killed:
 232
 233 ....
 234 # unshare --pid --fork --mount-proc -- \
 235        bash --norc -c '(sleep 555 &) && (ps a &) && sleep 999' &
 236 [1] 53479
 237 #     PID TTY      STAT   TIME COMMAND
 238       1 pts/3    S+     0:00 sleep 999
 239       3 pts/3    S+     0:00 sleep 555
 240       5 pts/3    R+     0:00 ps a
 241
 242 # kill $!
 243 # pidof sleep
 244 53482 53480
 245 ....
 246
 247 The following example demonstrates the creation of a time namespace where the boottime clock is set to a point several years in the past:
 248
 249 ....
 250 # uptime -p             # Show uptime in initial time namespace
 251 up 21 hours, 30 minutes
 252 # unshare --time --fork --boottime 300000000 uptime -p
 253 up 9 years, 28 weeks, 1 day, 2 hours, 50 minutes
 254 ....
 255
 256 == AUTHORS
 257
 258 mailto:dottedmag@dottedmag.net[Mikhail Gusarov],
 259 mailto:kzak@redhat.com[Karel Zak]
 260
 261 == SEE ALSO
 262
 263 *newuidmap*(1),
 264 *newgidmap*(1),
 265 *clone*(2),
 266 *unshare*(2),
 267 *namespaces*(7),
 268 *mount*(8)
 269
 270 include::man-common/bugreports.adoc[]
 271
 272 include::man-common/footer.adoc[]
 273
 274 ifdef::translation[]
 275 include::man-common/translation.adoc[]
 276 endif::[]