Jorge Lucangeli Obes | a521bee | 2016-03-03 13:47:57 -0800 | [diff] [blame] | 1 | .TH MINIJAIL0 "1" "March 2016" "Chromium OS" "User Commands" |
Elly Jones | cd7a904 | 2011-07-22 13:56:51 -0400 | [diff] [blame] | 2 | .SH NAME |
| 3 | minijail0 \- sandbox a process |
| 4 | .SH SYNOPSIS |
| 5 | .B minijail0 |
| 6 | [\fIOPTION\fR]... <\fIprogram\fR> [\fIargs\fR]... |
| 7 | .SH DESCRIPTION |
| 8 | .PP |
| 9 | Runs PROGRAM inside a sandbox. |
| 10 | .TP |
Andrew Bresticker | eac2894 | 2015-11-11 16:04:46 -0800 | [diff] [blame] | 11 | \fB-a <table>\fR |
Jorge Lucangeli Obes | a521bee | 2016-03-03 13:47:57 -0800 | [diff] [blame] | 12 | Run using the alternate syscall table named \fItable\fR. Only available on kernels |
Andrew Bresticker | eac2894 | 2015-11-11 16:04:46 -0800 | [diff] [blame] | 13 | and architectures that support the PR_ALT_SYSCALL option of prctl(2). |
| 14 | .TP |
Elly Jones | 51a5b6c | 2011-10-12 19:09:26 -0400 | [diff] [blame] | 15 | \fB-b <src>,<dest>[,<writeable>] |
Jorge Lucangeli Obes | a521bee | 2016-03-03 13:47:57 -0800 | [diff] [blame] | 16 | Bind-mount \fIsrc\fR into the chroot directory at \fIdest\fR, optionally writeable. |
Elly Jones | 51a5b6c | 2011-10-12 19:09:26 -0400 | [diff] [blame] | 17 | .TP |
Elly Jones | cd7a904 | 2011-07-22 13:56:51 -0400 | [diff] [blame] | 18 | \fB-c <caps>\fR |
| 19 | Restrict capabilities to \fIcaps\fR. When used in conjunction with \fB-u\fR and |
| 20 | \fB-g\fR, this allows a program to have access to only certain parts of root's |
| 21 | default privileges while running as another user and group ID altogether. Note |
| 22 | that these capabilities are not inherited by subprocesses of the process given |
| 23 | capabilities unless those subprocesses have POSIX file capabilities. See |
| 24 | \fBcapabilities\fR(7). |
| 25 | .TP |
Dylan Reid | 6cae0b2 | 2015-11-18 18:47:49 -0800 | [diff] [blame] | 26 | \fB-C <dir>\fR |
Jorge Lucangeli Obes | a521bee | 2016-03-03 13:47:57 -0800 | [diff] [blame] | 27 | Change root (using chroot(2)) to \fIdir\fR. |
Dylan Reid | 6cae0b2 | 2015-11-18 18:47:49 -0800 | [diff] [blame] | 28 | .TP |
| 29 | \fB-e[file]\fR |
Jorge Lucangeli Obes | a521bee | 2016-03-03 13:47:57 -0800 | [diff] [blame] | 30 | Enter a new network namespace, or if \fIfile\fR is specified, enter an existing |
Dylan Reid | 6cae0b2 | 2015-11-18 18:47:49 -0800 | [diff] [blame] | 31 | network namespace specified by \fIfile\fR which is typically of the form |
| 32 | /proc/<pid>/ns/net. |
| 33 | .TP |
| 34 | \fB-f <file>\fR |
| 35 | Write the pid of the jailed process to \fIfile\fR. |
| 36 | .TP |
Elly Jones | cd7a904 | 2011-07-22 13:56:51 -0400 | [diff] [blame] | 37 | \fB-G\fR |
| 38 | Inherit all the supplementary groups of the user specified with \fB-u\fR. It |
| 39 | is an error to use this option without having specified a \fBuser name\fR to |
| 40 | \fB-u\fR. |
| 41 | .TP |
| 42 | \fB-g <group>\fR |
| 43 | Change groups to \fIgroup\fR, which may be either a group name or a numeric |
| 44 | group ID. |
| 45 | .TP |
| 46 | \fB-h\fR |
| 47 | Print a help message. |
| 48 | .TP |
Will Drewry | 32ac9f5 | 2011-08-18 21:36:27 -0500 | [diff] [blame] | 49 | \fB-H\fR |
| 50 | Print a help message detailing supported system call names for seccomp_filter. |
| 51 | (Other direct numbers may be specified if minijail0 is not in sync with the |
| 52 | host kernel or something like 32/64-bit compatibility issues exist.) |
| 53 | .TP |
Brian Norris | 3b5841b | 2016-03-16 16:43:49 -0700 | [diff] [blame] | 54 | \fB-I\fR |
| 55 | Run \fIprogram\fR as init (pid 1) inside a new pid namespace (implies \fB-p\fR). |
| 56 | .TP |
Jorge Lucangeli Obes | a521bee | 2016-03-03 13:47:57 -0800 | [diff] [blame] | 57 | \fB-k <src>,<dest>,<type>[,<flags>]\fR |
| 58 | Mount \fIsrc\fR, a \fItype\fR filesystem, into the chroot directory at \fIdest\fR, with optional \fIflags\fR. |
| 59 | .TP |
| 60 | \fB-K\fR |
| 61 | Don't mark all existing mounts as MS_PRIVATE. |
| 62 | This option is \fBdangerous\fR as it negates most of the functionality of \fB-v\fR. |
| 63 | You very likely don't need this. |
| 64 | .TP |
Dylan Reid | f794247 | 2015-11-18 17:55:26 -0800 | [diff] [blame] | 65 | \fB-l\fR |
| 66 | Run inside a new IPC namespace. This option makes the program's System V IPC |
| 67 | namespace independent. |
| 68 | .TP |
Brian Norris | 3b5841b | 2016-03-16 16:43:49 -0700 | [diff] [blame] | 69 | \fB-L\fR |
| 70 | Report blocked syscalls to syslog when using seccomp filter. This option will |
| 71 | force certain syscalls to be allowed in order to achieve this, depending on the |
| 72 | system. |
| 73 | .TP |
Dylan Reid | 6cae0b2 | 2015-11-18 18:47:49 -0800 | [diff] [blame] | 74 | \fB-m "<uid> <loweruid> <count>[,<uid> <loweruid> <count>]"\fR |
Jorge Lucangeli Obes | a521bee | 2016-03-03 13:47:57 -0800 | [diff] [blame] | 75 | Set the uid mapping of a user namespace (implies \fB-pU\fR). Same arguments as |
| 76 | \fBnewuidmap(1)\fR. Multiple mappings should be separated by ','. |
Dylan Reid | 6cae0b2 | 2015-11-18 18:47:49 -0800 | [diff] [blame] | 77 | .TP |
| 78 | \fB-M "<uid> <loweruid> <count>[,<uid> <loweruid> <count>]"\fR |
Jorge Lucangeli Obes | a521bee | 2016-03-03 13:47:57 -0800 | [diff] [blame] | 79 | Set the gid mapping of a user namespace (implies \fB-pU\fR). Same arguments as |
| 80 | \fBnewgidmap(1)\fR. Multiple mappings should be separated by ','. |
Dylan Reid | 6cae0b2 | 2015-11-18 18:47:49 -0800 | [diff] [blame] | 81 | .TP |
Brian Norris | 3b5841b | 2016-03-16 16:43:49 -0700 | [diff] [blame] | 82 | \fB-n\fR |
| 83 | Set the process's \fIno_new_privs\fR bit. See \fBprctl(2)\fR and the kernel |
| 84 | source file \fIDocumentation/prctl/no_new_privs.txt\fR for more info. |
| 85 | .TP |
Elly Jones | cd7a904 | 2011-07-22 13:56:51 -0400 | [diff] [blame] | 86 | \fB-p\fR |
| 87 | Run inside a new PID namespace. This option will make it impossible for the |
Elly Jones | e58176c | 2012-01-23 11:46:17 -0500 | [diff] [blame] | 88 | program to see or affect processes that are not its descendants. This implies |
| 89 | \fB-v\fR and \fB-r\fR, since otherwise the process can see outside its namespace |
| 90 | by inspecting /proc. |
Elly Jones | cd7a904 | 2011-07-22 13:56:51 -0400 | [diff] [blame] | 91 | .TP |
Dylan Reid | 6cae0b2 | 2015-11-18 18:47:49 -0800 | [diff] [blame] | 92 | \fB-P <dir>\fR |
| 93 | Set \fIdir\fR as the root fs using \fBpivot_root\fR. Implies \fB-v\fR, not |
| 94 | compatible with \fB-C\fR. |
| 95 | .TP |
Elly Jones | cd7a904 | 2011-07-22 13:56:51 -0400 | [diff] [blame] | 96 | \fB-r\fR |
Dylan Reid | 6cae0b2 | 2015-11-18 18:47:49 -0800 | [diff] [blame] | 97 | Remount /proc readonly. This implies \fB-v\fR. Remounting /proc readonly means |
| 98 | that even if the process has write access to a system config knob in /proc |
| 99 | (e.g., in /sys/kernel), it cannot change the value. |
Elly Jones | cd7a904 | 2011-07-22 13:56:51 -0400 | [diff] [blame] | 100 | .TP |
| 101 | \fB-s\fR |
| 102 | Enable seccomp(2) in mode 1, which restricts the child process to a very small |
Will Drewry | 32ac9f5 | 2011-08-18 21:36:27 -0500 | [diff] [blame] | 103 | set of system calls. |
| 104 | .TP |
| 105 | \fB-S <arch-specific seccomp_filter policy file>\fR |
| 106 | Enable seccomp(2) in mode 13 which restricts the child process to a set of |
Jorge Lucangeli Obes | a521bee | 2016-03-03 13:47:57 -0800 | [diff] [blame] | 107 | system calls defined in the policy file. Note that system calls often change |
Will Drewry | 32ac9f5 | 2011-08-18 21:36:27 -0500 | [diff] [blame] | 108 | names based on the architecture or mode. (uname -m is your friend.) |
Elly Jones | cd7a904 | 2011-07-22 13:56:51 -0400 | [diff] [blame] | 109 | .TP |
Jorge Lucangeli Obes | a521bee | 2016-03-03 13:47:57 -0800 | [diff] [blame] | 110 | \fB-t\fR |
| 111 | Mounts a tmpfs filesystem on /tmp. /tmp must exist in the chroot. |
| 112 | This must be used with \fB-C\fR. The default filesystem has a max size of 128M |
| 113 | and has standard /tmp permissions (777). |
| 114 | .TP |
Matthew Dempsky | 2ed0912 | 2016-02-11 09:43:37 -0800 | [diff] [blame] | 115 | \fB-T <type>\fR |
| 116 | Assume program's ELF linkage type is \fItype\fR, |
| 117 | which should be either 'static' or 'dynamic'. |
| 118 | .TP |
Elly Jones | cd7a904 | 2011-07-22 13:56:51 -0400 | [diff] [blame] | 119 | \fB-u <user>\fR |
| 120 | Change users to \fIuser\fR, which may be either a user name or a numeric user |
| 121 | ID. |
| 122 | .TP |
Brian Norris | 3b5841b | 2016-03-16 16:43:49 -0700 | [diff] [blame] | 123 | \fB-U\fR |
| 124 | Enter a new user namespace (implies \fB-p\fR). |
| 125 | .TP |
Elly Jones | cd7a904 | 2011-07-22 13:56:51 -0400 | [diff] [blame] | 126 | \fB-v\fR |
| 127 | Run inside a new VFS namespace. This option makes the program's mountpoints |
| 128 | independent of the rest of the system's. |
Dylan Reid | 6cae0b2 | 2015-11-18 18:47:49 -0800 | [diff] [blame] | 129 | .TP |
| 130 | \fB-V <file>\fR |
| 131 | Enter the VFS namespace specified by \fIfile\fR. |
Elly Jones | cd7a904 | 2011-07-22 13:56:51 -0400 | [diff] [blame] | 132 | .SH IMPLEMENTATION |
| 133 | This program is broken up into two parts: \fBminijail0\fR (the frontend) and a helper |
| 134 | library called \fBlibminijailpreload\fR. Some jailings can only be achieved from |
| 135 | the process to which they will actually apply - specifically capability use |
| 136 | (since capabilities are not inherited to an exec'd process unless the exec'd |
| 137 | process has POSIX file capabilities), seccomp (since we can't exec() once we're |
Jorge Lucangeli Obes | a521bee | 2016-03-03 13:47:57 -0800 | [diff] [blame] | 138 | seccomp'd), and ptrace-disable (which is always cleared on exec()). |
Elly Jones | cd7a904 | 2011-07-22 13:56:51 -0400 | [diff] [blame] | 139 | |
| 140 | To this end, \fBlibminijailpreload\fR is forcibly loaded into all |
| 141 | dynamically-linked target programs if any of these restrictions are in effect; |
| 142 | we pass the specific restrictions in an environment variable which the preloaded |
| 143 | library looks for. The forcibly-loaded library then applies the restrictions |
| 144 | to the newly-loaded program. |
Jorge Lucangeli Obes | a521bee | 2016-03-03 13:47:57 -0800 | [diff] [blame] | 145 | |
Elly Jones | cd7a904 | 2011-07-22 13:56:51 -0400 | [diff] [blame] | 146 | .SH AUTHOR |
Jorge Lucangeli Obes | a521bee | 2016-03-03 13:47:57 -0800 | [diff] [blame] | 147 | The Chromium OS Authors <chromiumos-dev@chromium.org> |
Elly Jones | cd7a904 | 2011-07-22 13:56:51 -0400 | [diff] [blame] | 148 | .SH COPYRIGHT |
| 149 | Copyright \(co 2011 The Chromium OS Authors |
| 150 | License BSD-like. |
| 151 | .SH "SEE ALSO" |
Will Drewry | 32ac9f5 | 2011-08-18 21:36:27 -0500 | [diff] [blame] | 152 | \fBlibminijail.h\fR \fBminijail0(5)\fR |