NAME
unshare - run program in new namespacesSYNOPSIS
unshare [options] [program [arguments]]DESCRIPTION
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).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).
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.
Setting hostname or domainname will not affect
the rest of the system. For further details, see
uts_namespaces(7).
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).
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).
Children will have a distinct set of
PID-to-process mappings from their parent. For further details, see
pid_namespaces(7).
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).
The process will have a distinct set of UIDs,
GIDs and capabilities. For further details, see
user_namespaces(7).
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).
OPTIONS
-i, --ipc[=file]Create a new IPC namespace. If file is
specified, then the namespace is made persistent by creating a bind mount at
file.
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.
Create a new network namespace. If file
is specified, then the namespace is made persistent by creating a bind mount
at file.
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.)
See also the --fork and --mount-proc options.
Create a new UTS namespace. If file is
specified, then the namespace is made persistent by creating a bind mount at
file.
Create a new user namespace. If file is
specified, then the namespace is made persistent by creating a bind mount at
file.
Create a new cgroup namespace. If file
is specified, then the namespace is made persistent by creating a bind mount
at file.
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.
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.
When the --user option is given, ensure
that capabilities granted in the user namespace are preserved in the child
process.
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.
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).
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.
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 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. 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. If this option is specified multiple times, the last occurrence
takes precedence. This option implies --user.
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.
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 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. 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. If this option is specified multiple times, the last occurrence
takes precedence. This option implies --user.
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.
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.
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).
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.
Allow or deny the setgroups(2) system
call in a user namespace.
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).
run the command with root directory set to
dir.
change working directory to dir.
Set the user ID which will be used in the
entered namespace.
Set the group ID which will be used in the
entered namespace and drop supplementary groups.
Set the offset of CLOCK_MONOTONIC which
will be used in the entered time namespace. This option requires unsharing a
time namespace with --time.
Set the offset of CLOCK_BOOTTIME which
will be used in the entered time namespace. This option requires unsharing a
time namespace with --time.
Display help text and exit.
Print version and exit.
NOTES
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.EXAMPLES
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.# unshare --fork --pid --mount-proc readlink /proc/self 1
$ id -u; id -g 1000 1000 $ unshare --user --map-root-user \ sh -c ''whoami; cat /proc/self/uid_map /proc/self/gid_map'' root 0 1000 1 0 1000 1
$ id -u 1000 $ cat /etc/subuid 1000:100000:65536 $ unshare --user --map-auto --map-root-user # id -u 0 # cat /proc/self/uid_map 0 1000 1 1 100000 65535 # touch file; chown 1:1 file # ls -ln --time-style=+ file -rw-r--r-- 1 1 1 0 file # exit $ ls -ln --time-style=+ file -rw-r--r-- 1 100000 100000 0 file
# touch /root/uts-ns # unshare --uts=/root/uts-ns hostname FOO # nsenter --uts=/root/uts-ns hostname FOO # umount /root/uts-ns
# mount --bind /root/namespaces /root/namespaces # mount --make-private /root/namespaces # touch /root/namespaces/mnt # unshare --mount=/root/namespaces/mnt
# set +m # Don't print job status messages # unshare --pid --fork --mount-proc --kill-child -- \ bash --norc -c ''(sleep 555 &) && (ps a &) && sleep 999'' & [1] 53456 # PID TTY STAT TIME COMMAND 1 pts/3 S+ 0:00 sleep 999 3 pts/3 S+ 0:00 sleep 555 5 pts/3 R+ 0:00 ps a # ps h -o 'comm' $! # Show that background job is unshare # kill $! # Kill # pidof sleep
# unshare --pid --fork --mount-proc -- \ bash --norc -c ''(sleep 555 &) && (ps a &) && sleep 999'' & [1] 53479 # PID TTY STAT TIME COMMAND 1 pts/3 S+ 0:00 sleep 999 3 pts/3 S+ 0:00 sleep 555 5 pts/3 R+ 0:00 ps a # kill $! # pidof sleep 53482 53480
# uptime -p # Show uptime in initial time namespace up 21 hours, 30 minutes # unshare --time --fork --boottime 300000000 uptime -p up 9 years, 28 weeks, 1 day, 2 hours, 50 minutes
AUTHORS
Mikhail <[email protected]>Gusarov Karel <[email protected]>ZakSEE ALSO
newuidmap(1) newgidmap(1) clone(2), unshare(2), namespaces(7), mount(8)REPORTING BUGS
For bug reports, use the issue tracker at <https://github.com/util-linux/util-linux/issues>.AVAILABILITY
The unshare command is part of the util-linux package which can be downloaded from Linux Kernel Archive <https://www.kernel.org/pub/linux/utils/util-linux/>.2022-05-11 | util-linux 2.38.1 |