README.md

   1 [![LXD](https://linuxcontainers.org/static/img/containers.png)](https://linuxcontainers.org/lxd)
   2 # LXC
   3
   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
  10 ## Status
  11 Type            | Service               | Status
  12 ---             | ---                   | ---
  13 CI (Linux)      | GitHub                | [![Build Status](https://github.com/lxc/lxc/actions/workflows/build.yml/badge.svg)](https://github.com/lxc/lxc/actions)
  14 CI (Linux)      | Jenkins               | [![Build Status](https://jenkins.linuxcontainers.org/job/lxc-github-commit/badge/icon)](https://jenkins.linuxcontainers.org/job/lxc-github-commit/)
  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 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)
  19
  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
  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.
  85
  86 ## Configuration
  87
  88 LXC is configured via a simple set of keys. For example,
  89
  90 - `lxc.rootfs.path`
  91 - `lxc.mount.entry`
  92
  93 LXC namespaces configuration keys by using single dots. This means complex
  94 configuration keys such as `lxc.net.0` expose various subkeys such as
  95 `lxc.net.0.type`, `lxc.net.0.link`, `lxc.net.0.ipv6.address`, and others for
  96 even more fine-grained configuration.
  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
 111 - riscv64
 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
 125 version `4.*.*`.
 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
 133 - serge (at) hallyn (dot) com
 134 - stgraber (at) ubuntu (dot) com
 135 - brauner (at) kernel (dot) org
 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
 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
 156 in the open and discussion of new features or bugs is done either in
 157 appropriate GitHub issues or on IRC.
 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
 172 - https://linuxcontainers.org/lxc/downloads/
 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     meson setup -Dprefix=/usr build
 183     meson compile -C build
 184
 185 is usually sufficient.
 186
 187 ## Getting help
 188
 189 When you find you need help, the LXC projects provides you with several options.
 190
 191 ### Discuss Forum
 192
 193 We maintain a discuss forum at
 194
 195 - https://discuss.linuxcontainers.org/
 196
 197 where you can get support.
 198
 199 ### IRC
 200 You can find us in [#lxc](https://kiwiirc.com/client/irc.libera.chat/#lxc) on irc.libera.chat.
 201
 202 ### Mailing Lists
 203
 204 You can check out one of the two LXC mailing list archives and register if
 205 interested:
 206
 207 - http://lists.linuxcontainers.org/listinfo/lxc-devel
 208 - http://lists.linuxcontainers.org/listinfo/lxc-users