]>
Commit | Line | Data |
---|---|---|
ea033bbc | 1 | [![LXD](https://linuxcontainers.org/static/img/containers.png)](https://linuxcontainers.org/lxd) |
dc46727f CB |
2 | # LXC |
3 | ||
dc46727f CB |
4 | LXC is the well-known and heavily tested low-level Linux container runtime. It |
5 | is in active development since 2008 and has proven itself in critical | |
6 | production environments world-wide. Some of its core contributors are the same | |
7 | people that helped to implement various well-known containerization features | |
8 | inside the Linux kernel. | |
9 | ||
ea033bbc CB |
10 | ## Status |
11 | Type | Service | Status | |
12 | --- | --- | --- | |
73c852f7 | 13 | CI (Linux) | GitHub | [![Build Status](https://github.com/lxc/lxc/actions/workflows/build.yml/badge.svg)](https://github.com/lxc/lxc/actions) |
ea033bbc | 14 | CI (Linux) | Jenkins | [![Build Status](https://jenkins.linuxcontainers.org/job/lxc-github-commit/badge/icon)](https://jenkins.linuxcontainers.org/job/lxc-github-commit/) |
ea033bbc | 15 | Project status | CII Best Practices | [![CII Best Practices](https://bestpractices.coreinfrastructure.org/projects/1087/badge)](https://bestpractices.coreinfrastructure.org/projects/1087) |
a62cf72a | 16 | Code Quality | LGTM | [![Language grade: C/C++](https://img.shields.io/lgtm/grade/cpp/g/lxc/lxc.svg?logo=lgtm&logoWidth=18)](https://lgtm.com/projects/g/lxc/lxc/context:cpp) |
77d755ce EV |
17 | Fuzzing | OSS-Fuzz | [![Fuzzing Status](https://oss-fuzz-build-logs.storage.googleapis.com/badges/lxc.svg)](https://oss-fuzz-build-logs.storage.googleapis.com/index.html#lxc) |
18 | Fuzzing | CIFuzz | [![CIFuzz](https://github.com/lxc/lxc/actions/workflows/cifuzz.yml/badge.svg)](https://github.com/lxc/lxc/actions/workflows/cifuzz.yml) | |
ea033bbc | 19 | |
dc46727f CB |
20 | ## System Containers |
21 | ||
22 | LXC's main focus is system containers. That is, containers which offer an | |
23 | environment as close as possible as the one you'd get from a VM but without the | |
24 | overhead that comes with running a separate kernel and simulating all the | |
25 | hardware. | |
26 | ||
27 | This is achieved through a combination of kernel security features such as | |
28 | namespaces, mandatory access control and control groups. | |
29 | ||
30 | ## Unprivileged Containers | |
31 | ||
32 | Unprivileged containers are containers that are run without any privilege. This | |
33 | requires support for user namespaces in the kernel that the container is run | |
34 | on. LXC was the first runtime to support unprivileged containers after user | |
35 | namespaces were merged into the mainline kernel. | |
36 | ||
37 | In essence, user namespaces isolate given sets of UIDs and GIDs. This is | |
38 | achieved by establishing a mapping between a range of UIDs and GIDs on the host | |
39 | to a different (unprivileged) range of UIDs and GIDs in the container. The | |
40 | kernel will translate this mapping in such a way that inside the container all | |
41 | UIDs and GIDs appear as you would expect from the host whereas on the host | |
42 | these UIDs and GIDs are in fact unprivileged. For example, a process running as | |
43 | UID and GID 0 inside the container might appear as UID and GID 100000 on the | |
44 | host. The implementation and working details can be gathered from the | |
45 | corresponding user namespace man page. | |
46 | ||
47 | Since unprivileged containers are a security enhancement they naturally come | |
48 | with a few restrictions enforced by the kernel. In order to provide a fully | |
49 | functional unprivileged container LXC interacts with 3 pieces of setuid code: | |
50 | ||
51 | - lxc-user-nic (setuid helper to create a veth pair and bridge it on the host) | |
52 | - newuidmap (from the shadow package, sets up a uid map) | |
53 | - newgidmap (from the shadow package, sets up a gid map) | |
54 | ||
55 | Everything else is run as your own user or as a uid which your user owns. | |
56 | ||
57 | In general, LXC's goal is to make use of every security feature available in | |
58 | the kernel. This means LXC's configuration management will allow experienced | |
59 | users to intricately tune LXC to their needs. | |
60 | ||
61 | A more detailed introduction into LXC security can be found under the following link | |
62 | ||
63 | - https://linuxcontainers.org/lxc/security/ | |
64 | ||
65 | ### Removing all Privilege | |
66 | ||
67 | In principle LXC can be run without any of these tools provided the correct | |
68 | configuration is applied. However, the usefulness of such containers is usually | |
69 | quite restricted. Just to highlight the two most common problems: | |
70 | ||
71 | 1. Network: Without relying on a setuid helper to setup appropriate network | |
72 | devices for an unprivileged user (see LXC's `lxc-user-nic` binary) the only | |
73 | option is to share the network namespace with the host. Although this should | |
74 | be secure in principle, sharing the host's network namespace is still one | |
75 | step of isolation less and increases the attack vector. | |
76 | Furthermore, when host and container share the same network namespace the | |
77 | kernel will refuse any sysfs mounts. This usually means that the init binary | |
78 | inside of the container will not be able to boot up correctly. | |
79 | ||
80 | 2. User Namespaces: As outlined above, user namespaces are a big security | |
ac8f64dc CB |
81 | enhancement. However, without relying on privileged helpers users who are |
82 | unprivileged on the host are only permitted to map their own UID into | |
83 | a container. A standard POSIX system however, requires 65536 UIDs and GIDs | |
84 | to be available to guarantee full functionality. | |
dc46727f CB |
85 | |
86 | ## Configuration | |
87 | ||
88 | LXC is configured via a simple set of keys. For example, | |
89 | ||
7a96a068 | 90 | - `lxc.rootfs.path` |
dc46727f CB |
91 | - `lxc.mount.entry` |
92 | ||
93 | LXC namespaces configuration keys by using single dots. This means complex | |
7fa3f2e9 | 94 | configuration keys such as `lxc.net.0` expose various subkeys such as |
2e44ae28 CB |
95 | `lxc.net.0.type`, `lxc.net.0.link`, `lxc.net.0.ipv6.address`, and others for |
96 | even more fine-grained configuration. | |
dc46727f CB |
97 | |
98 | LXC is used as the default runtime for [LXD](https://github.com/lxc/lxd), | |
99 | a container hypervisor exposing a well-designed and stable REST-api on top of | |
100 | it. | |
101 | ||
102 | ## Kernel Requirements | |
103 | ||
104 | LXC runs on any kernel from 2.6.32 onwards. All it requires is a functional | |
105 | C compiler. LXC works on all architectures that provide the necessary kernel | |
106 | features. This includes (but isn't limited to): | |
107 | ||
108 | - i686 | |
109 | - x86_64 | |
110 | - ppc, ppc64, ppc64le | |
0a2ffe12 | 111 | - riscv64 |
dc46727f CB |
112 | - s390x |
113 | - armvl7, arm64 | |
114 | ||
115 | LXC also supports at least the following C standard libraries: | |
116 | ||
117 | - glibc | |
118 | - musl | |
119 | - bionic (Android's libc) | |
120 | ||
121 | ## Backwards Compatibility | |
122 | ||
123 | LXC has always focused on strong backwards compatibility. In fact, the API | |
124 | hasn't been broken from release `1.0.0` onwards. Main LXC is currently at | |
949b3059 | 125 | version `4.*.*`. |
dc46727f CB |
126 | |
127 | ## Reporting Security Issues | |
128 | ||
129 | The LXC project has a good reputation in handling security issues quickly and | |
130 | efficiently. If you think you've found a potential security issue, please | |
131 | report it by e-mail to all of the following persons: | |
132 | ||
a3cf04da | 133 | - serge (at) hallyn (dot) com |
dc46727f CB |
134 | - stgraber (at) ubuntu (dot) com |
135 | - christian.brauner (at) ubuntu (dot) com | |
136 | ||
137 | For further details please have a look at | |
138 | ||
139 | - https://linuxcontainers.org/lxc/security/ | |
140 | ||
141 | ## Becoming Active in LXC development | |
142 | ||
143 | We always welcome new contributors and are happy to provide guidance when | |
144 | necessary. LXC follows the kernel coding conventions. This means we only | |
145 | require that each commit includes a `Signed-off-by` line. The coding style we | |
146 | use is identical to the one used by the Linux kernel. You can find a detailed | |
147 | introduction at: | |
148 | ||
149 | - https://www.kernel.org/doc/html/v4.10/process/coding-style.html | |
150 | ||
151 | and should also take a look at the [CONTRIBUTING](CONTRIBUTING) file in this | |
152 | repo. | |
153 | ||
154 | If you want to become more active it is usually also a good idea to show up in | |
c49b9f61 | 155 | the LXC IRC channel [#lxc-dev](https://kiwiirc.com/client/irc.libera.chat/#lxc-dev) on irc.libera.chat. We try to do all development out |
dc46727f | 156 | in the open and discussion of new features or bugs is done either in |
154f6474 | 157 | appropriate GitHub issues or on IRC. |
dc46727f CB |
158 | |
159 | When thinking about making security critical contributions or substantial | |
160 | changes it is usually a good idea to ping the developers first and ask whether | |
161 | a PR would be accepted. | |
162 | ||
163 | ## Semantic Versioning | |
164 | ||
165 | LXC and its related projects strictly adhere to a [semantic | |
166 | versioning](http://semver.org/) scheme. | |
167 | ||
168 | ## Downloading the current source code | |
169 | ||
170 | Source for the latest released version can always be downloaded from | |
171 | ||
5e7448b5 | 172 | - https://linuxcontainers.org/lxc/downloads/ |
dc46727f CB |
173 | |
174 | You can browse the up to the minute source code and change history online | |
175 | ||
176 | - https://github.com/lxc/lxc | |
177 | ||
178 | ## Building LXC | |
179 | ||
180 | Without considering distribution specific details a simple | |
181 | ||
182 | ./autogen.sh && ./configure && make && sudo make install | |
183 | ||
184 | is usually sufficient. | |
185 | ||
186 | In order to test current git master of LXC it is usually a good idea to compile with | |
187 | ||
188 | ./autogen.sh && ./configure && make | |
189 | ||
190 | in a convenient directory and set `LD_LIBRARY_PATH="${BUILD_DIR}"/lxc/src/lxc/.libs`. | |
191 | ||
192 | ## Getting help | |
193 | ||
194 | When you find you need help, the LXC projects provides you with several options. | |
195 | ||
196 | ### Discuss Forum | |
197 | ||
198 | We maintain an discuss forum at | |
199 | ||
200 | - https://discuss.linuxcontainers.org/ | |
201 | ||
202 | where you can get support. | |
203 | ||
204 | ### IRC | |
c49b9f61 | 205 | You can find us in [#lxc](https://kiwiirc.com/client/irc.libera.chat/#lxc) on irc.libera.chat. |
dc46727f CB |
206 | |
207 | ### Mailing Lists | |
208 | ||
209 | You can check out one of the two LXC mailing list archives and register if | |
210 | interested: | |
211 | ||
212 | - http://lists.linuxcontainers.org/listinfo/lxc-devel | |
213 | - http://lists.linuxcontainers.org/listinfo/lxc-users |