The following pull request was submitted through Github. It can be accessed and reviewed at: https://github.com/lxc/lxc-utils/pull/1
This e-mail was sent by the LXC bot, direct replies will not reach the author unless they happen to be subscribed to this list. === Description (from pull-request) === Signed-off-by: Christian Brauner <christian.brau...@ubuntu.com>
From 3942cab0ccd6ff487657b7e6eeacc286140e14e3 Mon Sep 17 00:00:00 2001 From: Christian Brauner <christian.brau...@ubuntu.com> Date: Thu, 8 Feb 2018 15:16:28 +0100 Subject: [PATCH] README: update Signed-off-by: Christian Brauner <christian.brau...@ubuntu.com> --- README.md | 169 +++++++++++++++++--------------------------------------------- 1 file changed, 47 insertions(+), 122 deletions(-) diff --git a/README.md b/README.md index dd7ac8f..355ba63 100644 --- a/README.md +++ b/README.md @@ -1,11 +1,53 @@ [](https://linuxcontainers.org/lxd) # lxc-utils -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. +This repo provides the well-known and heavily tested command line utilities to +interact with the [LXC](https://github.com/lxc/lxc) low-level Linux container +runtime. The main tools it provides are: + +## Container Commands + +Commands that operate on individual containers can be given the name of the +container either via the traditional unix-style command line flag syntax +(`lxc-start -n <container-name>`) syntax or without it (`lxc-start <container-name>`). +This includes: + +- `lxc-attach` +- `lxc-cgroup` +- `lxc-checkpoint` +- `lxc-console` +- `lxc-copy` +- `lxc-create` +- `lxc-destroy` +- `lxc-device` +- `lxc-execute` +- `lxc-freeze` +- `lxc-info` +- `lxc-snapshot` +- `lxc-start` +- `lxc-stop` +- `lxc-unfreeze` +- `lxc-wait` + +## Generic Commands + +These commands do not operate on multiple containers or system settings for +containers. + +- `lxc-autostart` +- `lxc-config` +- `lxc-ls` +- `lxc-monitor` +- `lxc-top` + +## Utility Commands + +These commands are generic helpers usually for interacting with generic +containerization features provided by the Linux kernel. They have mostly been +surpassed by generic Linux core utilities and are kept around for legacy +reasons. + +- `lxc-unshare` ## Status Type | Service | Status @@ -14,113 +56,6 @@ CI (Linux) | Jenkins | [ | Travis | [](https://travis-ci.org/lxc/lxc/) Project status | CII Best Practices | [](https://bestpractices.coreinfrastructure.org/projects/1087) - -## 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 `2.*.*`. - ## Reporting Security Issues The LXC project has a good reputation in handling security issues quickly and @@ -180,16 +115,6 @@ Without considering distribution specific details a simple 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
_______________________________________________ lxc-devel mailing list lxc-devel@lists.linuxcontainers.org http://lists.linuxcontainers.org/listinfo/lxc-devel
