The following pull request was submitted through Github.
It can be accessed and reviewed at:

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 <>
From 3942cab0ccd6ff487657b7e6eeacc286140e14e3 Mon Sep 17 00:00:00 2001
From: Christian Brauner <>
Date: Thu, 8 Feb 2018 15:16:28 +0100
Subject: [PATCH] README: update

Signed-off-by: Christian Brauner <>
--- | 169 +++++++++++++++++---------------------------------------------
 1 file changed, 47 insertions(+), 122 deletions(-)

diff --git a/ b/
index dd7ac8f..355ba63 100644
--- a/
+++ b/
@@ -1,11 +1,53 @@
 # 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]( 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 
+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
+- `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
+- `lxc-unshare`
 ## Status
 Type            | Service               | Status
@@ -14,113 +56,6 @@ CI (Linux)      | Jenkins               | [![Build 
 CI (Linux)      | Travis                | [![Build 
 Project status  | CII Best Practices    | [![CII Best 
-## 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
-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
-### 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 `` expose various subkeys such as
-``, ``, ``, and others for
-even more fine-grained configuration.
-LXC is used as the default runtime for [LXD](,
-a container hypervisor exposing a well-designed and stable REST-api on top of
-## 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
-    ./ && ./configure && make
-in a convenient directory and set 
-## Getting help
-When you find you need help, the LXC projects provides you with several 
 ### Discuss Forum
 We maintain an discuss forum at
lxc-devel mailing list

Reply via email to