• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1# Minijail
2
3The Minijail homepage is
4https://google.github.io/minijail/.
5
6The main source repo is
7https://chromium.googlesource.com/chromiumos/platform/minijail.
8
9There might be other copies floating around, but this is the official one!
10
11[TOC]
12
13## What is it?
14
15Minijail is a sandboxing and containment tool used in ChromeOS and Android.
16It provides an executable that can be used to launch and sandbox other programs,
17and a library that can be used by code to sandbox itself.
18
19## Getting the code
20
21You're one `git clone` away from happiness.
22
23```
24$ git clone https://chromium.googlesource.com/chromiumos/platform/minijail
25$ cd minijail
26```
27
28Releases are tagged as `linux-vXX`:
29https://chromium.googlesource.com/chromiumos/platform/minijail/+refs
30
31## Building
32
33See the [HACKING.md](./HACKING.md) document for more details.
34
35## Release process
36
37See the [RELEASE.md](./RELEASE.md) document for more details.
38
39## Additional tools
40
41See the [tools/README.md](./tools/README.md) document for more details.
42
43## Contact
44
45We've got a couple of contact points.
46
47* [minijail@chromium.org]: Public user & developer mailing list.
48* [minijail-users@google.com]: Internal Google user mailing list.
49* [minijail-dev@google.com]: Internal Google developer mailing list.
50* [crbug.com/list]: Existing bug reports & feature requests.
51* [crbug.com/new]: File new bug reports & feature requests.
52* [Chromium Gerrit]: Code reviews.
53
54[minijail@chromium.org]: https://groups.google.com/a/chromium.org/forum/#!forum/minijail
55[minijail-users@google.com]: https://groups.google.com/a/google.com/forum/#!forum/minijail-users
56[minijail-dev@google.com]: https://groups.google.com/a/google.com/forum/#!forum/minijail-dev
57[crbug.com/list]: https://crbug.com/?q=component:OS>Systems>Minijail
58[crbug.com/new]: https://bugs.chromium.org/p/chromium/issues/entry?components=OS>Systems>Minijail
59[Chromium Gerrit]: https://chromium-review.googlesource.com/q/project:chromiumos/platform/minijail
60
61## GitHub Pages homepage
62
63The https://google.github.io/minijail/ homepage is maintained in the `gh-pages`
64branch, not in the `main` branch.
65Changes to it can be sent via Gerrit, but requires a little extra work.
66
67```shell
68# Make sure you have all the branches, and not only the "main" one.
69$ git fetch
70
71# Create a new local branch tracking the remote "gh-pages".
72# Git should automatically detect the remote and track it for you.
73$ git checkout gh-pages
74# If git can't auto-detect the remote, try one of these.
75$ git checkout -b gh-pages origin/gh-pages
76$ git checkout -b gh-pages cros/gh-pages
77
78# Make your changes like normal, then push them to Gerrit for review.
79# Here's a couple of different ways to post changes; you only need one!
80$ repo upload -D gh-pages
81$ git push origin HEAD:refs/for/gh-pages
82$ git push cros HEAD:refs/for/gh-pages
83
84# Now review your changes via Gerrit like normal.
85```
86
87Once a change merges into the `gh-pages` branch, there is no additional work for
88you other than waiting -- GitHub periodically syncs with our host, and then it
89will automatically regenerate the homepage when the `gh-pages` branch updates.
90
91## Talks and presentations
92
93The following talk serves as a good introduction to Minijail and how it can be used.
94
95[Video](https://drive.google.com/file/d/0BwPS_JpKyELWZTFBcTVsa1hhYjA/preview),
96[slides](https://docs.google.com/presentation/d/e/2PACX-1vRBqpin5xR9sng6lIBPjG0XQtu-uWWgr0ds-M3zW13XpDO-bTcMERLwoHUEB9078p1yqr9L-su9n5dk/pub).
97
98## Example usage
99
100The ChromiumOS project has a comprehensive
101[sandboxing](https://www.chromium.org/chromium-os/developer-library/guides/development/sandboxing)
102document that is largely based on Minijail.
103
104After you play with the simple examples below, you should check that out.
105
106### Change root to any user
107
108```
109# id
110uid=0(root) gid=0(root) groups=0(root),128(pkcs11)
111# minijail0 -u jorgelo -g 5000 /usr/bin/id
112uid=72178(jorgelo) gid=5000(eng) groups=5000(eng)
113```
114
115### Drop root while keeping some capabilities
116
117```
118# minijail0 -u jorgelo -c 3000 -- /bin/cat /proc/self/status
119Name: cat
120...
121CapInh: 0000000000003000
122CapPrm: 0000000000003000
123CapEff: 0000000000003000
124CapBnd: 0000000000003000
125```
126
127## Historical notes
128
129Q. "Why is it called minijail0?"
130
131A. It is minijail0 because it was a rewrite of an earlier program named
132minijail, which was considerably less mini, and in particular had a dependency
133on libchrome (the ChromeOS packaged version of Chromium's //base).  We needed a
134new name to not collide with the deprecated one.
135
136We didn't want to call it minijail2 or something that would make people
137start using it before we were ready, and it was also concretely _less_ since it
138dropped libbase, etc.  Technically, we needed to be able to fork/preload with
139minimal extra syscall noise which was too hard with libbase at the time (onexit
140handlers, etc that called syscalls we didn't want to allow).  Also, Elly made a
141strong case that C would be the right choice for this for linking and ease of
142controlled surprise system call use.
143
144https://crrev.com/c/4585/ added the original implementation.
145
146Source: Conversations with original authors, ellyjones@ and wad@.
147