Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Merge pull request #1590 from brauner/2017-05-27/new_readme
repo: add new README
- Loading branch information
Showing
2 changed files
with
205 additions
and
93 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,93 +0,0 @@ | ||
| Please see the COPYING file for details on copying and usage. | ||
| Please refer to the INSTALL file for instructions on how to build. | ||
|
|
||
| What is lxc: | ||
|
|
||
| The container technology is actively being pushed into the mainstream linux | ||
| kernel. It provides the resource management through the control groups aka | ||
| process containers and resource isolation through the namespaces. | ||
|
|
||
| The linux containers, lxc, aims to use these new functionalities to pro- | ||
| vide a userspace container object which provides full resource isolation | ||
| and resource control for an application or a system. | ||
|
|
||
| The first objective of this project is to make the life easier for the ker- | ||
| nel developers involved in the containers project and especially to con- | ||
| tinue working on the Checkpoint/Restart new features. The lxc is small | ||
| enough to easily manage a container with simple command lines and complete | ||
| enough to be used for other purposes. | ||
|
|
||
| Using lxc: | ||
|
|
||
| Refer the lxc* man pages (generated from doc/* files) | ||
|
|
||
| Downloading the current source code: | ||
|
|
||
| Source for the latest released version can always be downloaded from | ||
| http://linuxcontainers.org/downloads/ | ||
|
|
||
| You can browse the up to the minute source code and change history online. | ||
| http://github.com/lxc/lxc | ||
|
|
||
| For detailed build instruction refer to INSTALL and man lxc man page | ||
| but a short command line should work: | ||
| ./autogen.sh && ./configure && make && sudo make install | ||
| preceded by ./autogen.sh if configure do not exist yet. | ||
|
|
||
| Troubleshooting: | ||
|
|
||
| If you get an error message at the autogen.sh or configure stage, make | ||
| sure you have, autoconf, automake, pkg-config, make and gcc installed on | ||
| your machine. | ||
|
|
||
| The configure script will usually give you hints as to what you are missing, | ||
| looking for those in your package manager will usually give you the package | ||
| that you need to install. | ||
|
|
||
| Also pay a close attention to the feature summary showed at the end of | ||
| the configure run, features are automatically enabled/disabled based on | ||
| whether the needed development packages are installed on your machine. | ||
| If you want a feature but don't know what to install, force it with | ||
| --enable-<feature> and look at the error message from configure. | ||
|
|
||
| Getting help: | ||
|
|
||
| when you find you need help, 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 | ||
|
|
||
| Portability: | ||
|
|
||
| lxc is developed and tested on Linux since kernel mainline version 2.6.27 | ||
| (without network) and 2.6.29 with network isolation. | ||
| It's compiled with gcc, and should work on most architectures as long as the | ||
| required kernel features are available. This includes (but isn't limited to): | ||
| i686, x86_64, ppc, ppc64, S390, armel and armhf. | ||
|
|
||
| AUTHOR | ||
| Daniel Lezcano <daniel.lezcano@free.fr> | ||
|
|
||
| Seccomp with LXC | ||
| ---------------- | ||
|
|
||
| To restrict a container with seccomp, you must specify a profile which is | ||
| basically a whitelist of system calls it may execute. In the container | ||
| config file, add a line like | ||
|
|
||
| lxc.seccomp = /var/lib/lxc/q1/seccomp.full | ||
|
|
||
| I created a usable (but basically worthless) seccomp.full file using | ||
|
|
||
| cat > seccomp.full << EOF | ||
| 1 | ||
| whitelist | ||
| EOF | ||
| for i in `seq 0 300`; do | ||
| echo $i >> seccomp.full | ||
| done | ||
| for i in `seq 1024 1079`; do | ||
| echo $i >> seccomp.full | ||
| done | ||
|
|
||
| -- Serge Hallyn <serge.hallyn@ubuntu.com> Fri, 27 Jul 2012 15:47:02 +0600 | ||
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,205 @@ | ||
| # LXC | ||
|
|
||
| * Jenkins: [](https://jenkins.linuxcontainers.org/job/lxc-github-commit/) | ||
| * Travis: [](https://travis-ci.org/lxc/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. | ||
|
|
||
| ## 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, users which are unprivileged on the host will only be | ||
| able to establish a mapping for their own UID if they do not rely on | ||
| privileged helpers. 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` | ||
| - `lxc.mount.entry` | ||
|
|
||
| LXC namespaces configuration keys by using single dots. This means complex | ||
| configuration keys such as `lxc.network` expose various subkeys such as | ||
| `lxc.network.type`, `lxc.network.link`, `lxc.network.ipv6`, 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 `2.*.*`. | ||
|
|
||
| ## 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.hallyn (at) ubuntu (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 |