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