[mirror_lxc.git] / README.md

[![LXD](https://linuxcontainers.org/static/img/containers.png)](https://linuxcontainers.org/lxd)
# LXC

LXC is the well-known and heavily tested low-level Linux container runtime. It
is in active development since 2008 and has proven itself in critical
production environments world-wide. Some of its core contributors are the same
people that helped to implement various well-known containerization features
inside the Linux kernel.

## Status
Type            | Service               | Status
---             | ---                   | ---
CI (Linux)      | GitHub                | [![Build Status](https://github.com/lxc/lxc/actions/workflows/build.yml/badge.svg)](https://github.com/lxc/lxc/actions)
CI (Linux)      | Jenkins               | [![Build Status](https://jenkins.linuxcontainers.org/job/lxc-github-commit/badge/icon)](https://jenkins.linuxcontainers.org/job/lxc-github-commit/)
Project status  | CII Best Practices    | [![CII Best Practices](https://bestpractices.coreinfrastructure.org/projects/1087/badge)](https://bestpractices.coreinfrastructure.org/projects/1087)
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)
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)
Fuzzing         | CIFuzz                | [![CIFuzz](https://github.com/lxc/lxc/actions/workflows/cifuzz.yml/badge.svg)](https://github.com/lxc/lxc/actions/workflows/cifuzz.yml)

## System Containers

LXC's main focus is system containers. That is, containers which offer an
environment as close as possible as the one you'd get from a VM but without the
overhead that comes with running a separate kernel and simulating all the
hardware.

This is achieved through a combination of kernel security features such as
namespaces, mandatory access control and control groups.

## Unprivileged Containers

Unprivileged containers are containers that are run without any privilege. This
requires support for user namespaces in the kernel that the container is run
on. LXC was the first runtime to support unprivileged containers after user
namespaces were merged into the mainline kernel.

In essence, user namespaces isolate given sets of UIDs and GIDs. This is
achieved by establishing a mapping between a range of UIDs and GIDs on the host
to a different (unprivileged) range of UIDs and GIDs in the container. The
kernel will translate this mapping in such a way that inside the container all
UIDs and GIDs appear as you would expect from the host whereas on the host
these UIDs and GIDs are in fact unprivileged. For example, a process running as
UID and GID 0 inside the container might appear as UID and GID 100000 on the
host. The implementation and working details can be gathered from the
corresponding user namespace man page.

Since unprivileged containers are a security enhancement they naturally come
with a few restrictions enforced by the kernel. In order to provide a fully
functional unprivileged container LXC interacts with 3 pieces of setuid code:

- lxc-user-nic (setuid helper to create a veth pair and bridge it on the host)
- newuidmap (from the shadow package, sets up a uid map)
- newgidmap (from the shadow package, sets up a gid map)

Everything else is run as your own user or as a uid which your user owns.

In general, LXC's goal is to make use of every security feature available in
the kernel. This means LXC's configuration management will allow experienced
users to intricately tune LXC to their needs.

A more detailed introduction into LXC security can be found under the following link

- https://linuxcontainers.org/lxc/security/

### Removing all Privilege

In principle LXC can be run without any of these tools provided the correct
configuration is applied. However, the usefulness of such containers is usually
quite restricted. Just to highlight the two most common problems:

1. Network: Without relying on a setuid helper to setup appropriate network
   devices for an unprivileged user (see LXC's `lxc-user-nic` binary) the only
   option is to share the network namespace with the host. Although this should
   be secure in principle, sharing the host's network namespace is still one
   step of isolation less and increases the attack vector.
   Furthermore, when host and container share the same network namespace the
   kernel will refuse any sysfs mounts. This usually means that the init binary
   inside of the container will not be able to boot up correctly.

2. User Namespaces: As outlined above, user namespaces are a big security
   enhancement. However, without relying on privileged helpers users who are
   unprivileged on the host are only permitted to map their own UID into
   a container. A standard POSIX system however, requires 65536 UIDs and GIDs
   to be available to guarantee full functionality.

## Configuration

LXC is configured via a simple set of keys. For example,

- `lxc.rootfs.path`
- `lxc.mount.entry`

LXC namespaces configuration keys by using single dots. This means complex
configuration keys such as `lxc.net.0` expose various subkeys such as
`lxc.net.0.type`, `lxc.net.0.link`, `lxc.net.0.ipv6.address`, and others for
even more fine-grained configuration.

LXC is used as the default runtime for [LXD](https://github.com/lxc/lxd),
a container hypervisor exposing a well-designed and stable REST-api on top of
it.

## Kernel Requirements

LXC runs on any kernel from 2.6.32 onwards. All it requires is a functional
C compiler. LXC works on all architectures that provide the necessary kernel
features. This includes (but isn't limited to):

- i686
- x86_64
- ppc, ppc64, ppc64le
- s390x
- armvl7, arm64

LXC also supports at least the following C standard libraries:

- glibc
- musl
- bionic (Android's libc)

## Backwards Compatibility

LXC has always focused on strong backwards compatibility. In fact, the API
hasn't been broken from release `1.0.0` onwards. Main LXC is currently at
version `4.*.*`.

## Reporting Security Issues

The LXC project has a good reputation in handling security issues quickly and
efficiently. If you think you've found a potential security issue, please
report it by e-mail to all of the following persons:

- serge (at) hallyn (dot) com
- stgraber (at) ubuntu (dot) com
- christian.brauner (at) ubuntu (dot) com

For further details please have a look at

- https://linuxcontainers.org/lxc/security/

## Becoming Active in LXC development

We always welcome new contributors and are happy to provide guidance when
necessary. LXC follows the kernel coding conventions. This means we only
require that each commit includes a `Signed-off-by` line. The coding style we
use is identical to the one used by the Linux kernel. You can find a detailed
introduction at:

- https://www.kernel.org/doc/html/v4.10/process/coding-style.html

and should also take a look at the [CONTRIBUTING](CONTRIBUTING) file in this
repo.

If you want to become more active it is usually also a good idea to show up in
the LXC IRC channel `#lxc-dev` on `Freenode`. We try to do all development out
in the open and discussion of new features or bugs is done either in
appropriate GitHub issues or on IRC.

When thinking about making security critical contributions or substantial
changes it is usually a good idea to ping the developers first and ask whether
a PR would be accepted.

## Semantic Versioning

LXC and its related projects strictly adhere to a [semantic
versioning](http://semver.org/) scheme.

## Downloading the current source code

Source for the latest released version can always be downloaded from

- https://linuxcontainers.org/downloads/

You can browse the up to the minute source code and change history online

- https://github.com/lxc/lxc

## Building LXC

Without considering distribution specific details a simple

    ./autogen.sh && ./configure && make && sudo make install

is usually sufficient.

In order to test current git master of LXC it is usually a good idea to compile with

    ./autogen.sh && ./configure && make

in a convenient directory and set `LD_LIBRARY_PATH="${BUILD_DIR}"/lxc/src/lxc/.libs`.

## Getting help

When you find you need help, the LXC projects provides you with several options.

### Discuss Forum

We maintain an discuss forum at

- https://discuss.linuxcontainers.org/

where you can get support.

### IRC

You can find support by joining `#lxcontainers` on `Freenode`.

### Mailing Lists

You can check out one of the two LXC mailing list archives and register if
interested:

- http://lists.linuxcontainers.org/listinfo/lxc-devel
- http://lists.linuxcontainers.org/listinfo/lxc-users
Commit	Line	Data
ea033bbc	1	[![LXD](https://linuxcontainers.org/static/img/containers.png)](https://linuxcontainers.org/lxd)
dc46727f CB	2	# LXC
dc46727f CB	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)
77d755ce EV	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
2e44ae28 CB	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
	111	- s390x
	112	- armvl7, arm64
	113
	114	LXC also supports at least the following C standard libraries:
	115
	116	- glibc
	117	- musl
	118	- bionic (Android's libc)
	119
	120	## Backwards Compatibility
	121
	122	LXC has always focused on strong backwards compatibility. In fact, the API
	123	hasn't been broken from release `1.0.0` onwards. Main LXC is currently at
949b3059	124	version `4..`.
dc46727f CB	125
	126	## Reporting Security Issues
	127
	128	The LXC project has a good reputation in handling security issues quickly and
	129	efficiently. If you think you've found a potential security issue, please
	130	report it by e-mail to all of the following persons:
	131
a3cf04da	132	- serge (at) hallyn (dot) com
dc46727f CB	133	- stgraber (at) ubuntu (dot) com
	134	- christian.brauner (at) ubuntu (dot) com
	135
	136	For further details please have a look at
	137
	138	- https://linuxcontainers.org/lxc/security/
	139
	140	## Becoming Active in LXC development
	141
	142	We always welcome new contributors and are happy to provide guidance when
	143	necessary. LXC follows the kernel coding conventions. This means we only
	144	require that each commit includes a `Signed-off-by` line. The coding style we
	145	use is identical to the one used by the Linux kernel. You can find a detailed
	146	introduction at:
	147
	148	- https://www.kernel.org/doc/html/v4.10/process/coding-style.html
	149
	150	and should also take a look at the [CONTRIBUTING](CONTRIBUTING) file in this
	151	repo.
	152
	153	If you want to become more active it is usually also a good idea to show up in
	154	the LXC IRC channel `#lxc-dev` on `Freenode`. We try to do all development out
	155	in the open and discussion of new features or bugs is done either in
154f6474	156	appropriate GitHub issues or on IRC.
dc46727f CB	157
	158	When thinking about making security critical contributions or substantial
	159	changes it is usually a good idea to ping the developers first and ask whether
	160	a PR would be accepted.
	161
	162	## Semantic Versioning
	163
	164	LXC and its related projects strictly adhere to a [semantic
	165	versioning](http://semver.org/) scheme.
	166
	167	## Downloading the current source code
	168
	169	Source for the latest released version can always be downloaded from
	170
	171	- https://linuxcontainers.org/downloads/
	172
	173	You can browse the up to the minute source code and change history online
	174
	175	- https://github.com/lxc/lxc
	176
	177	## Building LXC
	178
	179	Without considering distribution specific details a simple
	180
	181	./autogen.sh && ./configure && make && sudo make install
	182
	183	is usually sufficient.
	184
	185	In order to test current git master of LXC it is usually a good idea to compile with
	186
	187	./autogen.sh && ./configure && make
	188
	189	in a convenient directory and set `LD_LIBRARY_PATH="${BUILD_DIR}"/lxc/src/lxc/.libs`.
	190
	191	## Getting help
	192
	193	When you find you need help, the LXC projects provides you with several options.
	194
	195	### Discuss Forum
	196
	197	We maintain an discuss forum at
	198
	199	- https://discuss.linuxcontainers.org/
	200
	201	where you can get support.
	202
	203	### IRC
	204
	205	You can find support by joining `#lxcontainers` on `Freenode`.
	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