1 [![LXD](https://linuxcontainers.org/static/img/containers.png)](https://linuxcontainers.org/lxd)
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.
11 Type | Service | Status
13 CI (Linux) | Jenkins | [![Build Status](https://jenkins.linuxcontainers.org/job/lxc-github-commit/badge/icon)](https://jenkins.linuxcontainers.org/job/lxc-github-commit/)
14 CI (Linux) | Travis | [![Build Status](https://travis-ci.org/lxc/lxc.svg?branch=master)](https://travis-ci.org/lxc/lxc/)
15 Project status | CII Best Practices | [![CII Best Practices](https://bestpractices.coreinfrastructure.org/projects/1087/badge)](https://bestpractices.coreinfrastructure.org/projects/1087)
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)
17 Static Analysis | Coverity | <a href="https://scan.coverity.com/projects/lxc-linux-containers"> <img alt="Coverity Scan Build Status" src="https://img.shields.io/coverity/scan/369.svg"/> </a>
21 LXC's main focus is system containers. That is, containers which offer an
22 environment as close as possible as the one you'd get from a VM but without the
23 overhead that comes with running a separate kernel and simulating all the
26 This is achieved through a combination of kernel security features such as
27 namespaces, mandatory access control and control groups.
29 ## Unprivileged Containers
31 Unprivileged containers are containers that are run without any privilege. This
32 requires support for user namespaces in the kernel that the container is run
33 on. LXC was the first runtime to support unprivileged containers after user
34 namespaces were merged into the mainline kernel.
36 In essence, user namespaces isolate given sets of UIDs and GIDs. This is
37 achieved by establishing a mapping between a range of UIDs and GIDs on the host
38 to a different (unprivileged) range of UIDs and GIDs in the container. The
39 kernel will translate this mapping in such a way that inside the container all
40 UIDs and GIDs appear as you would expect from the host whereas on the host
41 these UIDs and GIDs are in fact unprivileged. For example, a process running as
42 UID and GID 0 inside the container might appear as UID and GID 100000 on the
43 host. The implementation and working details can be gathered from the
44 corresponding user namespace man page.
46 Since unprivileged containers are a security enhancement they naturally come
47 with a few restrictions enforced by the kernel. In order to provide a fully
48 functional unprivileged container LXC interacts with 3 pieces of setuid code:
50 - lxc-user-nic (setuid helper to create a veth pair and bridge it on the host)
51 - newuidmap (from the shadow package, sets up a uid map)
52 - newgidmap (from the shadow package, sets up a gid map)
54 Everything else is run as your own user or as a uid which your user owns.
56 In general, LXC's goal is to make use of every security feature available in
57 the kernel. This means LXC's configuration management will allow experienced
58 users to intricately tune LXC to their needs.
60 A more detailed introduction into LXC security can be found under the following link
62 - https://linuxcontainers.org/lxc/security/
64 ### Removing all Privilege
66 In principle LXC can be run without any of these tools provided the correct
67 configuration is applied. However, the usefulness of such containers is usually
68 quite restricted. Just to highlight the two most common problems:
70 1. Network: Without relying on a setuid helper to setup appropriate network
71 devices for an unprivileged user (see LXC's `lxc-user-nic` binary) the only
72 option is to share the network namespace with the host. Although this should
73 be secure in principle, sharing the host's network namespace is still one
74 step of isolation less and increases the attack vector.
75 Furthermore, when host and container share the same network namespace the
76 kernel will refuse any sysfs mounts. This usually means that the init binary
77 inside of the container will not be able to boot up correctly.
79 2. User Namespaces: As outlined above, user namespaces are a big security
80 enhancement. However, without relying on privileged helpers users who are
81 unprivileged on the host are only permitted to map their own UID into
82 a container. A standard POSIX system however, requires 65536 UIDs and GIDs
83 to be available to guarantee full functionality.
87 LXC is configured via a simple set of keys. For example,
92 LXC namespaces configuration keys by using single dots. This means complex
93 configuration keys such as `lxc.net.0` expose various subkeys such as
94 `lxc.net.0.type`, `lxc.net.0.link`, `lxc.net.0.ipv6.address`, and others for
95 even more fine-grained configuration.
97 LXC is used as the default runtime for [LXD](https://github.com/lxc/lxd),
98 a container hypervisor exposing a well-designed and stable REST-api on top of
101 ## Kernel Requirements
103 LXC runs on any kernel from 2.6.32 onwards. All it requires is a functional
104 C compiler. LXC works on all architectures that provide the necessary kernel
105 features. This includes (but isn't limited to):
109 - ppc, ppc64, ppc64le
113 LXC also supports at least the following C standard libraries:
117 - bionic (Android's libc)
119 ## Backwards Compatibility
121 LXC has always focused on strong backwards compatibility. In fact, the API
122 hasn't been broken from release `1.0.0` onwards. Main LXC is currently at
125 ## Reporting Security Issues
127 The LXC project has a good reputation in handling security issues quickly and
128 efficiently. If you think you've found a potential security issue, please
129 report it by e-mail to all of the following persons:
131 - serge (at) hallyn (dot) com
132 - stgraber (at) ubuntu (dot) com
133 - christian.brauner (at) ubuntu (dot) com
135 For further details please have a look at
137 - https://linuxcontainers.org/lxc/security/
139 ## Becoming Active in LXC development
141 We always welcome new contributors and are happy to provide guidance when
142 necessary. LXC follows the kernel coding conventions. This means we only
143 require that each commit includes a `Signed-off-by` line. The coding style we
144 use is identical to the one used by the Linux kernel. You can find a detailed
147 - https://www.kernel.org/doc/html/v4.10/process/coding-style.html
149 and should also take a look at the [CONTRIBUTING](CONTRIBUTING) file in this
152 If you want to become more active it is usually also a good idea to show up in
153 the LXC IRC channel `#lxc-dev` on `Freenode`. We try to do all development out
154 in the open and discussion of new features or bugs is done either in
155 appropriate GitHub issues or on IRC.
157 When thinking about making security critical contributions or substantial
158 changes it is usually a good idea to ping the developers first and ask whether
159 a PR would be accepted.
161 ## Semantic Versioning
163 LXC and its related projects strictly adhere to a [semantic
164 versioning](http://semver.org/) scheme.
166 ## Downloading the current source code
168 Source for the latest released version can always be downloaded from
170 - https://linuxcontainers.org/downloads/
172 You can browse the up to the minute source code and change history online
174 - https://github.com/lxc/lxc
178 Without considering distribution specific details a simple
180 ./autogen.sh && ./configure && make && sudo make install
182 is usually sufficient.
184 In order to test current git master of LXC it is usually a good idea to compile with
186 ./autogen.sh && ./configure && make
188 in a convenient directory and set `LD_LIBRARY_PATH="${BUILD_DIR}"/lxc/src/lxc/.libs`.
192 When you find you need help, the LXC projects provides you with several options.
196 We maintain an discuss forum at
198 - https://discuss.linuxcontainers.org/
200 where you can get support.
204 You can find support by joining `#lxcontainers` on `Freenode`.
208 You can check out one of the two LXC mailing list archives and register if
211 - http://lists.linuxcontainers.org/listinfo/lxc-devel
212 - http://lists.linuxcontainers.org/listinfo/lxc-users