[lxc-devel] [lxc-utils/master] README: update
brauner on Github
lxc-bot at linuxcontainers.org
Thu Feb 8 14:20:27 UTC 2018
A non-text attachment was scrubbed...
Name: not available
Type: text/x-mailbox
Size: 367 bytes
Desc: not available
URL: <http://lists.linuxcontainers.org/pipermail/lxc-devel/attachments/20180208/a35c3580/attachment.bin>
-------------- next part --------------
From 3942cab0ccd6ff487657b7e6eeacc286140e14e3 Mon Sep 17 00:00:00 2001
From: Christian Brauner <christian.brauner at ubuntu.com>
Date: Thu, 8 Feb 2018 15:16:28 +0100
Subject: [PATCH] README: update
Signed-off-by: Christian Brauner <christian.brauner at 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
More information about the lxc-devel
mailing list