.\" Copyright (C) 2006, Janak Desai <janak@us.ibm.com>
-.\" and Copyright (C) 2006, Michael Kerrisk <mtk.manpages@gmail.com>
+.\" and Copyright (C) 2006, 2012 Michael Kerrisk <mtk.manpages@gmail.com>
+.\"
+.\" %%%LICENSE_START(GPL_NOVERSION_ONELINE)
.\" Licensed under the GPL
+.\" %%%LICENSE_END
.\"
.\" Patch Justification:
.\" unshare system call is needed to implement, using PAM,
.\" by clone, which would require porting and maintaining all commands
.\" such as login, and su, that establish a user session.
.\"
-.\" FIXME Document CLONE_NEWIPC, which is new in 2.6.18
-.\" FIXME Document CLONE_NEWUTS, which is new in 2.6.19
-.\" FIXME Document CLONE_SYSVSEM, which is new in 2.6.26
-.\"
-.TH UNSHARE 2 2008-11-20 "Linux" "Linux Programmer's Manual"
+.TH UNSHARE 2 2014-09-21 "Linux" "Linux Programmer's Manual"
.SH NAME
unshare \- disassociate parts of the process execution context
.SH SYNOPSIS
.nf
-.B #define _GNU_SOURCE
-.\" Actually _BSD_SOURCE || _SVID_SOURCE
-.\" See http://sources.redhat.com/bugzilla/show_bug.cgi?id=4749
.B #include <sched.h>
.sp
.BI "int unshare(int " flags );
.fi
+.sp
+.in -4n
+Feature Test Macro Requirements for glibc (see
+.BR feature_test_macros (7)):
+.in
+.sp
+.BR unshare ():
+.ad l
+.RS 4
+.PD 0
+.TP 4
+Since glibc 2.14:
+_GNU_SOURCE
+.TP 4
+.\" See http://sources.redhat.com/bugzilla/show_bug.cgi?id=4749
+Before glibc 2.14:
+_BSD_SOURCE || _SVID_SOURCE
+ /* _GNU_SOURCE also suffices */
+.PD
+.RE
+.ad b
.SH DESCRIPTION
.BR unshare ()
allows a process to disassociate parts of its execution
.BR clone (2)
.B CLONE_FS
flag.
-Unshare file system attributes, so that the calling process
-no longer shares its root directory, current directory,
-or umask attributes with any other process.
-.BR chroot (2),
-.BR chdir (2),
-or
-.BR umask (2)
+Unshare filesystem attributes, so that the calling process
+no longer shares its root directory
+.RB ( chroot (2)),
+current directory
+.RB ( chdir (2)),
+or umask
+.RB ( umask (2))
+attributes with any other process.
+.TP
+.BR CLONE_NEWIPC " (since Linux 2.6.19)
+This flag has the same effect as the
+.BR clone (2)
+.B CLONE_NEWIPC
+flag.
+Unshare the System\ V IPC namespace,
+so that the calling process has a private copy of the
+System\ V IPC namespace which is not shared with any other process.
+Specifying this flag automatically implies
+.BR CLONE_SYSVSEM
+as well.
+Use of
+.BR CLONE_NEWIPC
+requires the
+.BR CAP_SYS_ADMIN
+capability.
+.TP
+.BR CLONE_NEWNET " (since Linux 2.6.24)
+This flag has the same effect as the
+.BR clone (2)
+.B CLONE_NEWNET
+flag.
+Unshare the network namespace,
+so that the calling process is moved into a
+new network namespace which is not shared
+with any previously existing process.
+Use of
+.BR CLONE_NEWNET
+requires the
+.BR CAP_SYS_ADMIN
+capability.
.TP
.B CLONE_NEWNS
.\" These flag name are inconsistent:
.\" CLONE_NEWNS does the same thing in clone(), but CLONE_VM,
.\" CLONE_FS, and CLONE_FILES reverse the action of the clone()
.\" flags of the same name.
-This flag has the
-.I same
-effect as the
+This flag has the same effect as the
.BR clone (2)
.B CLONE_NEWNS
flag.
Specifying this flag automatically implies
.B CLONE_FS
as well.
-.\" As at 2.6.16, the following forced implications also apply,
+Use of
+.BR CLONE_NEWNS
+requires the
+.BR CAP_SYS_ADMIN
+capability.
+.TP
+.BR CLONE_NEWPID " (since Linux 3.8)"
+This flag has the same effect as the
+.BR clone (2)
+.B CLONE_NEWPID
+flag.
+Unshare the PID namespace,
+so that the calling process has a new PID namespace for its children
+which is not shared with any previously existing process.
+The calling process is
+.I not
+moved into the new namespace.
+The first child created by the calling process will have
+the process ID 1 and will assume the role of
+.BR init (1)
+in the new namespace.
+.BR CLONE_NEWPID
+automatically implies
+.BR CLONE_THREAD
+as well.
+Use of
+.BR CLONE_NEWPID
+requires the
+.BR CAP_SYS_ADMIN
+capability.
+For further information, see
+.BR pid_namespaces (7).
+.TP
+.BR CLONE_NEWUSER " (since Linux 3.8)"
+This flag has the same effect as the
+.BR clone (2)
+.B CLONE_NEWUSER
+flag.
+Unshare the user namespace,
+so that the calling process is moved into a new user namespace
+which is not shared with any previously existing process.
+As with the child process created by
+.BR clone (2)
+with the
+.B CLONE_NEWUSER
+flag, the caller obtains a full set of capabilities in the new namespace.
+.IP
+.BR CLONE_NEWUSER
+requires that the calling process is not threaded; specifying
+.BR CLONE_NEWUSER
+automatically implies
+.BR CLONE_THREAD .
+Since Linux 3.9,
+.\" commit e66eded8309ebf679d3d3c1f5820d1f2ca332c71
+.\" https://lwn.net/Articles/543273/
+.BR CLONE_NEWUSER
+also automatically implies
+.BR CLONE_FS .
+.BR CLONE_NEWUSER
+requires that the user ID and group ID
+of the calling process are mapped to user IDs and group IDs in the
+user namespace of the calling process at the time of the call.
+
+For further information on user namespaces, see
+.BR user_namespaces (7).
+.TP
+.BR CLONE_NEWUTS " (since Linux 2.6.19)"
+This flag has the same effect as the
+.BR clone (2)
+.B CLONE_NEWUTS
+flag.
+Unshare the UTS IPC namespace,
+so that the calling process has a private copy of the
+UTS namespace which is not shared with any other process.
+Use of
+.BR CLONE_NEWUTS
+requires the
+.BR CAP_SYS_ADMIN
+capability.
+.TP
+.BR CLONE_SYSVSEM " (since Linux 2.6.26)
+.\" commit 9edff4ab1f8d82675277a04e359d0ed8bf14a7b7
+This flag reverses the effect of the
+.BR clone (2)
+.B CLONE_SYSVSEM
+flag.
+Unshare System\ V semaphore adjustment
+.RI ( semadj )
+values,
+so that the calling process has a new empty
+.I semadj
+list that is not shared with any other process.
+If this is the last process that has a reference to the process's current
+.I semadj
+list, then the adjustments in that list are applied
+to the corresponding semaphores, as described in
+.BR semop (2).
+.\" CLONE_NEWNS If CLONE_SIGHAND is set and signals are also being shared
+.\" (i.e., current->signal->count > 1), force CLONE_THREAD.
+.PP
+In addition,
+.BR CLONE_THREAD ,
+.BR CLONE_SIGHAND ,
+and
+.BR CLONE_VM
+can be specified in
+.I flags
+if the caller is single threaded (i.e., it is not sharing
+its address space with another process or thread).
+In this case, these flags have no effect.
+(Note also that specifying
+.BR CLONE_THREAD
+automatically implies
+.BR CLONE_VM ,
+and specifying
+.BR CLONE_VM
+automatically implies
+.BR CLONE_SIGHAND .)
+.\" As at 3.9, the following forced implications also apply,
.\" although the relevant flags are not yet implemented.
.\" If CLONE_THREAD is set force CLONE_VM.
.\" If CLONE_VM is set, force CLONE_SIGHAND.
-.\" If CLONE_SIGHAND is set and signals are also being shared
-.\" (i.e., current->signal->count > 1), force CLONE_THREAD.
.\"
-.\" FIXME . CLONE_VM is not (yet, as at 2.6.16) implemented.
-.\" .TP
-.\" .B CLONE_VM
-.\" Reverse the effect of the
-.\" .BR clone (2)
-.\" .B CLONE_VM
-.\" flag.
-.\" .RB ( CLONE_VM
-.\" is also implicitly set by
-.\" .BR vfork (2),
-.\" and can be reversed using this
-.\" .BR unshare ()
-.\" flag.)
-.\" Unshare virtual memory, so that the calling process no
-.\" longer shares its virtual address space with any other process.
+If the process is multithreaded, then
+the use of these flags results in an error.
+.\" See kernel/fork.c::check_unshare_flags()
.PP
If
.I flags
An invalid bit was specified in
.IR flags .
.TP
+.B EINVAL
+.BR CLONE_THREAD ,
+.BR CLONE_SIGHAND ,
+or
+.BR CLONE_VM
+was specified in
+.IR flags ,
+and the caller is multithreaded.
+.TP
.B ENOMEM
Cannot allocate sufficient memory to copy parts of caller's
context that need to be unshared.
.TP
.B EPERM
+The calling process did not have the required privileges for this operation.
+.TP
+.B EPERM
+.BR CLONE_NEWUSER
+was specified in
+.IR flags ,
+but either the effective user ID or the effective group ID of the caller
+does not have a mapping in the parent namespace (see
+.BR user_namespaces (7)).
+.TP
+.BR EPERM " (since Linux 3.9)"
+.\" commit 3151527ee007b73a0ebd296010f1c0454a919c7d
+.B CLONE_NEWUSER
+was specified in
.I flags
-specified
-.B CLONE_NEWNS
-but the calling process was not privileged (did not have the
-.B CAP_SYS_ADMIN
-capability).
+and the caller is in a chroot environment
+.\" FIXME What is the rationale for this restriction?
+(i.e., the caller's root directory does not match the root directory
+of the mount namespace in which it resides).
+.TP
+.BR EUSERS " (since Linux 3.11)"
+.B CLONE_NEWUSER
+was specified in
+.IR flags ,
+and the call would cause the limit on the number of
+nested user namespaces to be exceeded.
+See
+.BR user_namespaces (7).
.SH VERSIONS
The
.BR unshare ()
.BR clone (2)
can be unshared using
.BR unshare ().
-In particular, as at kernel 2.6.16,
+In particular, as at kernel 3.8,
+.\" FIXME all of the following needs to be reviewed for the current kernel
.BR unshare ()
does not implement flags that reverse the effects of
.BR CLONE_SIGHAND ,
.\" was not specified when doing clone(); i.e., unsharing
.\" signal handlers is permitted if we are not actually
.\" sharing signal handlers. mtk
-.BR CLONE_SYSVSEM ,
.BR CLONE_THREAD ,
or
-.\" FIXME . check future kernel versions (e.g., 2.6.17)
-.\" to see if CLONE_VM gets implemented.
.BR CLONE_VM .
-.\" However, as at 2.6.16, we can do unshare(CLONE_VM) if CLONE_VM
+.\" However, we can do unshare(CLONE_VM) if CLONE_VM
.\" was not specified when doing clone(); i.e., unsharing
.\" virtual memory is permitted if we are not actually
.\" sharing virtual memory. mtk
.\"be incrementally added to unshare without affecting legacy
.\"applications using unshare.
.\"
+.SH EXAMPLE
+The program below provides a simple implementation of the
+.BR unshare (1)
+command, which unshares one or more namespaces and executes the
+command supplied in its command-line arguments.
+Here's an example of the use of this program,
+running a shell in a new mount namespace,
+and verifying that the original shell and the
+new shell are in separate mount namespaces:
+.in +4n
+.nf
+
+$ \fBreadlink /proc/$$/ns/mnt\fP
+mnt:[4026531840]
+$ \fBsudo ./unshare -m /bin/bash\fP
+[sudo] password for cecilia:
+# \fBreadlink /proc/$$/ns/mnt\fP
+mnt:[4026532325]
+.fi
+.in
+
+The differing output of the two
+.BR readlink (1)
+commands shows that the two shells are in different mount namespaces.
+.SS Program source
+\&
+.nf
+/* unshare.c
+
+ A simple implementation of the unshare(1) command: unshare
+ namespaces and execute a command.
+*/
+#define _GNU_SOURCE
+#include <sched.h>
+#include <unistd.h>
+#include <stdlib.h>
+#include <stdio.h>
+
+/* A simple error\-handling function: print an error message based
+ on the value in \(aqerrno\(aq and terminate the calling process */
+
+#define errExit(msg) do { perror(msg); exit(EXIT_FAILURE); \\
+ } while (0)
+
+static void
+usage(char *pname)
+{
+ fprintf(stderr, "Usage: %s [options] program [arg...]\\n", pname);
+ fprintf(stderr, "Options can be:\\n");
+ fprintf(stderr, " \-i unshare IPC namespace\\n");
+ fprintf(stderr, " \-m unshare mount namespace\\n");
+ fprintf(stderr, " \-n unshare network namespace\\n");
+ fprintf(stderr, " \-p unshare PID namespace\\n");
+ fprintf(stderr, " \-u unshare UTS namespace\\n");
+ fprintf(stderr, " \-U unshare user namespace\\n");
+ exit(EXIT_FAILURE);
+}
+
+int
+main(int argc, char *argv[])
+{
+ int flags, opt;
+
+ flags = 0;
+
+ while ((opt = getopt(argc, argv, "imnpuU")) != \-1) {
+ switch (opt) {
+ case \(aqi\(aq: flags |= CLONE_NEWIPC; break;
+ case \(aqm\(aq: flags |= CLONE_NEWNS; break;
+ case \(aqn\(aq: flags |= CLONE_NEWNET; break;
+ case \(aqp\(aq: flags |= CLONE_NEWPID; break;
+ case \(aqu\(aq: flags |= CLONE_NEWUTS; break;
+ case \(aqU\(aq: flags |= CLONE_NEWUSER; break;
+ default: usage(argv[0]);
+ }
+ }
+
+ if (optind >= argc)
+ usage(argv[0]);
+
+ if (unshare(flags) == \-1)
+ errExit("unshare");
+
+ execvp(argv[optind], &argv[optind]);
+ errExit("execvp");
+}
+.fi
.SH SEE ALSO
+.BR unshare (1),
.BR clone (2),
.BR fork (2),
+.BR kcmp (2),
+.BR setns (2),
.BR vfork (2),
-Documentation/unshare.txt
+.BR namespaces (7)
+
+.I Documentation/unshare.txt
+in the Linux kernel source tree
+.SH COLOPHON
+This page is part of release 3.79 of the Linux
+.I man-pages
+project.
+A description of the project,
+information about reporting bugs,
+and the latest version of this page,
+can be found at
+\%http://www.kernel.org/doc/man\-pages/.
OSDN Git Service
