README 5 KB
Newer Older
Colin Walters's avatar
Colin Walters committed
1
2
3
4
5
6
7
8
9
10
11
12
13
THIS PROJECT IS REPLACED BY BUBBLEWRAP
--------------------------------------

Please see:
https://github.com/projectatomic/bubblewrap

THIS PROJECT IS REPLACED BY BUBBLEWRAP
--------------------------------------


Historical README follows:


Colin Walters's avatar
Colin Walters committed
14
15
16
17
18
19
20
Summary
-------

This tool allows regular (non-root) users to call chroot(2), create
Linux bind mounts, and use some Linux container features.  It's
primarily intended for use by build systems.

Colin Walters's avatar
Colin Walters committed
21
22
23
24
25
26
Contributing
------------

Currently, linux-user-chroot reuses
the https://mail.gnome.org/mailman/listinfo/ostree-list
mailing list.
Colin Walters's avatar
Colin Walters committed
27

Colin Walters's avatar
Colin Walters committed
28
Please send patches there.
Colin Walters's avatar
Colin Walters committed
29

Colin Walters's avatar
Colin Walters committed
30
31
32
Why is this useful?
-------------------

Colin Walters's avatar
Colin Walters committed
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
There are a few well-known approaches for software build roots:
 
 - Set up a chroot as root, then chroot in, and become non-root
   This is the model currently used by both rpm and dpkg.
   The problem with this is that if you want to build *two* packages
   where B depends on A, then the `%post` type scripts from A run
   as root, and hence need to be fully trusted.
 - Use `LD_PRELOAD` emulation
   This is implemented by https://github.com/wrpseudo/pseudo
   The problem with this is that it's a speed hit, and maintaining
   that sort of emulation is a long-term maintenance pain.
 - Don't do any chrooting, use environment variables
   This is implemented by `jhbuild`.  The problem with this is there
   are a *lot* of these, and it's really easy to get "host contamination",
   where we silently pick up `/usr/include/foo.h` instead of the one
   from the root.

What linux-user-chroot does is a variant of the first, except instead
of using root-owned files for the chroot, you simply make the chroot
data as non-root, and run `%post` type scripts as non-root too.

This works because we believe linux-user-chroot is secure; see below.
Colin Walters's avatar
Colin Walters committed
55
56
57
58

Security
--------

Colin Walters's avatar
Colin Walters committed
59
60
**** IMPORTANT NOTE ****

Colin Walters's avatar
Colin Walters committed
61
62
63
64
Installing this tool accessible to all users increases their ability
to perform local, authenticated denial of service attacks.  One
mitigation against this is to ensure the tool is only executable by
certain users.
Colin Walters's avatar
Colin Walters committed
65
66
67

**** IMPORTANT NOTE ****

Colin Walters's avatar
Colin Walters committed
68
69
70
71
The historical reason Unix doesn't allow chroot(2) as non-root is
because of setuid binaries.  It's trivial to use chroot to create a
hostile environment, then execute a setuid binary to subvert it.

Colin Walters's avatar
Colin Walters committed
72
73
74
75
76
77
78
79
Since then, the Linux kernel has gained a per-process mode
that disables setuid binaries, called `PR_SET_NO_NEW_PRIVS`:

https://lwn.net/Articles/478062/

While this tool itself is setuid, it enables that mode, thus ensuring
any other setuid binaries (including recursive invocations of this
tool) cannot be exploited.
Colin Walters's avatar
Colin Walters committed
80
81

However, this tool also allows creating bind mounts, which currently
Colin Walters's avatar
Colin Walters committed
82
83
84
have no resource controls and occupy kernel memory.  This is why this
tool is not intended to be installed by default and accessible to all
users.
Colin Walters's avatar
Colin Walters committed
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114

Abilities granted
-----------------

However in order to make a usable system, it's not quite enough to be
able to call chroot(2).  A lot of Unix software expects
e.g. /dev/null, and Linux /proc is also fairly widely used.  So
this tool also allows creating Linux "bind mounts".  This is how
one can expose the "host" /dev inside the chroot.  Also, this tool
allows mounting procfs.

In addition, this tool exposes several of the Linux "unshare"
capabilities such as:

  * CLONE_NEWNET - create a new, empty networking stack.  Because
    the child process won't have the privilges to manipulate the
    network, this will result in no networking (including loopback)
    which ensures that e.g. the build process isn't downloading more
    code.

  * CLONE_NEWPID - create a new PID namespace.  For example, if the
    build script runs some test scripts that start processes, "pidof"
    won't accidentally pick up a similarly-named process outside of
    the root.

  * CLONE_NEWIPC - get a new SysV IPC namespace.  This is just further
    isolation.

See "man 2 clone" for more information.

Colin Walters's avatar
Colin Walters committed
115
116
117
118
Additionally, the 2015.1 release of linux-user-chroot also gained
support for seccomp, which is a strong way to restrict what system
calls build systems can use.

Colin Walters's avatar
Colin Walters committed
119
120
121
122
123
124
Example usage
-------------

Note here all files are owned by the user.

$ mkdir -p /path/to/my/chroot/usr/src/project
Colin Walters's avatar
Colin Walters committed
125
126
127
$ linux-user-chroot \
   --seccomp-profile-version 0 \
   --unshare-pid --unshare-net --unshare-pid \
Colin Walters's avatar
Colin Walters committed
128
129
130
131
132
133
   --mount-proc /proc --mount-bind /dev /dev \
   --mount-bind /home/user/source/project /usr/src/project \
   /path/to/my/chroot /bin/sh

Here we're creating a bind mount inside the chroot to outside.  This
helps avoid copying files around.
134
135
136
137
138
139
140
141

Installing
----------

This binary can be installed in two modes:

1) uwsr-xr-x  root:root - Executable by everyone
2) uwsr-x---  root:somegroup - Executable only by somegroup
Colin Walters's avatar
Colin Walters committed
142
143
144
145
146
147

Programs using linux-user-chroot
--------------------------------

 - https://github.com/CodethinkLabs/sandboxlib
 - https://git.gnome.org/browse/gnome-continuous/ uses it for builds
Colin Walters's avatar
Colin Walters committed
148
149
150
151
152
153
154
155
156

Related projects
----------------

Google's Bazel system has a similar tool:

https://github.com/google/bazel/blob/master/src/main/tools/namespace-sandbox.c

(Noted by the sandboxlib/README.rst list of related projects)