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 このフラグは \fBclone\fP(2) \fBCLONE_NEWPID\fP フラグと同じ効果を持つ。 PID 名前空間を共有しない。 呼び出し元プロセスは、
 108 すでに存在するどのプロセスとも共有されない新しい PID 名前空間を、 自身の子プロセス用に持つことになる。
 109 このプロセスにより作成される最初の子プロセスはプロセス ID 1 を持ち、 この新しい名前空間において \fBinit\fP(1) の役割を持つとみなされる。
 110 \fBCLONE_NEWPID\fP を指定すると、自動的に \fBCLONE_THREAD\fP も指定されたものとみなされる。 \fBCLONE_NEWPID\fP
 111 を使用するには \fBCAP_SYS_ADMIN\fP ケーパビリティが必要である。 詳細な情報は \fBpid_namespaces\fP(7) を参照。
 112 .TP
 113 \fBCLONE_NEWUSER\fP (Linux 3.8 以降)
 114 このフラグは \fBclone\fP(2) \fBCLONE_NEWUSER\fP フラグと同じ効果を持つ。 ユーザー名前空間を共有せず、
 115 呼び出し元プロセスはすでに存在するどのプロセスとも共有されない新しいユーザー名前空間に移動される。 \fBCLONE_NEWUSER\fP フラグを指定して
 116 \fBclone\fP(2) で作成された子プロセスと同様に、 呼び出し元は新しい名前空間ですべてのケーパビリティを獲得する。
 117 .IP
 118 .\" commit e66eded8309ebf679d3d3c1f5820d1f2ca332c71
 119 .\" https://lwn.net/Articles/543273/
 120 \fBCLONE_NEWUSER\fP を使うには、呼び出し元プロセスがスレッド化されていないことが必要である。 \fBCLONE_NEWUSER\fP
 121 を指定すると、自動的に \fBCLONE_THREAD\fP が指定されたものとみなされる。 Linux 3.9 以降では、 \fBCLONE_NEWUSER\fP
 122 が指定された場合 \fBCLONE_FS\fP も指定されたとみなされる。 \fBCLONE_NEWUSER\fP を使うには、呼び出し元プロセスのユーザー ID
 123 とグループ ID が、 呼び出した時点で、 呼び出し元プロセスのユーザー名前空間のユーザー ID とグループ ID にマッピングされている必要がある。
 124
 125 ユーザー名前空間の詳細は \fBuser_namespaces\fP(7) を参照。
 126 .TP
 127 \fBCLONE_NEWUTS\fP (Linux 2.6.19 以降)
 128 このフラグは \fBclone\fP(2) \fBCLONE_NEWUTS\fP フラグと同じ効果を持つ。 UTS
 129 IPC 名前空間を共有せず、呼び出し元プロセスは他のプロセスとは共有しない
 130 固有の UTS IPC 名前空間のコピーを持つ。 このフラグを指定すると、
 131 \fBCLONE_FS\fP も暗黙のうちに指定される。\fBCLONE_NEWUTS\fP を使用するには
 132 \fBCAP_SYS_ADMIN\fP ケーパビリティが必要である。
 133 .TP
 134 \fBCLONE_SYSVSEM\fP (Linux 2.6.26 以降)
 135 .\" commit 9edff4ab1f8d82675277a04e359d0ed8bf14a7b7
 136 .\" CLONE_NEWNS If CLONE_SIGHAND is set and signals are also being shared
 137 .\" (i.e., current->signal->count > 1), force CLONE_THREAD.
 138 このフラグは \fBclone\fP(2) \fBCLONE_SYSVSEM\fP フラグの効果を逆転させる。 System\ V セマフォの調整値
 139 (\fIsemadj\fP) を共有せず、 呼び出し元プロセスは他のプロセスとは共有されない新しい空の \fIsemadj\fP リストを持つ。
 140 そのプロセスが、自分の現在の \fIsemadj\fP リストへの参照を持つ最後のプロセスであれば、 このリストの調整値は対応するセマフォに適用される
 141 (\fBsemop\fP(2) に説明がある通り)。
 142 .PP
 143 .\" As at 3.9, the following forced implications also apply,
 144 .\" although the relevant flags are not yet implemented.
 145 .\" If CLONE_THREAD is set force CLONE_VM.
 146 .\" If CLONE_VM is set, force CLONE_SIGHAND.
 147 .\"
 148 .\" See kernel/fork.c::check_unshare_flags()
 149 上記に加えて、 呼び出し元がシングルスレッドの場合 (すなわち別のプロセスやスレッドとアドレス空間を共有していない場合)、
 150 \fBCLONE_THREAD\fP, \fBCLONE_SIGHAND\fP, \fBCLONE_VM\fP を指定することができる。 この場合、
 151 これらのフラグは効果を持たない。 (\fBCLONE_THREAD\fP を指定すると自動的に \fBCLONE_VM\fP が指定されたとみなされ、
 152 \fBCLONE_VM\fP を指定すると自動的に \fBCLONE_SIGHAND\fP が指定されたとみなされる点に注意してほしい。)
 153 プロセスがマルチスレッドの場合、 これらのフラグを使用するとエラーとなる。
 154 .PP
 155 \fIflags\fP に 0 が指定された場合、 \fBunshare\fP()  は何も行わないので、
 156 呼び出し元プロセスの実行コンテキストは、何も変更されない。
 157 .SH 返り値
 158 成功した場合は 0 が返される。 失敗した場合は \-1 が返されて、 \fIerrno\fP にはエラーを示す値が設定される。
 159 .SH エラー
 160 .TP
 161 \fBEINVAL\fP
 162 \fIflags\fP に不正なビットが指定された。
 163 .TP
 164 \fBEINVAL\fP
 165 \fBCLONE_THREAD\fP, \fBCLONE_SIGHAND\fP, \fBCLONE_VM\fP が \fIflags\fP に指定されたが、
 166 呼び出したプロセスはマルチスレッドである。
 167 .TP
 168 \fBENOMEM\fP
 169 呼び出し元のコンテキストのうち共有を解除する必要がある部分をコピーするために、 十分なメモリーが確保できなかった。
 170 .TP
 171 \fBEPERM\fP
 172 呼び出し元プロセスはこの操作を行うのに必要な特権を持っていなかった。
 173 .TP
 174 \fBEPERM\fP
 175 \fBCLONE_NEWUSER\fP が \fIflags\fP に指定されたが、 呼び出し元の実効ユーザー ID もしくは実効グループ ID
 176 が親名前空間にマッピングがない (\fBuser_namespaces\fP(7) 参照)。
 177 .TP
 178 \fBEPERM\fP (Linux 3.9 以降)
 179 .\" commit 3151527ee007b73a0ebd296010f1c0454a919c7d
 180 .\" FIXME What is the rationale for this restriction?
 181 \fBCLONE_NEWUSER\fP が \fIflags\fP に指定され、 呼び出し元が chroot された環境にいる (すなわち、呼び出し元の root
 182 ディレクトリが呼び出し元が属するマウント名前空間の root ディレクトリに一致しない)。
 183 .TP
 184 \fBEUSERS\fP (Linux 3.11 以降)
 185 \fBCLONE_NEWUSER\fP が \fIflags\fP に指定されており、 この呼び出しによりネストされたユーザー名前空間数の上限を超えてしまう。
 186 \fBuser_namespaces\fP(7) を参照。
 187 .SH バージョン
 188 \fBunshare\fP()  システムコールは Linux カーネル 2.6.16 で追加された。
 189 .SH 準拠
 190 \fBunshare\fP()  システムコールは Linux 固有である。
 191 .SH 注意
 192 .\" FIXME all of the following needs to be reviewed for the current kernel
 193 .\" However, we can do unshare(CLONE_SIGHAND) if CLONE_SIGHAND
 194 .\" was not specified when doing clone(); i.e., unsharing
 195 .\" signal handlers is permitted if we are not actually
 196 .\" sharing signal handlers.   mtk
 197 .\" However, we can do unshare(CLONE_VM) if CLONE_VM
 198 .\" was not specified when doing clone(); i.e., unsharing
 199 .\" virtual memory is permitted if we are not actually
 200 .\" sharing virtual memory.   mtk
 201 .\"
 202 .\"9) Future Work
 203 .\"--------------
 204 .\"The current implementation of unshare does not allow unsharing of
 205 .\"signals and signal handlers. Signals are complex to begin with and
 206 .\"to unshare signals and/or signal handlers of a currently running
 207 .\"process is even more complex. If in the future there is a specific
 208 .\"need to allow unsharing of signals and/or signal handlers, it can
 209 .\"be incrementally added to unshare without affecting legacy
 210 .\"applications using unshare.
 211 .\"
 212 \fBclone\fP(2)  で新しいプロセスを生成したときに共有される全てのプロセス属性を、 \fBunshare\fP()
 213 によって共有の解除ができるわけではない。 特に、カーネル 3.8 時点では、 \fBunshare\fP()  に \fBCLONE_SIGHAND\fP,
 214 \fBCLONE_THREAD\fP, \fBCLONE_VM\fP の効果を取り消すためのフラグが実装されていない。
 215 これらの機能は、必要であれば将来追加されるかもしれない。
 216 .SH 例
 217 以下のプログラムは \fBunshare\fP(1) コマンドの簡単な実装である。 このコマンドは、1 つ以上の名前空間の unshare を行ってから、
 218 コマンドライン引き数で指定されたコマンドを実行する。 以下はこのプログラムの使用例である。 新しいマウント名前空間でシェルを実行し、
 219 元のシェルと新しいシェルが別のマウント名前空間にいることを確認している。
 220 .in +4n
 221 .nf
 222
 223 $ \fBreadlink /proc/$$/ns/mnt\fP
 224 mnt:[4026531840]
 225 $ \fBsudo ./unshare \-m /bin/bash\fP
 226 [sudo] password for cecilia:
 227 # \fBreadlink /proc/$$/ns/mnt\fP
 228 mnt:[4026532325]
 229 .fi
 230 .in
 231
 232 2 つの \fBreadlink\fP(1) コマンドの出力が違うことから、 2 つのシェルは異なるマウント名前空間にいることが分かる。
 233 .SS プログラムのソース
 234 \&
 235 .nf
 236 /* unshare.c
 237
 238    A simple implementation of the unshare(1) command: unshare
 239    namespaces and execute a command.
 240 */
 241 #define _GNU_SOURCE
 242 #include <sched.h>
 243 #include <unistd.h>
 244 #include <stdlib.h>
 245 #include <stdio.h>
 246
 247 /* A simple error\-handling function: print an error message based
 248    on the value in \(aqerrno\(aq and terminate the calling process */
 249
 250 #define errExit(msg)    do { perror(msg); exit(EXIT_FAILURE); \e
 251                         } while (0)
 252
 253 static void
 254 usage(char *pname)
 255 {
 256     fprintf(stderr, "Usage: %s [options] program [arg...]\en", pname);
 257     fprintf(stderr, "Options can be:\en");
 258     fprintf(stderr, "    \-i   unshare IPC namespace\en");
 259     fprintf(stderr, "    \-m   unshare mount namespace\en");
 260     fprintf(stderr, "    \-n   unshare network namespace\en");
 261     fprintf(stderr, "    \-p   unshare PID namespace\en");
 262     fprintf(stderr, "    \-u   unshare UTS namespace\en");
 263     fprintf(stderr, "    \-U   unshare user namespace\en");
 264     exit(EXIT_FAILURE);
 265 }
 266
 267 int
 268 main(int argc, char *argv[])
 269 {
 270     int flags, opt;
 271
 272     flags = 0;
 273
 274     while ((opt = getopt(argc, argv, "imnpuU")) != \-1) {
 275         switch (opt) {
 276         case \(aqi\(aq: flags |= CLONE_NEWIPC;        break;
 277         case \(aqm\(aq: flags |= CLONE_NEWNS;         break;
 278         case \(aqn\(aq: flags |= CLONE_NEWNET;        break;
 279         case \(aqp\(aq: flags |= CLONE_NEWPID;        break;
 280         case \(aqu\(aq: flags |= CLONE_NEWUTS;        break;
 281         case \(aqU\(aq: flags |= CLONE_NEWUSER;       break;
 282         default:  usage(argv[0]);
 283         }
 284     }
 285
 286     if (optind >= argc)
 287         usage(argv[0]);
 288
 289     if (unshare(flags) == \-1)
 290         errExit("unshare");
 291
 292     execvp(argv[optind], &argv[optind]);
 293     errExit("execvp");
 294 }
 295 .fi
 296 .SH 関連項目
 297 \fBunshare\fP(1), \fBclone\fP(2), \fBfork\fP(2), \fBkcmp\fP(2), \fBsetns\fP(2),
 298 \fBvfork\fP(2), \fBnamespaces\fP(7)
 299
 300 Linux カーネルソース内の \fIDocumentation/unshare.txt\fP
 301 .SH この文書について
 302 この man ページは Linux \fIman\-pages\fP プロジェクトのリリース 3.79 の一部
 303 である。プロジェクトの説明とバグ報告に関する情報は
 304 http://www.kernel.org/doc/man\-pages/ に書かれている。