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 |
Jorge Lucangeli Obes | 1365061 | 2016-09-02 11:27:29 -0400 | [diff] [blame] | 6 | [\fIOPTION\fR]... <\fIPROGRAM\fR> [\fIargs\fR]... |
Elly Jones | cd7a904 | 2011-07-22 13:56:51 -0400 | [diff] [blame] | 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 |
Mike Frysinger | 0fe4e4f | 2017-06-20 14:01:09 -0400 | [diff] [blame] | 13 | and architectures that support the \fBPR_ALT_SYSCALL\fR option of \fBprctl\fR(2). |
Andrew Bresticker | eac2894 | 2015-11-11 16:04:46 -0800 | [diff] [blame] | 14 | .TP |
Mike Frysinger | 8f0665b | 2018-01-17 14:26:09 -0500 | [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. |
Mike Frysinger | eaab420 | 2017-08-14 14:57:21 -0400 | [diff] [blame] | 17 | The \fIsrc\fR path must be an absolute path. |
Mike Frysinger | 8f0665b | 2018-01-17 14:26:09 -0500 | [diff] [blame] | 18 | If \fIdest\fR is not specified, it will default to \fIsrc\fR. |
Mike Frysinger | eaab420 | 2017-08-14 14:57:21 -0400 | [diff] [blame] | 19 | If the destination does not exist, it will be created as a file or directory |
| 20 | based on the \fIsrc\fR type. |
Elly Jones | 51a5b6c | 2011-10-12 19:09:26 -0400 | [diff] [blame] | 21 | .TP |
Elly Jones | cd7a904 | 2011-07-22 13:56:51 -0400 | [diff] [blame] | 22 | \fB-c <caps>\fR |
| 23 | Restrict capabilities to \fIcaps\fR. When used in conjunction with \fB-u\fR and |
| 24 | \fB-g\fR, this allows a program to have access to only certain parts of root's |
| 25 | default privileges while running as another user and group ID altogether. Note |
| 26 | that these capabilities are not inherited by subprocesses of the process given |
| 27 | capabilities unless those subprocesses have POSIX file capabilities. See |
| 28 | \fBcapabilities\fR(7). |
| 29 | .TP |
Dylan Reid | 6cae0b2 | 2015-11-18 18:47:49 -0800 | [diff] [blame] | 30 | \fB-C <dir>\fR |
Mike Frysinger | 0fe4e4f | 2017-06-20 14:01:09 -0400 | [diff] [blame] | 31 | Change root (using \fBchroot\fR(2)) to \fIdir\fR. |
Dylan Reid | 6cae0b2 | 2015-11-18 18:47:49 -0800 | [diff] [blame] | 32 | .TP |
Mike Frysinger | 33ffef3 | 2017-01-13 19:53:19 -0500 | [diff] [blame] | 33 | \fB-d\fR, \fB--mount-dev\fR |
| 34 | Create a new /dev mount with a minimal set of nodes. Implies \fB-v\fR. |
| 35 | Additional nodes can be bound with the \fB-b\fR or \fB-k\fR options. |
| 36 | The initial set of nodes are: full null tty urandom zero. |
| 37 | Symlinks are also created for: fd ptmx stderr stdin stdout. |
| 38 | .TP |
Dylan Reid | 6cae0b2 | 2015-11-18 18:47:49 -0800 | [diff] [blame] | 39 | \fB-e[file]\fR |
Jorge Lucangeli Obes | a521bee | 2016-03-03 13:47:57 -0800 | [diff] [blame] | 40 | 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] | 41 | network namespace specified by \fIfile\fR which is typically of the form |
| 42 | /proc/<pid>/ns/net. |
| 43 | .TP |
| 44 | \fB-f <file>\fR |
| 45 | Write the pid of the jailed process to \fIfile\fR. |
| 46 | .TP |
Lutz Justen | 13807cb | 2017-01-03 17:11:55 +0100 | [diff] [blame] | 47 | \fB-g <group>\fR |
| 48 | Change groups to \fIgroup\fR, which may be either a group name or a numeric |
| 49 | group ID. |
| 50 | .TP |
Elly Jones | cd7a904 | 2011-07-22 13:56:51 -0400 | [diff] [blame] | 51 | \fB-G\fR |
| 52 | Inherit all the supplementary groups of the user specified with \fB-u\fR. It |
| 53 | is an error to use this option without having specified a \fBuser name\fR to |
| 54 | \fB-u\fR. |
| 55 | .TP |
Elly Jones | cd7a904 | 2011-07-22 13:56:51 -0400 | [diff] [blame] | 56 | \fB-h\fR |
| 57 | Print a help message. |
| 58 | .TP |
Will Drewry | 32ac9f5 | 2011-08-18 21:36:27 -0500 | [diff] [blame] | 59 | \fB-H\fR |
| 60 | Print a help message detailing supported system call names for seccomp_filter. |
| 61 | (Other direct numbers may be specified if minijail0 is not in sync with the |
Mike Frysinger | 4a5fed6 | 2018-01-17 16:04:50 -0500 | [diff] [blame] | 62 | host kernel or something like 32/64-bit compatibility issues exist.) |
Will Drewry | 32ac9f5 | 2011-08-18 21:36:27 -0500 | [diff] [blame] | 63 | .TP |
Brian Norris | 3b5841b | 2016-03-16 16:43:49 -0700 | [diff] [blame] | 64 | \fB-I\fR |
| 65 | Run \fIprogram\fR as init (pid 1) inside a new pid namespace (implies \fB-p\fR). |
| 66 | .TP |
Mike Frysinger | fea05c6 | 2018-01-17 16:56:48 -0500 | [diff] [blame] | 67 | \fB-k <src>,<dest>,<type>[,<flags>[,<data>]]\fR |
Mike Frysinger | 4f3e09f | 2018-01-24 18:01:16 -0500 | [diff] [blame] | 68 | Mount \fIsrc\fR, a \fItype\fR filesystem, at \fIdest\fR. If a chroot or pivot |
| 69 | root is active, \fIdest\fR will automatically be placed below that path. |
| 70 | |
| 71 | The \fIflags\fR field is optional and is a hex constant. These represent the |
| 72 | \fIMS_XXX\fR settings (see \fBmount\fR(2) for details). Their values can be |
| 73 | looked up in the sys/mount.h header file. \fI0xe\fR is a common value here |
| 74 | (a writable mount with nodev/nosuid/noexec bits set), and it is strongly |
| 75 | recommended that all mounts have these three bits set whenever possible. |
| 76 | |
| 77 | The \fIdata\fR field is optional and is a comma delimited string (see |
| 78 | \fBmount\fR(2) for details). It is passed directly to the kernel, so all |
| 79 | fields here are filesystem specific. |
| 80 | |
Mike Frysinger | eaab420 | 2017-08-14 14:57:21 -0400 | [diff] [blame] | 81 | If the mount is not a pseudo filesystem (e.g. proc or sysfs), \fIsrc\fR path |
| 82 | must be an absolute path (e.g. \fI/dev/sda1\fR and not \fIsda1\fR). |
Mike Frysinger | 4f3e09f | 2018-01-24 18:01:16 -0500 | [diff] [blame] | 83 | |
Mike Frysinger | eaab420 | 2017-08-14 14:57:21 -0400 | [diff] [blame] | 84 | If the destination does not exist, it will be created as a directory. |
Jorge Lucangeli Obes | a521bee | 2016-03-03 13:47:57 -0800 | [diff] [blame] | 85 | .TP |
| 86 | \fB-K\fR |
| 87 | Don't mark all existing mounts as MS_PRIVATE. |
| 88 | This option is \fBdangerous\fR as it negates most of the functionality of \fB-v\fR. |
| 89 | You very likely don't need this. |
| 90 | .TP |
Dylan Reid | f794247 | 2015-11-18 17:55:26 -0800 | [diff] [blame] | 91 | \fB-l\fR |
| 92 | Run inside a new IPC namespace. This option makes the program's System V IPC |
| 93 | namespace independent. |
| 94 | .TP |
Brian Norris | 3b5841b | 2016-03-16 16:43:49 -0700 | [diff] [blame] | 95 | \fB-L\fR |
| 96 | Report blocked syscalls to syslog when using seccomp filter. This option will |
| 97 | force certain syscalls to be allowed in order to achieve this, depending on the |
| 98 | system. |
| 99 | .TP |
Jorge Lucangeli Obes | 959f656 | 2017-02-07 11:03:46 -0500 | [diff] [blame] | 100 | \fB-m[<uid> <loweruid> <count>[,<uid> <loweruid> <count>]]\fR |
Jorge Lucangeli Obes | a521bee | 2016-03-03 13:47:57 -0800 | [diff] [blame] | 101 | Set the uid mapping of a user namespace (implies \fB-pU\fR). Same arguments as |
Mike Frysinger | 0fe4e4f | 2017-06-20 14:01:09 -0400 | [diff] [blame] | 102 | \fBnewuidmap\fR(1). Multiple mappings should be separated by ','. With no mapping, |
Jorge Lucangeli Obes | 959f656 | 2017-02-07 11:03:46 -0500 | [diff] [blame] | 103 | map the current uid to root inside the user namespace. |
Dylan Reid | 6cae0b2 | 2015-11-18 18:47:49 -0800 | [diff] [blame] | 104 | .TP |
Jorge Lucangeli Obes | 959f656 | 2017-02-07 11:03:46 -0500 | [diff] [blame] | 105 | \fB-M[<uid> <loweruid> <count>[,<uid> <loweruid> <count>]]\fR |
Jorge Lucangeli Obes | a521bee | 2016-03-03 13:47:57 -0800 | [diff] [blame] | 106 | Set the gid mapping of a user namespace (implies \fB-pU\fR). Same arguments as |
Mike Frysinger | 0fe4e4f | 2017-06-20 14:01:09 -0400 | [diff] [blame] | 107 | \fBnewgidmap\fR(1). Multiple mappings should be separated by ','. With no mapping, |
Jorge Lucangeli Obes | 959f656 | 2017-02-07 11:03:46 -0500 | [diff] [blame] | 108 | map the current gid to root inside the user namespace. |
Dylan Reid | 6cae0b2 | 2015-11-18 18:47:49 -0800 | [diff] [blame] | 109 | .TP |
Brian Norris | 3b5841b | 2016-03-16 16:43:49 -0700 | [diff] [blame] | 110 | \fB-n\fR |
Mike Frysinger | 0fe4e4f | 2017-06-20 14:01:09 -0400 | [diff] [blame] | 111 | Set the process's \fIno_new_privs\fR bit. See \fBprctl\fR(2) and the kernel |
Brian Norris | 3b5841b | 2016-03-16 16:43:49 -0700 | [diff] [blame] | 112 | source file \fIDocumentation/prctl/no_new_privs.txt\fR for more info. |
| 113 | .TP |
Dylan Reid | 87e5851 | 2016-07-11 14:35:12 -0700 | [diff] [blame] | 114 | \fB-N\fR |
| 115 | Run inside a new cgroup namespace. This option runs the program with a cgroup |
| 116 | view showing the program's cgroup as the root. This is only available on v4.6+ |
| 117 | of the Linux kernel. |
| 118 | .TP |
Elly Jones | cd7a904 | 2011-07-22 13:56:51 -0400 | [diff] [blame] | 119 | \fB-p\fR |
| 120 | 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] | 121 | program to see or affect processes that are not its descendants. This implies |
| 122 | \fB-v\fR and \fB-r\fR, since otherwise the process can see outside its namespace |
| 123 | by inspecting /proc. |
Elly Jones | cd7a904 | 2011-07-22 13:56:51 -0400 | [diff] [blame] | 124 | .TP |
Dylan Reid | 6cae0b2 | 2015-11-18 18:47:49 -0800 | [diff] [blame] | 125 | \fB-P <dir>\fR |
| 126 | Set \fIdir\fR as the root fs using \fBpivot_root\fR. Implies \fB-v\fR, not |
| 127 | compatible with \fB-C\fR. |
| 128 | .TP |
Elly Jones | cd7a904 | 2011-07-22 13:56:51 -0400 | [diff] [blame] | 129 | \fB-r\fR |
Dylan Reid | 6cae0b2 | 2015-11-18 18:47:49 -0800 | [diff] [blame] | 130 | Remount /proc readonly. This implies \fB-v\fR. Remounting /proc readonly means |
| 131 | that even if the process has write access to a system config knob in /proc |
| 132 | (e.g., in /sys/kernel), it cannot change the value. |
Elly Jones | cd7a904 | 2011-07-22 13:56:51 -0400 | [diff] [blame] | 133 | .TP |
Luis Hector Chavez | 7058a2d | 2018-01-29 08:41:34 -0800 | [diff] [blame] | 134 | \fB-R <rlim_type>,<rlim_cur>,<rlim_max>\fR |
| 135 | Set an rlimit value, see \fBgetrlimit\fR(2) for allowed values. The string |
| 136 | \fBunlimited\fR can be used for \fBrlim_cur\fR and \fBrlim_max\fR, which will |
| 137 | translate to \fBRLIM_INFINITY\fR. |
Dylan Reid | 0f72ef4 | 2017-06-06 15:42:49 -0700 | [diff] [blame] | 138 | .TP |
Elly Jones | cd7a904 | 2011-07-22 13:56:51 -0400 | [diff] [blame] | 139 | \fB-s\fR |
Mike Frysinger | 0fe4e4f | 2017-06-20 14:01:09 -0400 | [diff] [blame] | 140 | Enable \fBseccomp\fR(2) in mode 1, which restricts the child process to a very |
| 141 | small set of system calls. |
Mike Frysinger | e61fd66 | 2017-06-20 14:07:41 -0400 | [diff] [blame] | 142 | You most likely do not want to use this with the seccomp filter mode (\fB-S\fR) |
| 143 | as they are completely different (even though they have similar names). |
Will Drewry | 32ac9f5 | 2011-08-18 21:36:27 -0500 | [diff] [blame] | 144 | .TP |
| 145 | \fB-S <arch-specific seccomp_filter policy file>\fR |
Mike Frysinger | 0fe4e4f | 2017-06-20 14:01:09 -0400 | [diff] [blame] | 146 | Enable \fBseccomp\fR(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] | 147 | 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] | 148 | names based on the architecture or mode. (uname -m is your friend.) |
Elly Jones | cd7a904 | 2011-07-22 13:56:51 -0400 | [diff] [blame] | 149 | .TP |
Jorge Lucangeli Obes | 959f656 | 2017-02-07 11:03:46 -0500 | [diff] [blame] | 150 | \fB-t[size]\fR |
Mike Frysinger | ec7def2 | 2017-01-13 18:44:45 -0500 | [diff] [blame] | 151 | Mounts a tmpfs filesystem on /tmp. /tmp must exist already (e.g. in the chroot). |
Martin Pelikán | ab9eb44 | 2017-01-25 11:53:58 +1100 | [diff] [blame] | 152 | The filesystem has a default size of "64M", overridden with an optional |
| 153 | argument. It has standard /tmp permissions (1777), and is mounted |
| 154 | nodev/noexec/nosuid. Implies \fB-v\fR. |
Jorge Lucangeli Obes | a521bee | 2016-03-03 13:47:57 -0800 | [diff] [blame] | 155 | .TP |
Matthew Dempsky | 2ed0912 | 2016-02-11 09:43:37 -0800 | [diff] [blame] | 156 | \fB-T <type>\fR |
Graziano Misuraca | 58602a8 | 2017-08-28 17:33:15 -0700 | [diff] [blame] | 157 | Assume binary's ELF linkage type is \fItype\fR, which must be either 'static' |
| 158 | or 'dynamic'. Either setting will prevent minijail0 from manually parsing the |
| 159 | ELF header to determine the type. Type 'static' can be used to avoid preload |
| 160 | hooking, and will force minijail0 to instead set everything up before the |
| 161 | program is executed. Type 'dynamic' will force minijail0 to preload |
| 162 | \fIlibminijailpreload.so\fR to setup hooks, but will fail on actually |
| 163 | statically-linked binaries. |
Matthew Dempsky | 2ed0912 | 2016-02-11 09:43:37 -0800 | [diff] [blame] | 164 | .TP |
Elly Jones | cd7a904 | 2011-07-22 13:56:51 -0400 | [diff] [blame] | 165 | \fB-u <user>\fR |
| 166 | Change users to \fIuser\fR, which may be either a user name or a numeric user |
| 167 | ID. |
| 168 | .TP |
Brian Norris | 3b5841b | 2016-03-16 16:43:49 -0700 | [diff] [blame] | 169 | \fB-U\fR |
| 170 | Enter a new user namespace (implies \fB-p\fR). |
| 171 | .TP |
Elly Jones | cd7a904 | 2011-07-22 13:56:51 -0400 | [diff] [blame] | 172 | \fB-v\fR |
| 173 | Run inside a new VFS namespace. This option makes the program's mountpoints |
| 174 | independent of the rest of the system's. |
Dylan Reid | 6cae0b2 | 2015-11-18 18:47:49 -0800 | [diff] [blame] | 175 | .TP |
| 176 | \fB-V <file>\fR |
| 177 | Enter the VFS namespace specified by \fIfile\fR. |
Jorge Lucangeli Obes | 1365061 | 2016-09-02 11:27:29 -0400 | [diff] [blame] | 178 | .TP |
Chirantan Ekbote | 866bb3a | 2017-02-07 12:26:42 -0800 | [diff] [blame] | 179 | \fB-w\fR |
| 180 | Create and join a new anonymous session keyring. See \fBkeyrings\fR(7) for more |
| 181 | details. |
| 182 | .TP |
Lutz Justen | 13807cb | 2017-01-03 17:11:55 +0100 | [diff] [blame] | 183 | \fB-y\fR |
| 184 | Keep the current user's supplementary groups. |
| 185 | .TP |
Jorge Lucangeli Obes | 1365061 | 2016-09-02 11:27:29 -0400 | [diff] [blame] | 186 | \fB-Y\fR |
| 187 | Synchronize seccomp filters across thread group. |
Mike Frysinger | b9a7b16 | 2017-05-30 15:25:49 -0400 | [diff] [blame] | 188 | .TP |
| 189 | \fB--uts[=hostname]\fR |
| 190 | Create a new UTS/hostname namespace, and optionally set the hostname in the new |
| 191 | namespace to \fIhostname\fR. |
Luis Hector Chavez | 114a930 | 2017-09-05 20:36:58 -0700 | [diff] [blame] | 192 | .TP |
| 193 | \fB--logging=<system>\fR |
| 194 | Use \fIsystem\fR as the logging system. \fIsystem\fR must be one of |
| 195 | \fBsyslog\fR (the default) or \fBstderr\fR. |
Luis Hector Chavez | d45fc42 | 2017-10-25 15:11:53 -0700 | [diff] [blame] | 196 | .TP |
| 197 | \fB--profile <profile>\fR |
| 198 | Choose from one of the available sandboxing profiles, which are simple way to |
| 199 | get a standardized environment. See the |
| 200 | .BR "SANDBOXING PROFILES" |
| 201 | section below for the full list of supported values for \fIprofile\fR. |
| 202 | .SH SANDBOXING PROFILES |
| 203 | The following sandboxing profiles are supported: |
| 204 | .TP |
| 205 | \fBminimalistic-mountns\fR |
| 206 | Set up a minimalistic mount namespace. Equivalent to \fB-v -P /var/empty |
| 207 | -b /,/ -b /proc,/proc -t -r --mount-dev\fR. |
Elly Jones | cd7a904 | 2011-07-22 13:56:51 -0400 | [diff] [blame] | 208 | .SH IMPLEMENTATION |
| 209 | This program is broken up into two parts: \fBminijail0\fR (the frontend) and a helper |
| 210 | library called \fBlibminijailpreload\fR. Some jailings can only be achieved from |
| 211 | the process to which they will actually apply - specifically capability use |
| 212 | (since capabilities are not inherited to an exec'd process unless the exec'd |
| 213 | 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] | 214 | seccomp'd), and ptrace-disable (which is always cleared on exec()). |
Elly Jones | cd7a904 | 2011-07-22 13:56:51 -0400 | [diff] [blame] | 215 | |
| 216 | To this end, \fBlibminijailpreload\fR is forcibly loaded into all |
| 217 | dynamically-linked target programs if any of these restrictions are in effect; |
| 218 | we pass the specific restrictions in an environment variable which the preloaded |
| 219 | library looks for. The forcibly-loaded library then applies the restrictions |
| 220 | to the newly-loaded program. |
Jorge Lucangeli Obes | a521bee | 2016-03-03 13:47:57 -0800 | [diff] [blame] | 221 | |
Elly Jones | cd7a904 | 2011-07-22 13:56:51 -0400 | [diff] [blame] | 222 | .SH AUTHOR |
Jorge Lucangeli Obes | a521bee | 2016-03-03 13:47:57 -0800 | [diff] [blame] | 223 | The Chromium OS Authors <chromiumos-dev@chromium.org> |
Elly Jones | cd7a904 | 2011-07-22 13:56:51 -0400 | [diff] [blame] | 224 | .SH COPYRIGHT |
| 225 | Copyright \(co 2011 The Chromium OS Authors |
| 226 | License BSD-like. |
| 227 | .SH "SEE ALSO" |
Mike Frysinger | 0fe4e4f | 2017-06-20 14:01:09 -0400 | [diff] [blame] | 228 | \fBlibminijail.h\fR \fBminijail0\fR(5) |