Usage:
unshare [options] [<program> [<argument>...]]
Run a program with some namespaces unshared from the parent.
Options:
-m, --mount[=<file>] unshare mounts namespace
-u, --uts[=<file>] unshare UTS namespace (hostname etc)
-i, --ipc[=<file>] unshare System V IPC namespace
-n, --net[=<file>] unshare network namespace
-p, --pid[=<file>] unshare pid namespace
-U, --user[=<file>] unshare user namespace
-C, --cgroup[=<file>] unshare cgroup namespace
-T, --time[=<file>] unshare time namespace
--mount-proc[=<dir>] mount proc filesystem first (implies --mount)
--mount-binfmt[=<dir>] mount binfmt filesystem first (implies --user and --mount)
-l, --load-interp <file> load binfmt definition in the namespace (implies --mount-binfmt)
--propagation slave|shared|private|unchanged
modify mount propagation in mount namespace
-R, --root <dir> run the command with root directory set to <dir>
-w, --wd <dir> change working directory to <dir>
-S, --setuid <uid> set uid in entered namespace
-G, --setgid <gid> set gid in entered namespace
--map-user <uid>|<name> map current user to uid (implies --user)
--map-group <gid>|<name> map current group to gid (implies --user)
-r, --map-root-user map current user to root (implies --user)
-c, --map-current-user map current user to itself (implies --user)
--map-auto map users and groups automatically (implies --user)
--map-subids map the first block of user IDs owned by euid (implies --user)
--map-users <inneruid>:<outeruid>:<count>
map count users from outeruid to inneruid (implies --user)
--map-groups <innergid>:<outergid>:<count>
map count groups from outergid to innergid (implies --user)
--owner <uid>:<gid> set the user namespace owner (implies --user)
-f, --fork fork before launching <program>
--kill-child[=<signame>] when dying, kill the forked child (implies --fork)
defaults to SIGKILL
--forward-signals forward SIGTERM and SIGINT to child (implies --fork)
--setgroups allow|deny control the setgroups syscall in user namespaces
--keep-caps retain capabilities granted in user namespaces
--monotonic <offset> set clock monotonic offset (seconds) in time namespaces
--boottime <offset> set clock boottime offset (seconds) in time namespaces
-h, --help display this help
-V, --version display version
For more details see unshare(1).
Options (34)
| Option | Description | Source |
|---|---|---|
-m, --mount file | Create a new mount namespace. | help + man |
-u, --uts file | unshare UTS namespace (hostname etc) | help + man |
-i, --ipc file | unshare System V IPC namespace | help + man |
-n, --net file | Create a new network namespace. | help + man |
-p, --pid file | Create a new PID namespace. | help + man |
-U, --user file | Create a new user namespace. | help + man |
-C, --cgroup file | Create a new cgroup namespace. | help + man |
-T, --time file | Create a new time namespace. | help + man |
--mount-proc dir | Just before running the program, mount the proc filesystem at mountpoint (default is /proc). | help + man |
--mount-binfmt dir | Just before running the program, mount the binfmt_misc filesystem at mountpoint (default is /proc/sys/fs/binfmt_misc). | help + man |
-l, --load-interp file | Load binfmt_misc definition in the namespace (implies --mount-binfmt). | help + man |
--propagation slave|shared|private|unchanged | Recursively set the mount propagation flag in the new mount namespace. | help + man |
-R, --root dir | run the command with root directory set to <dir> | help + man |
-w, --wd dir | change working directory to <dir> | help + man |
-S, --setuid uid | Set the user ID which will be used in the entered namespace. | help + man |
-G, --setgid gid | Set the group ID which will be used in the entered namespace and drop supplementary groups. | help + man |
--map-user uid>|<name | Run the program only after the current effective user ID has been mapped to uid. | help + man |
--map-group gid>|<name | Run the program only after the current effective group ID has been mapped to gid. | help + man |
-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. | help + man |
-c, --map-current-user | 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. | help + man |
--map-auto | Map the first block of user IDs owned by the effective user from /etc/subuid to a block starting at user ID 0. | help + man |
--map-subids | Identity map the first block of user IDs owned by the effective user from /etc/subuid. | help + man |
--map-users inneruid>:<outeruid>:<count | 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. | help + man |
--map-groups innergid>:<outergid>:<count | 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. | help + man |
--owner uid>:<gid | Set the owner user and group when creating a user namespace. | help + man |
-f, --fork | Fork the specified program as a child process of unshare rather than running it directly. | help + man |
--kill-child signame | When unshare terminates, have signame be sent to the forked child process. | help + man |
--forward-signals | Forward SIGTERM and SIGINT signals received by the parent unshare process to the child process. | help + man |
--setgroups allow|deny | Allow or deny the setgroups(2) system call in a user namespace. | help + man |
--keep-caps | When the --user option is given, ensure that capabilities granted in the user namespace are preserved in the child process. | help + man |
--monotonic offset | Set the offset of CLOCK_MONOTONIC which will be used in the entered time namespace. | help + man |
--boottime offset | Set the offset of CLOCK_BOOTTIME which will be used in the entered time namespace. | help + man |
-h, --help | Display help text and exit. | help + man |
-V, --version | Display version and exit. | help + man |
Examples (12) from the manual page, untested
unshare --fork --pid --mount-proc readlink /proc/self
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.id -u; id -g
As an unprivileged user, create a new user namespace where the user’s credentials are mapped to the root IDs inside the namespace:unshare --user --map-root-user \
As an unprivileged user, create a new user namespace where the user’s credentials are mapped to the root IDs inside the namespace:id -u
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.cat /etc/subuid
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.unshare --user --map-auto --map-root-user
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.ls -ln --time-style=+ file
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.touch /root/uts-ns
The first of the following commands creates a new persistent UTS namespace and modifies the hostname as seen in that namespace.mount --bind /root/namespaces /root/namespaces
The following commands establish a persistent mount namespace referenced by the bind mount /root/namespaces/mnt.set +m # Don't print job status messages
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…unshare --pid --fork --mount-proc -- \
The pidof(1) command prints no output, because the sleep processes have been killed.uptime -p # Show uptime in initial time namespace
The following example demonstrates the creation of a time namespace where the boottime clock is set to a point several years in the past: