{ "content": [ { "type": "text", "text": "# UNSHARE(1) (man)\n\n**Summary:** unshare - run program in new namespaces\n\n**Synopsis:** unshare [options] [program [arguments]]\n\n## Flags\n\n| Flag | Long | Arg | Description |\n|------|------|-----|-------------|\n| -i | --ipc | — | Unshare the IPC namespace. If file is specified, then a persistent namespace is created by a bind mount. |\n| -m | --mount | — | Unshare the mount namespace. If file is specified, then a persistent namespace is created by a bind mount. Note that fil |\n| -n | --net | — | Unshare the network namespace. If file is specified, then a persistent namespace is created by a bind mount. |\n| -p | --pid | — | Unshare the PID namespace. If file is specified, then a persistent namespace is created by a bind mount. (Creation of a |\n| -u | --uts | — | Unshare the UTS namespace. If file is specified, then a persistent namespace is created by a bind mount. |\n| -U | --user | — | Unshare the user namespace. If file is specified, then a persistent namespace is created by a bind mount. |\n| -C | --cgroup | — | Unshare the cgroup namespace. If file is specified, then persistent namespace is created by bind mount. |\n| -T | --time | — | Unshare the time namespace. If file is specified, then a persistent namespace is created by a bind mount. The --monotoni |\n| -f | --fork | — | Fork the specified program as a child process of unshare rather than running it directly. This is useful when creating a |\n| — | --keep-caps | — | When the --user option is given, ensure that capabilities granted in the user namespace are preserved in the child proce |\n| -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 |\n| -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 newl |\n| -R | — | — | run the command with root directory set to dir. |\n| -w | — | — | change working directory to dir. |\n| -S | --setuid | — | Set the user ID which will be used in the entered namespace. |\n| -G | --setgid | — | Set the group ID which will be used in the entered namespace and drop supplementary groups. --monotonic offset Set the o |\n| -V | --version | — | Display version information and exit. |\n| -h | --help | — | Display help text and exit. |\n\n## Examples\n\n- `The following command creates a PID namespace, using --fork to ensure that the executed`\n- `command is performed in a child process that (being the first process in the namespace) has`\n- `PID 1. The --mount-proc option ensures that a new mount namespace is also simultaneously`\n- `created and that a new proc(5) filesystem is mounted that contains information corresponding`\n- `to the new PID namespace. When the readlink command terminates, the new namespaces are`\n- `automatically torn down.`\n- `# unshare --fork --pid --mount-proc readlink /proc/self`\n- `As an unprivileged user, create a new user namespace where the user’s credentials are mapped`\n- `to the root IDs inside the namespace:`\n- `$ id -u; id -g`\n- `1000`\n- `1000`\n- `$ unshare --user --map-root-user \\`\n- `sh -c ''whoami; cat /proc/self/uidmap /proc/self/gidmap''`\n- `root`\n- `0 1000 1`\n- `0 1000 1`\n- `The first of the following commands creates a new persistent UTS namespace and modifies the`\n- `hostname as seen in that namespace. The namespace is then entered with nsenter(1) in order to`\n- `display the modified hostname; this step demonstrates that the UTS namespace continues to`\n- `exist even though the namespace had no member processes after the unshare command terminated.`\n- `The namespace is then destroyed by removing the bind mount.`\n- `# touch /root/uts-ns`\n- `# unshare --uts=/root/uts-ns hostname FOO`\n- `# nsenter --uts=/root/uts-ns hostname`\n- `FOO`\n- `# umount /root/uts-ns`\n- `The following commands establish a persistent mount namespace referenced by the bind mount`\n- `/root/namespaces/mnt. In order to ensure that the creation of that bind mount succeeds, the`\n- `parent directory (/root/namespaces) is made a bind mount whose propagation type is not`\n- `shared.`\n- `# mount --bind /root/namespaces /root/namespaces`\n- `# mount --make-private /root/namespaces`\n- `# touch /root/namespaces/mnt`\n- `# unshare --mount=/root/namespaces/mnt`\n- `The following commands demonstrate the use of the --kill-child option when creating a PID`\n- `namespace, in order to ensure that when unshare is killed, all of the processes within the`\n- `PID namespace are killed.`\n- `# set +m # Don't print job status messages`\n- `# unshare --pid --fork --mount-proc --kill-child -- \\`\n- `bash --norc -c ''(sleep 555 &) && (ps a &) && sleep 999'' &`\n- `[1] 53456`\n- `# PID TTY STAT TIME COMMAND`\n- `1 pts/3 S+ 0:00 sleep 999`\n- `3 pts/3 S+ 0:00 sleep 555`\n- `5 pts/3 R+ 0:00 ps a`\n- `# ps h -o 'comm' $! # Show that background job is unshare(1)`\n- `unshare`\n- `# kill $! # Kill unshare(1)`\n- `# pidof sleep`\n- `The pidof(1) command prints no output, because the sleep processes have been killed. More`\n- `precisely, when the sleep process that has PID 1 in the namespace (i.e., the namespace’s init`\n- `process) was killed, this caused all other processes in the namespace to be killed. By`\n- `contrast, a similar series of commands where the --kill-child option is not used shows that`\n- `when unshare terminates, the processes in the PID namespace are not killed:`\n- `# unshare --pid --fork --mount-proc -- \\`\n- `bash --norc -c ''(sleep 555 &) && (ps a &) && sleep 999'' &`\n- `[1] 53479`\n- `# PID TTY STAT TIME COMMAND`\n- `1 pts/3 S+ 0:00 sleep 999`\n- `3 pts/3 S+ 0:00 sleep 555`\n- `5 pts/3 R+ 0:00 ps a`\n- `# kill $!`\n- `# pidof sleep`\n- `53482 53480`\n- `The following example demonstrates the creation of a time namespace where the boottime clock`\n- `is set to a point several years in the past:`\n- `# uptime -p # Show uptime in initial time namespace`\n- `up 21 hours, 30 minutes`\n- `# unshare --time --fork --boottime 300000000 uptime -p`\n- `up 9 years, 28 weeks, 1 day, 2 hours, 50 minutes`\n\n## See Also\n\n- clone(2)\n- unshare(2)\n- namespaces(7)\n- mount(8)\n\n## Section Outline\n\n- **NAME** (2 lines)\n- **SYNOPSIS** (2 lines)\n- **DESCRIPTION** (18 lines) — 8 subsections\n - mount namespace (10 lines)\n - UTS namespace (3 lines)\n - IPC namespace (4 lines)\n - network namespace (4 lines)\n - PID namespace (3 lines)\n - cgroup namespace (3 lines)\n - user namespace (3 lines)\n - time namespace (3 lines)\n- **OPTIONS** (1 lines) — 18 subsections\n - -i --ipc (3 lines)\n - -m --mount (5 lines)\n - -n --net (3 lines)\n - -p --pid (6 lines)\n - -u --uts (3 lines)\n - -U --user (3 lines)\n - -C --cgroup (3 lines)\n - -T --time (4 lines)\n - -f --fork (5 lines)\n - --keep-caps (25 lines)\n - -r --map-root-user (9 lines)\n - -c --map-current-user (21 lines)\n - -R --root= (2 lines)\n - -w --wd= (2 lines)\n - -S --setuid (2 lines)\n - -G --setgid (11 lines)\n - -V --version (2 lines)\n - -h --help (2 lines)\n- **NOTES** (5 lines)\n- **EXAMPLES** (94 lines)\n- **AUTHORS** (2 lines)\n- **SEE ALSO** (2 lines)\n- **REPORTING BUGS** (2 lines)\n- **AVAILABILITY** (6 lines)\n\n## Full Content\n\n### NAME\n\nunshare - run program in new namespaces\n\n### SYNOPSIS\n\nunshare [options] [program [arguments]]\n\n### DESCRIPTION\n\nThe unshare command creates new namespaces (as specified by the command-line options\ndescribed below) and then executes the specified program. If program is not given, then\n\"${SHELL}\" is run (default: /bin/sh).\n\nBy default, a new namespace persists only as long as it has member processes. A new namespace\ncan be made persistent even when it has no member processes by bind mounting\n/proc/pid/ns/type files to a filesystem path. A namespace that has been made persistent in\nthis way can subsequently be entered with nsenter(1) even after the program terminates\n(except PID namespaces where a permanently running init process is required). Once a\npersistent namespace is no longer needed, it can be unpersisted by using umount(8) to remove\nthe bind mount. See the EXAMPLES section for more details.\n\nunshare since util-linux version 2.36 uses /proc/[pid]/ns/pidforchildren and\n/proc/[pid]/ns/timeforchildren files for persistent PID and TIME namespaces. This change\nrequires Linux kernel 4.17 or newer.\n\nThe following types of namespaces can be created with unshare:\n\n#### mount namespace\n\nMounting and unmounting filesystems will not affect the rest of the system, except for\nfilesystems which are explicitly marked as shared (with mount --make-shared; see\n/proc/self/mountinfo or findmnt -o+PROPAGATION for the shared flags). For further\ndetails, see mountnamespaces(7).\n\nunshare since util-linux version 2.27 automatically sets propagation to private in a new\nmount namespace to make sure that the new namespace is really unshared. It’s possible to\ndisable this feature with option --propagation unchanged. Note that private is the kernel\ndefault.\n\n#### UTS namespace\n\nSetting hostname or domainname will not affect the rest of the system. For further\ndetails, see utsnamespaces(7).\n\n#### IPC namespace\n\nThe process will have an independent namespace for POSIX message queues as well as System\nV message queues, semaphore sets and shared memory segments. For further details, see\nipcnamespaces(7).\n\n#### network namespace\n\nThe process will have independent IPv4 and IPv6 stacks, IP routing tables, firewall\nrules, the /proc/net and /sys/class/net directory trees, sockets, etc. For further\ndetails, see networknamespaces(7).\n\n#### PID namespace\n\nChildren will have a distinct set of PID-to-process mappings from their parent. For\nfurther details, see pidnamespaces(7).\n\n#### cgroup namespace\n\nThe process will have a virtualized view of /proc/self/cgroup, and new cgroup mounts will\nbe rooted at the namespace cgroup root. For further details, see cgroupnamespaces(7).\n\n#### user namespace\n\nThe process will have a distinct set of UIDs, GIDs and capabilities. For further details,\nsee usernamespaces(7).\n\n#### time namespace\n\nThe process can have a distinct view of CLOCKMONOTONIC and/or CLOCKBOOTTIME which can\nbe changed using /proc/self/timensoffsets. For further details, see timenamespaces(7).\n\n### OPTIONS\n\n#### -i --ipc\n\nUnshare the IPC namespace. If file is specified, then a persistent namespace is created\nby a bind mount.\n\n#### -m --mount\n\nUnshare the mount namespace. If file is specified, then a persistent namespace is created\nby a bind mount. Note that file must be located on a mount whose propagation type is not\nshared (or an error results). Use the command findmnt -o+PROPAGATION when not sure about\nthe current setting. See also the examples below.\n\n#### -n --net\n\nUnshare the network namespace. If file is specified, then a persistent namespace is\ncreated by a bind mount.\n\n#### -p --pid\n\nUnshare the PID namespace. If file is specified, then a persistent namespace is created\nby a bind mount. (Creation of a persistent PID namespace will fail if the --fork option\nis not also specified.)\n\nSee also the --fork and --mount-proc options.\n\n#### -u --uts\n\nUnshare the UTS namespace. If file is specified, then a persistent namespace is created\nby a bind mount.\n\n#### -U --user\n\nUnshare the user namespace. If file is specified, then a persistent namespace is created\nby a bind mount.\n\n#### -C --cgroup\n\nUnshare the cgroup namespace. If file is specified, then persistent namespace is created\nby bind mount.\n\n#### -T --time\n\nUnshare the time namespace. If file is specified, then a persistent namespace is created\nby a bind mount. The --monotonic and --boottime options can be used to specify the\ncorresponding offset in the time namespace.\n\n#### -f --fork\n\nFork the specified program as a child process of unshare rather than running it directly.\nThis is useful when creating a new PID namespace. Note that when unshare is waiting for\nthe child process, then it ignores SIGINT and SIGTERM and does not forward any signals to\nthe child. It is necessary to send signals to the child process.\n\n#### --keep-caps\n\nWhen the --user option is given, ensure that capabilities granted in the user namespace\nare preserved in the child process.\n\n--kill-child[=signame]\nWhen unshare terminates, have signame be sent to the forked child process. Combined with\n--pid this allows for an easy and reliable killing of the entire process tree below\nunshare. If not given, signame defaults to SIGKILL. This option implies --fork.\n\n--mount-proc[=mountpoint]\nJust before running the program, mount the proc filesystem at mountpoint (default is\n/proc). This is useful when creating a new PID namespace. It also implies creating a new\nmount namespace since the /proc mount would otherwise mess up existing programs on the\nsystem. The new proc filesystem is explicitly mounted as private (with\nMSPRIVATE|MSREC).\n\n--map-user=uid|name\nRun the program only after the current effective user ID has been mapped to uid. If this\noption is specified multiple times, the last occurrence takes precedence. This option\nimplies --user.\n\n--map-group=gid|name\nRun the program only after the current effective group ID has been mapped to gid. If this\noption is specified multiple times, the last occurrence takes precedence. This option\nimplies --setgroups=deny and --user.\n\n#### -r --map-root-user\n\nRun the program only after the current effective user and group IDs have been mapped to\nthe superuser UID and GID in the newly created user namespace. This makes it possible to\nconveniently gain capabilities needed to manage various aspects of the newly created\nnamespaces (such as configuring interfaces in the network namespace or mounting\nfilesystems in the mount namespace) even when run unprivileged. As a mere convenience\nfeature, it does not support more sophisticated use cases, such as mapping multiple\nranges of UIDs and GIDs. This option implies --setgroups=deny and --user. This option is\nequivalent to --map-user=0 --map-group=0.\n\n#### -c --map-current-user\n\nRun the program only after the current effective user and group IDs have been mapped to\nthe same UID and GID in the newly created user namespace. This option implies\n--setgroups=deny and --user. This option is equivalent to --map-user=$(id -ru)\n--map-group=$(id -rg).\n\n--propagation private|shared|slave|unchanged\nRecursively set the mount propagation flag in the new mount namespace. The default is to\nset the propagation to private. It is possible to disable this feature with the argument\nunchanged. The option is silently ignored when the mount namespace (--mount) is not\nrequested.\n\n--setgroups allow|deny\nAllow or deny the setgroups(2) system call in a user namespace.\n\nTo be able to call setgroups(2), the calling process must at least have CAPSETGID. But\nsince Linux 3.19 a further restriction applies: the kernel gives permission to call\nsetgroups(2) only after the GID map (/proc/pid*/gidmap*) has been set. The GID map is\nwritable by root when setgroups(2) is enabled (i.e., allow, the default), and the GID map\nbecomes writable by unprivileged processes when setgroups(2) is permanently disabled\n(with deny).\n\n#### -R --root=\n\nrun the command with root directory set to dir.\n\n#### -w --wd=\n\nchange working directory to dir.\n\n#### -S --setuid\n\nSet the user ID which will be used in the entered namespace.\n\n#### -G --setgid\n\nSet the group ID which will be used in the entered namespace and drop supplementary\ngroups.\n\n--monotonic offset\nSet the offset of CLOCKMONOTONIC which will be used in the entered time namespace. This\noption requires unsharing a time namespace with --time.\n\n--boottime offset\nSet the offset of CLOCKBOOTTIME which will be used in the entered time namespace. This\noption requires unsharing a time namespace with --time.\n\n#### -V --version\n\nDisplay version information and exit.\n\n#### -h --help\n\nDisplay help text and exit.\n\n### NOTES\n\nThe proc and sysfs filesystems mounting as root in a user namespace have to be restricted so\nthat a less privileged user can not get more access to sensitive files that a more privileged\nuser made unavailable. In short the rule for proc and sysfs is as close to a bind mount as\npossible.\n\n### EXAMPLES\n\nThe following command creates a PID namespace, using --fork to ensure that the executed\ncommand is performed in a child process that (being the first process in the namespace) has\nPID 1. The --mount-proc option ensures that a new mount namespace is also simultaneously\ncreated and that a new proc(5) filesystem is mounted that contains information corresponding\nto the new PID namespace. When the readlink command terminates, the new namespaces are\nautomatically torn down.\n\n# unshare --fork --pid --mount-proc readlink /proc/self\n1\n\nAs an unprivileged user, create a new user namespace where the user’s credentials are mapped\nto the root IDs inside the namespace:\n\n$ id -u; id -g\n1000\n1000\n$ unshare --user --map-root-user \\\nsh -c ''whoami; cat /proc/self/uidmap /proc/self/gidmap''\nroot\n0 1000 1\n0 1000 1\n\nThe first of the following commands creates a new persistent UTS namespace and modifies the\nhostname as seen in that namespace. The namespace is then entered with nsenter(1) in order to\ndisplay the modified hostname; this step demonstrates that the UTS namespace continues to\nexist even though the namespace had no member processes after the unshare command terminated.\nThe namespace is then destroyed by removing the bind mount.\n\n# touch /root/uts-ns\n# unshare --uts=/root/uts-ns hostname FOO\n# nsenter --uts=/root/uts-ns hostname\nFOO\n# umount /root/uts-ns\n\nThe following commands establish a persistent mount namespace referenced by the bind mount\n/root/namespaces/mnt. In order to ensure that the creation of that bind mount succeeds, the\nparent directory (/root/namespaces) is made a bind mount whose propagation type is not\nshared.\n\n# mount --bind /root/namespaces /root/namespaces\n# mount --make-private /root/namespaces\n# touch /root/namespaces/mnt\n# unshare --mount=/root/namespaces/mnt\n\nThe following commands demonstrate the use of the --kill-child option when creating a PID\nnamespace, in order to ensure that when unshare is killed, all of the processes within the\nPID namespace are killed.\n\n# set +m # Don't print job status messages\n\n\n# unshare --pid --fork --mount-proc --kill-child -- \\\n\n\nbash --norc -c ''(sleep 555 &) && (ps a &) && sleep 999'' &\n[1] 53456\n# PID TTY STAT TIME COMMAND\n1 pts/3 S+ 0:00 sleep 999\n3 pts/3 S+ 0:00 sleep 555\n5 pts/3 R+ 0:00 ps a\n\n# ps h -o 'comm' $! # Show that background job is unshare(1)\nunshare\n# kill $! # Kill unshare(1)\n# pidof sleep\n\nThe pidof(1) command prints no output, because the sleep processes have been killed. More\nprecisely, when the sleep process that has PID 1 in the namespace (i.e., the namespace’s init\nprocess) was killed, this caused all other processes in the namespace to be killed. By\ncontrast, a similar series of commands where the --kill-child option is not used shows that\nwhen unshare terminates, the processes in the PID namespace are not killed:\n\n# unshare --pid --fork --mount-proc -- \\\n\n\nbash --norc -c ''(sleep 555 &) && (ps a &) && sleep 999'' &\n[1] 53479\n# PID TTY STAT TIME COMMAND\n1 pts/3 S+ 0:00 sleep 999\n3 pts/3 S+ 0:00 sleep 555\n5 pts/3 R+ 0:00 ps a\n\n# kill $!\n# pidof sleep\n53482 53480\n\nThe following example demonstrates the creation of a time namespace where the boottime clock\nis set to a point several years in the past:\n\n# uptime -p # Show uptime in initial time namespace\nup 21 hours, 30 minutes\n# unshare --time --fork --boottime 300000000 uptime -p\nup 9 years, 28 weeks, 1 day, 2 hours, 50 minutes\n\n### AUTHORS\n\nMikhail Gusarov , Karel Zak \n\n### SEE ALSO\n\nclone(2), unshare(2), namespaces(7), mount(8)\n\n### REPORTING BUGS\n\nFor bug reports, use the issue tracker at https://github.com/karelzak/util-linux/issues.\n\n### AVAILABILITY\n\nThe unshare command is part of the util-linux package which can be downloaded from Linux\nKernel Archive .\n\n\n\nutil-linux 2.37.2 2021-07-20 UNSHARE(1)\n\n" } ], "structuredContent": { "command": "UNSHARE", "section": "1", "mode": "man", "summary": "unshare - run program in new namespaces", "synopsis": "unshare [options] [program [arguments]]", "tldr_summary": null, "tldr_examples": [], "tldr_source": null, "flags": [ { "flag": "-i", "long": "--ipc", "arg": null, "description": "Unshare the IPC namespace. If file is specified, then a persistent namespace is created by a bind mount." }, { "flag": "-m", "long": "--mount", "arg": null, "description": "Unshare the mount namespace. If file is specified, then a persistent namespace is created by a bind mount. 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." }, { "flag": "-n", "long": "--net", "arg": null, "description": "Unshare the network namespace. If file is specified, then a persistent namespace is created by a bind mount." }, { "flag": "-p", "long": "--pid", "arg": null, "description": "Unshare the PID namespace. If file is specified, then a persistent namespace is created by a bind mount. (Creation of a persistent PID namespace will fail if the --fork option is not also specified.) See also the --fork and --mount-proc options." }, { "flag": "-u", "long": "--uts", "arg": null, "description": "Unshare the UTS namespace. If file is specified, then a persistent namespace is created by a bind mount." }, { "flag": "-U", "long": "--user", "arg": null, "description": "Unshare the user namespace. If file is specified, then a persistent namespace is created by a bind mount." }, { "flag": "-C", "long": "--cgroup", "arg": null, "description": "Unshare the cgroup namespace. If file is specified, then persistent namespace is created by bind mount." }, { "flag": "-T", "long": "--time", "arg": null, "description": "Unshare the time namespace. If file is specified, then a persistent namespace is created by a bind mount. The --monotonic and --boottime options can be used to specify the corresponding offset in the time namespace." }, { "flag": "-f", "long": "--fork", "arg": null, "description": "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." }, { "flag": "", "long": "--keep-caps", "arg": null, "description": "When the --user option is given, ensure that capabilities granted in the user namespace are preserved in the child process. --kill-child[=signame] 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. --mount-proc[=mountpoint] 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 MSPRIVATE|MSREC). --map-user=uid|name 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. --map-group=gid|name 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." }, { "flag": "-r", "long": "--map-root-user", "arg": null, "description": "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." }, { "flag": "-c", "long": "--map-current-user", "arg": null, "description": "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). --propagation private|shared|slave|unchanged 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. --setgroups allow|deny 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 CAPSETGID. But since Linux 3.19 a further restriction applies: the kernel gives permission to call setgroups(2) only after the GID map (/proc/pid*/gidmap*) 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)." }, { "flag": "-R", "long": null, "arg": null, "description": "run the command with root directory set to dir." }, { "flag": "-w", "long": null, "arg": null, "description": "change working directory to dir." }, { "flag": "-S", "long": "--setuid", "arg": null, "description": "Set the user ID which will be used in the entered namespace." }, { "flag": "-G", "long": "--setgid", "arg": null, "description": "Set the group ID which will be used in the entered namespace and drop supplementary groups. --monotonic offset Set the offset of CLOCKMONOTONIC which will be used in the entered time namespace. This option requires unsharing a time namespace with --time. --boottime offset Set the offset of CLOCKBOOTTIME which will be used in the entered time namespace. This option requires unsharing a time namespace with --time." }, { "flag": "-V", "long": "--version", "arg": null, "description": "Display version information and exit." }, { "flag": "-h", "long": "--help", "arg": null, "description": "Display help text and exit." } ], "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 command terminates, the new namespaces are", "automatically torn down.", "# unshare --fork --pid --mount-proc readlink /proc/self", "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; id -g", "1000", "1000", "$ unshare --user --map-root-user \\", "sh -c ''whoami; cat /proc/self/uidmap /proc/self/gidmap''", "root", "0 1000 1", "0 1000 1", "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.", "# touch /root/uts-ns", "# unshare --uts=/root/uts-ns hostname FOO", "# nsenter --uts=/root/uts-ns hostname", "FOO", "# umount /root/uts-ns", "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.", "# mount --bind /root/namespaces /root/namespaces", "# mount --make-private /root/namespaces", "# touch /root/namespaces/mnt", "# unshare --mount=/root/namespaces/mnt", "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.", "# 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(1)", "unshare", "# kill $! # Kill unshare(1)", "# pidof sleep", "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:", "# 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", "The following example demonstrates the creation of a time namespace where the boottime clock", "is set to a point several years in the past:", "# 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" ], "see_also": [ { "name": "clone", "section": "2", "url": "https://www.chedong.com/phpMan.php/man/clone/2/json" }, { "name": "unshare", "section": "2", "url": "https://www.chedong.com/phpMan.php/man/unshare/2/json" }, { "name": "namespaces", "section": "7", "url": "https://www.chedong.com/phpMan.php/man/namespaces/7/json" }, { "name": "mount", "section": "8", "url": "https://www.chedong.com/phpMan.php/man/mount/8/json" } ], "section_outline": [ { "name": "NAME", "lines": 2, "subsections": [] }, { "name": "SYNOPSIS", "lines": 2, "subsections": [] }, { "name": "DESCRIPTION", "lines": 18, "subsections": [ { "name": "mount namespace", "lines": 10 }, { "name": "UTS namespace", "lines": 3 }, { "name": "IPC namespace", "lines": 4 }, { "name": "network namespace", "lines": 4 }, { "name": "PID namespace", "lines": 3 }, { "name": "cgroup namespace", "lines": 3 }, { "name": "user namespace", "lines": 3 }, { "name": "time namespace", "lines": 3 } ] }, { "name": "OPTIONS", "lines": 1, "subsections": [ { "name": "-i --ipc", "lines": 3, "flag": "-i", "long": "--ipc" }, { "name": "-m --mount", "lines": 5, "flag": "-m", "long": "--mount" }, { "name": "-n --net", "lines": 3, "flag": "-n", "long": "--net" }, { "name": "-p --pid", "lines": 6, "flag": "-p", "long": "--pid" }, { "name": "-u --uts", "lines": 3, "flag": "-u", "long": "--uts" }, { "name": "-U --user", "lines": 3, "flag": "-U", "long": "--user" }, { "name": "-C --cgroup", "lines": 3, "flag": "-C", "long": "--cgroup" }, { "name": "-T --time", "lines": 4, "flag": "-T", "long": "--time" }, { "name": "-f --fork", "lines": 5, "flag": "-f", "long": "--fork" }, { "name": "--keep-caps", "lines": 25, "long": "--keep-caps" }, { "name": "-r --map-root-user", "lines": 9, "flag": "-r", "long": "--map-root-user" }, { "name": "-c --map-current-user", "lines": 21, "flag": "-c", "long": "--map-current-user" }, { "name": "-R --root=", "lines": 2, "flag": "-R" }, { "name": "-w --wd=", "lines": 2, "flag": "-w" }, { "name": "-S --setuid", "lines": 2, "flag": "-S", "long": "--setuid" }, { "name": "-G --setgid", "lines": 11, "flag": "-G", "long": "--setgid" }, { "name": "-V --version", "lines": 2, "flag": "-V", "long": "--version" }, { "name": "-h --help", "lines": 2, "flag": "-h", "long": "--help" } ] }, { "name": "NOTES", "lines": 5, "subsections": [] }, { "name": "EXAMPLES", "lines": 94, "subsections": [] }, { "name": "AUTHORS", "lines": 2, "subsections": [] }, { "name": "SEE ALSO", "lines": 2, "subsections": [] }, { "name": "REPORTING BUGS", "lines": 2, "subsections": [] }, { "name": "AVAILABILITY", "lines": 6, "subsections": [] } ] } }