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* [[email protected]]: Public user & developer mailing list. 48* [[email protected]]: Internal Google user mailing list. 49* [[email protected]]: 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[[email protected]]: https://groups.google.com/a/chromium.org/forum/#!forum/minijail 55[[email protected]]: https://groups.google.com/a/google.com/forum/#!forum/minijail-users 56[[email protected]]: 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## Talks and presentations 62 63The following talk serves as a good introduction to Minijail and how it can be used. 64 65[Video](https://drive.google.com/file/d/0BwPS_JpKyELWZTFBcTVsa1hhYjA/preview), 66[slides](https://docs.google.com/presentation/d/e/2PACX-1vRBqpin5xR9sng6lIBPjG0XQtu-uWWgr0ds-M3zW13XpDO-bTcMERLwoHUEB9078p1yqr9L-su9n5dk/pub). 67 68## Example usage 69 70The ChromiumOS project has a comprehensive 71[sandboxing](https://chromium.googlesource.com/chromiumos/docs/+/master/sandboxing.md) 72document that is largely based on Minijail. 73 74After you play with the simple examples below, you should check that out. 75 76### Change root to any user 77 78``` 79# id 80uid=0(root) gid=0(root) groups=0(root),128(pkcs11) 81# minijail0 -u jorgelo -g 5000 /usr/bin/id 82uid=72178(jorgelo) gid=5000(eng) groups=5000(eng) 83``` 84 85### Drop root while keeping some capabilities 86 87``` 88# minijail0 -u jorgelo -c 3000 -- /bin/cat /proc/self/status 89Name: cat 90... 91CapInh: 0000000000003000 92CapPrm: 0000000000003000 93CapEff: 0000000000003000 94CapBnd: 0000000000003000 95``` 96 97## Historical notes 98 99Q. "Why is it called minijail0?" 100 101A. It is minijail0 because it was a rewrite of an earlier program named 102minijail, which was considerably less mini, and in particular had a dependency 103on libchrome (the ChromeOS packaged version of Chromium's //base). We needed a 104new name to not collide with the deprecated one. 105 106We didn't want to call it minijail2 or something that would make people 107start using it before we were ready, and it was also concretely _less_ since it 108dropped libbase, etc. Technically, we needed to be able to fork/preload with 109minimal extra syscall noise which was too hard with libbase at the time (onexit 110handlers, etc that called syscalls we didn't want to allow). Also, Elly made a 111strong case that C would be the right choice for this for linking and ease of 112controlled surprise system call use. 113 114https://crrev.com/c/4585/ added the original implementation. 115 116Source: Conversations with original authors, ellyjones@ and wad@. 117