README.md

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