[lxc-devel] [lxc/master] repo: add new README

brauner on Github lxc-bot at linuxcontainers.org
Sat May 27 04:25:03 UTC 2017


A non-text attachment was scrubbed...
Name: not available
Type: text/x-mailbox
Size: 364 bytes
Desc: not available
URL: <http://lists.linuxcontainers.org/pipermail/lxc-devel/attachments/20170527/11476ea5/attachment.bin>
-------------- next part --------------
From 13abab96d64c91da4bb404f9d85f3c9b33e88fe5 Mon Sep 17 00:00:00 2001
From: Christian Brauner <christian.brauner at ubuntu.com>
Date: Sat, 27 May 2017 03:53:59 +0200
Subject: [PATCH] repo: add new README

Signed-off-by: Christian Brauner <christian.brauner at ubuntu.com>
---
 README    |  93 -----------------------------
 README.md | 197 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 197 insertions(+), 93 deletions(-)
 create mode 100644 README.md

diff --git a/README b/README
index bca00c97e..e69de29bb 100644
--- a/README
+++ b/README
@@ -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 at 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 at ubuntu.com>  Fri, 27 Jul 2012 15:47:02 +0600
diff --git a/README.md b/README.md
new file mode 100644
index 000000000..ece63e7ca
--- /dev/null
+++ b/README.md
@@ -0,0 +1,197 @@
+# LXC
+
+* Jenkins: [![Build Status](https://jenkins.linuxcontainers.org/job/lxc-github-commit/badge/icon)](https://jenkins.linuxcontainers.org/job/lxc-github-commit/)
+* Travis:  [![Build Status](https://travis-ci.org/lxc/lxc.svg?branch=master)](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.
+
+2. User Namespaces: As outlined above, user namespaces are a big security
+   enhancement. However, user 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 compatiblity. 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 approriate
+Github issues or on IRC.
+
+When thinking about making security critical contributions or substantial
+changes it is usally a good idea to ping the developers first and ask whether
+a PR would be accepted.
+
+## 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 `#lxccontainers` 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


More information about the lxc-devel mailing list