release/man2/unshare.2

   1 .\" Copyright (C) 2006, Janak Desai <janak@us.ibm.com>
   2 .\" and Copyright (C) 2006, 2012 Michael Kerrisk <mtk.manpages@gmail.com>
   3 .\"
   4 .\" %%%LICENSE_START(GPL_NOVERSION_ONELINE)
   5 .\" Licensed under the GPL
   6 .\" %%%LICENSE_END
   7 .\"
   8 .\" Patch Justification:
   9 .\" unshare system call is needed to implement, using PAM,
  10 .\" per-security_context and/or per-user namespace to provide
  11 .\" polyinstantiated directories. Using unshare and bind mounts, a
  12 .\" PAM module can create private namespace with appropriate
  13 .\" directories(based on user's security context) bind mounted on
  14 .\" public directories such as /tmp, thus providing an instance of
  15 .\" /tmp that is based on user's security context. Without the
  16 .\" unshare system call, namespace separation can only be achieved
  17 .\" by clone, which would require porting and maintaining all commands
  18 .\" such as login, and su, that establish a user session.
  19 .\"
  20 .\"*******************************************************************
  21 .\"
  22 .\" This file was generated with po4a. Translate the source file.
  23 .\"
  24 .\"*******************************************************************
  25 .\"
  26 .\" Japanese Version Copyright (c) 2006 Yuichi SATO
  27 .\"         all rights reserved.
  28 .\" Translated 2006-08-10 by Yuichi SATO <ysato444@yahoo.co.jp>, LDP v2.36
  29 .\" Updated 2012-05-08, Akihiro MOTOKI <amotoki@gmail.com>
  30 .\" Updated 2013-03-26, Akihiro MOTOKI <amotoki@gmail.com>
  31 .\" Updated 2013-05-06, Akihiro MOTOKI <amotoki@gmail.com>
  32 .\"
  33 .TH UNSHARE 2 2014\-09\-21 Linux "Linux Programmer's Manual"
  34 .SH 名前
  35 unshare \- プロセス実行コンテキストの一部を分離する
  36 .SH 書式
  37 .nf
  38 \fB#include <sched.h>\fP
  39 .sp
  40 \fBint unshare(int \fP\fIflags\fP\fB);\fP
  41 .fi
  42 .sp
  43 .in -4n
  44 glibc 向けの機能検査マクロの要件 (\fBfeature_test_macros\fP(7)  参照):
  45 .in
  46 .sp
  47 \fBunshare\fP():
  48 .ad l
  49 .RS 4
  50 .PD 0
  51 .TP  4
  52 glibc 2.14 以降:
  53 _GNU_SOURCE
  54 .TP  4
  55 .\" See http://sources.redhat.com/bugzilla/show_bug.cgi?id=4749
  56 glibc 2.14 より前:
  57 _BSD_SOURCE || _SVID_SOURCE
  58     /* _GNU_SOURCE も定義される */
  59 .PD
  60 .RE
  61 .ad b
  62 .SH 説明
  63 \fBunshare\fP()  を使うと、プロセスは他のプロセスと現在共有している 実行コンテキストの一部を分離することができる。
  64 実行コンテキストの一部、たとえばマウント名前空間 (mount namespace)  などは、新しいプロセスを \fBfork\fP(2)  または
  65 \fBvfork\fP(2)  を使って生成したときに、暗黙のうちに共有される。 一方、仮想メモリなどは、 \fBclone\fP(2)
  66 を使ってプロセスを生成するときに、明示的に共有することを要求できる。
  67
  68 \fBunshare\fP()  の主な利用法は、プロセスが新しいプロセスを生成することなく、 共有実行コンテキストを制御することである。
  69
  70 \fIflags\fP 引き数はビットマスクであり、 実行コンテキストのどの部分の共有を解除するかを表す。 この引き数は、以下の定数の 0 個以上の OR
  71 で指定する:
  72 .TP
  73 \fBCLONE_FILES\fP
  74 \fBclone\fP(2)  \fBCLONE_FILES\fP フラグの効果を取り消す。 ファイルディスクリプタテーブルを共有させず、
  75 呼び出し元プロセスは他のプロセスとファイルディスクリプタを共有しなくなる。
  76 .TP
  77 \fBCLONE_FS\fP
  78 \fBclone\fP(2)  \fBCLONE_FS\fP フラグの効果を取り消す。ファイルシステム属性を共有させず、呼び出し元プロセスは、ルートディレクトリ
  79 (\fBchroot\fP(2))、カレントディレクトリ (\fBchdir\fP(2))、 umask (\fBumask\fP(2))
  80 を他のプロセスと共有しなくなる。
  81 .TP
  82 \fBCLONE_NEWIPC\fP (Linux 2.6.19 以降)
  83 このフラグは \fBclone\fP(2) \fBCLONE_NEWIPC\fP フラグと同じ効果を持つ。
  84 System\ V IPC 名前空間を共有せず、呼び出し元プロセスは 他のプロセスとは
  85 共有しない固有の System\ V IPC 名前空間のコピーを持つ。 このフラグを指定
  86 すると、 \fBCLONE_SYSVSEM\fP も暗黙のうちに指定される。 \fBCLONE_NEWIPC\fP を
  87 使用するには \fBCAP_SYS_ADMIN\fP ケーパビリティが必要である。
  88 .TP
  89 \fBCLONE_NEWNET\fP (Linux 2.6.24 以降)
  90 このフラグは \fBclone\fP(2) \fBCLONE_NEWNET\fP フラグと同じ効果を持つ。ネット
  91 ワーク名前空間を共有せず、呼び出し元プロセスは他のプロセスとは共有しな
  92 い固有のネットワーク名前空間のコピーを持つ。\fBCLONE_NEWNET\fP を使用する
  93 には \fBCAP_SYS_ADMIN\fP ケーパビリティが必要である。
  94 .TP
  95 \fBCLONE_NEWNS\fP
  96 .\" These flag name are inconsistent:
  97 .\" CLONE_NEWNS does the same thing in clone(), but CLONE_VM,
  98 .\" CLONE_FS, and CLONE_FILES reverse the action of the clone()
  99 .\" flags of the same name.
 100 このフラグは \fBclone\fP(2) \fBCLONE_NEWNS\fP フラグと同じ効果を持つ。 マウン
 101 ト名前空間を共有せず、呼び出し元プロセスは 他のプロセスとは共有しない固
 102 有の名前空間のコピーを持つ。 このフラグを指定すると、 \fBCLONE_FS\fP も暗
 103 黙のうちに指定される。 \fBCLONE_NEWNS\fP を使用するには \fBCAP_SYS_ADMIN\fP
 104 ケーパビリティが必要である。
 105 .TP
 106 \fBCLONE_NEWPID\fP (Linux 3.8 以降)
 107 This flag has the same effect as the \fBclone\fP(2)  \fBCLONE_NEWPID\fP flag.
 108 Unshare the PID namespace, so that the calling process has a new PID
 109 namespace for its children which is not shared with any previously existing
 110 process.  The calling process is \fInot\fP moved into the new namespace.  The
 111 first child created by the calling process will have the process ID 1 and
 112 will assume the role of \fBinit\fP(1)  in the new namespace.  \fBCLONE_NEWPID\fP
 113 automatically implies \fBCLONE_THREAD\fP as well.  Use of \fBCLONE_NEWPID\fP
 114 requires the \fBCAP_SYS_ADMIN\fP capability.  For further information, see
 115 \fBpid_namespaces\fP(7).
 116 .TP
 117 \fBCLONE_NEWUSER\fP (Linux 3.8 以降)
 118 This flag has the same effect as the \fBclone\fP(2)  \fBCLONE_NEWUSER\fP flag.
 119 Unshare the user namespace, so that the calling process is moved into a new
 120 user namespace which is not shared with any previously existing process.  As
 121 with the child process created by \fBclone\fP(2)  with the \fBCLONE_NEWUSER\fP
 122 flag, the caller obtains a full set of capabilities in the new namespace.
 123 .IP
 124 .\" commit e66eded8309ebf679d3d3c1f5820d1f2ca332c71
 125 .\" https://lwn.net/Articles/543273/
 126 \fBCLONE_NEWUSER\fP requires that the calling process is not threaded;
 127 specifying \fBCLONE_NEWUSER\fP automatically implies \fBCLONE_THREAD\fP.  Since
 128 Linux 3.9, \fBCLONE_NEWUSER\fP also automatically implies \fBCLONE_FS\fP.
 129 \fBCLONE_NEWUSER\fP requires that the user ID and group ID of the calling
 130 process are mapped to user IDs and group IDs in the user namespace of the
 131 calling process at the time of the call.
 132
 133 For further information on user namespaces, see \fBuser_namespaces\fP(7).
 134 .TP
 135 \fBCLONE_NEWUTS\fP (Linux 2.6.19 以降)
 136 このフラグは \fBclone\fP(2) \fBCLONE_NEWUTS\fP フラグと同じ効果を持つ。 UTS
 137 IPC 名前空間を共有せず、呼び出し元プロセスは他のプロセスとは共有しない
 138 固有の UTS IPC 名前空間のコピーを持つ。 このフラグを指定すると、
 139 \fBCLONE_FS\fP も暗黙のうちに指定される。\fBCLONE_NEWUTS\fP を使用するには
 140 \fBCAP_SYS_ADMIN\fP ケーパビリティが必要である。
 141 .TP
 142 \fBCLONE_SYSVSEM\fP (Linux 2.6.26 以降)
 143 .\" commit 9edff4ab1f8d82675277a04e359d0ed8bf14a7b7
 144 .\" CLONE_NEWNS If CLONE_SIGHAND is set and signals are also being shared
 145 .\" (i.e., current->signal->count > 1), force CLONE_THREAD.
 146 This flag reverses the effect of the \fBclone\fP(2)  \fBCLONE_SYSVSEM\fP flag.
 147 Unshare System\ V semaphore adjustment (\fIsemadj\fP)  values, so that the
 148 calling process has a new empty \fIsemadj\fP list that is not shared with any
 149 other process.  If this is the last process that has a reference to the
 150 process's current \fIsemadj\fP list, then the adjustments in that list are
 151 applied to the corresponding semaphores, as described in \fBsemop\fP(2).
 152 .PP
 153 .\" As at 3.9, the following forced implications also apply,
 154 .\" although the relevant flags are not yet implemented.
 155 .\" If CLONE_THREAD is set force CLONE_VM.
 156 .\" If CLONE_VM is set, force CLONE_SIGHAND.
 157 .\"
 158 .\" See kernel/fork.c::check_unshare_flags()
 159 In addition, \fBCLONE_THREAD\fP, \fBCLONE_SIGHAND\fP, and \fBCLONE_VM\fP can be
 160 specified in \fIflags\fP if the caller is single threaded (i.e., it is not
 161 sharing its address space with another process or thread).  In this case,
 162 these flags have no effect.  (Note also that specifying \fBCLONE_THREAD\fP
 163 automatically implies \fBCLONE_VM\fP, and specifying \fBCLONE_VM\fP automatically
 164 implies \fBCLONE_SIGHAND\fP.)  If the process is multithreaded, then the use of
 165 these flags results in an error.
 166 .PP
 167 \fIflags\fP に 0 が指定された場合、 \fBunshare\fP()  は何も行わないので、
 168 呼び出し元プロセスの実行コンテキストは、何も変更されない。
 169 .SH 返り値
 170 成功した場合は 0 が返される。 失敗した場合は \-1 が返されて、 \fIerrno\fP にはエラーを示す値が設定される。
 171 .SH エラー
 172 .TP
 173 \fBEINVAL\fP
 174 \fIflags\fP に不正なビットが指定された。
 175 .TP
 176 \fBEINVAL\fP
 177 \fBCLONE_THREAD\fP, \fBCLONE_SIGHAND\fP, or \fBCLONE_VM\fP was specified in \fIflags\fP,
 178 and the caller is multithreaded.
 179 .TP
 180 \fBENOMEM\fP
 181 呼び出し元のコンテキストのうち共有を解除する必要がある部分をコピーするために、 十分なメモリが確保できなかった。
 182 .TP
 183 \fBEPERM\fP
 184 呼び出し元プロセスはこの操作を行うのに必要な特権を持っていなかった。
 185 .TP
 186 \fBEPERM\fP
 187 \fBCLONE_NEWUSER\fP was specified in \fIflags\fP, but either the effective user ID
 188 or the effective group ID of the caller does not have a mapping in the
 189 parent namespace (see \fBuser_namespaces\fP(7)).
 190 .TP
 191 \fBEPERM\fP (Linux 3.9 以降)
 192 .\" commit 3151527ee007b73a0ebd296010f1c0454a919c7d
 193 .\" FIXME What is the rationale for this restriction?
 194 \fBCLONE_NEWUSER was specified in\fP \fIflags\fP and the caller is in a chroot
 195 environment (i.e., the caller's root directory does not match the root
 196 directory of the mount namespace in which it resides).
 197 .TP
 198 \fBEUSERS\fP (Linux 3.11 以降)
 199 \fBCLONE_NEWUSER\fP was specified in \fIflags\fP, and the call would cause the
 200 limit on the number of nested user namespaces to be exceeded.  See
 201 \fBuser_namespaces\fP(7).
 202 .SH バージョン
 203 \fBunshare\fP()  システムコールは Linux カーネル 2.6.16 で追加された。
 204 .SH 準拠
 205 \fBunshare\fP()  システムコールは Linux 固有である。
 206 .SH 注意
 207 .\" FIXME all of the following needs to be reviewed for the current kernel
 208 .\" However, we can do unshare(CLONE_SIGHAND) if CLONE_SIGHAND
 209 .\" was not specified when doing clone(); i.e., unsharing
 210 .\" signal handlers is permitted if we are not actually
 211 .\" sharing signal handlers.   mtk
 212 .\" However, we can do unshare(CLONE_VM) if CLONE_VM
 213 .\" was not specified when doing clone(); i.e., unsharing
 214 .\" virtual memory is permitted if we are not actually
 215 .\" sharing virtual memory.   mtk
 216 .\"
 217 .\"9) Future Work
 218 .\"--------------
 219 .\"The current implementation of unshare does not allow unsharing of
 220 .\"signals and signal handlers. Signals are complex to begin with and
 221 .\"to unshare signals and/or signal handlers of a currently running
 222 .\"process is even more complex. If in the future there is a specific
 223 .\"need to allow unsharing of signals and/or signal handlers, it can
 224 .\"be incrementally added to unshare without affecting legacy
 225 .\"applications using unshare.
 226 .\"
 227 \fBclone\fP(2)  で新しいプロセスを生成したときに共有される全てのプロセス属性を、 \fBunshare\fP()
 228 によって共有の解除ができるわけではない。 特に、カーネル 3.8 時点では、 \fBunshare\fP()  に \fBCLONE_SIGHAND\fP,
 229 \fBCLONE_THREAD\fP, \fBCLONE_VM\fP の効果を取り消すためのフラグが実装されていない。
 230 これらの機能は、必要であれば将来追加されるかもしれない。
 231 .SH 例
 232 The program below provides a simple implementation of the \fBunshare\fP(1)
 233 command, which unshares one or more namespaces and executes the command
 234 supplied in its command\-line arguments.  Here's an example of the use of
 235 this program, running a shell in a new mount namespace, and verifying that
 236 the original shell and the new shell are in separate mount namespaces:
 237 .in +4n
 238 .nf
 239
 240 $ \fBreadlink /proc/$$/ns/mnt\fP
 241 mnt:[4026531840]
 242 $ \fBsudo ./unshare \-m /bin/bash\fP
 243 [sudo] password for cecilia:
 244 # \fBreadlink /proc/$$/ns/mnt\fP
 245 mnt:[4026532325]
 246 .fi
 247 .in
 248
 249 The differing output of the two \fBreadlink\fP(1)  commands shows that the two
 250 shells are in different mount namespaces.
 251 .SS プログラムのソース
 252 \&
 253 .nf
 254 /* unshare.c
 255
 256    A simple implementation of the unshare(1) command: unshare
 257    namespaces and execute a command.
 258 */
 259 #define _GNU_SOURCE
 260 #include <sched.h>
 261 #include <unistd.h>
 262 #include <stdlib.h>
 263 #include <stdio.h>
 264
 265 /* A simple error\-handling function: print an error message based
 266    on the value in \(aqerrno\(aq and terminate the calling process */
 267
 268 #define errExit(msg)    do { perror(msg); exit(EXIT_FAILURE); \e
 269                         } while (0)
 270
 271 static void
 272 usage(char *pname)
 273 {
 274     fprintf(stderr, "Usage: %s [options] program [arg...]\en", pname);
 275     fprintf(stderr, "Options can be:\en");
 276     fprintf(stderr, "    \-i   unshare IPC namespace\en");
 277     fprintf(stderr, "    \-m   unshare mount namespace\en");
 278     fprintf(stderr, "    \-n   unshare network namespace\en");
 279     fprintf(stderr, "    \-p   unshare PID namespace\en");
 280     fprintf(stderr, "    \-u   unshare UTS namespace\en");
 281     fprintf(stderr, "    \-U   unshare user namespace\en");
 282     exit(EXIT_FAILURE);
 283 }
 284
 285 int
 286 main(int argc, char *argv[])
 287 {
 288     int flags, opt;
 289
 290     flags = 0;
 291
 292     while ((opt = getopt(argc, argv, "imnpuU")) != \-1) {
 293         switch (opt) {
 294         case \(aqi\(aq: flags |= CLONE_NEWIPC;        break;
 295         case \(aqm\(aq: flags |= CLONE_NEWNS;         break;
 296         case \(aqn\(aq: flags |= CLONE_NEWNET;        break;
 297         case \(aqp\(aq: flags |= CLONE_NEWPID;        break;
 298         case \(aqu\(aq: flags |= CLONE_NEWUTS;        break;
 299         case \(aqU\(aq: flags |= CLONE_NEWUSER;       break;
 300         default:  usage(argv[0]);
 301         }
 302     }
 303
 304     if (optind >= argc)
 305         usage(argv[0]);
 306
 307     if (unshare(flags) == \-1)
 308         errExit("unshare");
 309
 310     execvp(argv[optind], &argv[optind]);
 311     errExit("execvp");
 312 }
 313 .fi
 314 .SH 関連項目
 315 \fBunshare\fP(1), \fBclone\fP(2), \fBfork\fP(2), \fBkcmp\fP(2), \fBsetns\fP(2),
 316 \fBvfork\fP(2), \fBnamespaces\fP(7)
 317
 318 Linux カーネルソース内の \fIDocumentation/unshare.txt\fP
 319 .SH この文書について
 320 この man ページは Linux \fIman\-pages\fP プロジェクトのリリース 3.76 の一部
 321 である。プロジェクトの説明とバグ報告に関する情報は
 322 http://www.kernel.org/doc/man\-pages/ に書かれている。