lxc / python2-lxc

Python 2.7 binding for liblxc (similar to the better supported python3-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.

Status

Type	Service	Status
CI (Linux)	GitHub
CI (Linux)	Jenkins
Project status	CII Best Practices
Fuzzing	OSS-Fuzz
Fuzzing	CIFuzz

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 Incus, 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
• riscv64
• s390x
• armv7l, arm64
• loongarch64

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 4.*.*.

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 (at) hallyn (dot) com
• stgraber (at) ubuntu (dot) com
• brauner (at) kernel (dot) org

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 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 irc.libera.chat. 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 scheme.

Downloading the current source code

Source for the latest released version can always be downloaded from

• https://linuxcontainers.org/lxc/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

meson setup -Dprefix=/usr build
meson compile -C build

is usually sufficient.

Getting help

When you find you need help, the LXC projects provides you with several options.

Discuss Forum

We maintain a discuss forum at

• https://discuss.linuxcontainers.org/

where you can get support.

IRC

You can find us in #lxc on irc.libera.chat.

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

python2-lxc's Issues

Document the dependencies

Can you please document the dependencies of this project? Guessing from the errors below, at least the Python and LXC development libraries (aka python-dev/python-devel and lxc-dev/lxc-devel) are needed.

$ pip install lxc-python2
Collecting lxc-python2
  Using cached lxc-python2-0.1.zip
Installing collected packages: lxc-python2
  Running setup.py install for lxc-python2
    Complete output from command /usr/bin/python -c "import setuptools, tokenize;__file__='/tmp/pip-build-ivXpM7/lxc-python2/setup.py';exec(compile(getattr(tokenize, 'open', open)(__file__).read().replace('\r\n', '\n'), __file__, 'exec'))" install --record /tmp/pip-U4pDvj-record/install-record.txt --single-version-externally-managed --compile:
    running install
    running build
    running build_py
    creating build
    creating build/lib.linux-x86_64-2.7
    creating build/lib.linux-x86_64-2.7/lxc
    copying lxc/__init__.py -> build/lib.linux-x86_64-2.7/lxc
    running build_ext
    building '_lxc' extension
    creating build/temp.linux-x86_64-2.7
    gcc -pthread -fno-strict-aliasing -fmessage-length=0 -grecord-gcc-switches -O2 -Wall -D_FORTIFY_SOURCE=2 -fstack-protector -funwind-tables -fasynchronous-unwind-tables -g -DNDEBUG -fmessage-length=0 -grecord-gcc-switches -O2 -Wall -D_FORTIFY_SOURCE=2 -fstack-protector -funwind-tables -fasynchronous-unwind-tables -g -DOPENSSL_LOAD_CONF -fPIC -I/usr/include/python2.7 -c lxc.c -o build/temp.linux-x86_64-2.7/lxc.o
    lxc.c:25:20: fatal error: Python.h: No such file or directory
     #include <Python.h>
                        ^
    compilation terminated.
    error: command 'gcc' failed with exit status 1
    
    ----------------------------------------
Command "/usr/bin/python -c "import setuptools, tokenize;__file__='/tmp/pip-build-ivXpM7/lxc-python2/setup.py';exec(compile(getattr(tokenize, 'open', open)(__file__).read().replace('\r\n', '\n'), __file__, 'exec'))" install --record /tmp/pip-U4pDvj-record/install-record.txt --single-version-externally-managed --compile" failed with error code 1 in /tmp/pip-build-ivXpM7/lxc-python2

$ pip install lxc-python2
Collecting lxc-python2
  Using cached lxc-python2-0.1.zip
Installing collected packages: lxc-python2
  Running setup.py install for lxc-python2
    Complete output from command /usr/bin/python -c "import setuptools, tokenize;__file__='/tmp/pip-build-8Nfx30/lxc-python2/setup.py';exec(compile(getattr(tokenize, 'open', open)(__file__).read().replace('\r\n', '\n'), __file__, 'exec'))" install --record /tmp/pip-l7QFQg-record/install-record.txt --single-version-externally-managed --compile:
    running install
    running build
    running build_py
    creating build
    creating build/lib.linux-x86_64-2.7
    creating build/lib.linux-x86_64-2.7/lxc
    copying lxc/__init__.py -> build/lib.linux-x86_64-2.7/lxc
    running build_ext
    building '_lxc' extension
    creating build/temp.linux-x86_64-2.7
    gcc -pthread -fno-strict-aliasing -fmessage-length=0 -grecord-gcc-switches -O2 -Wall -D_FORTIFY_SOURCE=2 -fstack-protector -funwind-tables -fasynchronous-unwind-tables -g -DNDEBUG -fmessage-length=0 -grecord-gcc-switches -O2 -Wall -D_FORTIFY_SOURCE=2 -fstack-protector -funwind-tables -fasynchronous-unwind-tables -g -DOPENSSL_LOAD_CONF -fPIC -I/usr/include/python2.7 -c lxc.c -o build/temp.linux-x86_64-2.7/lxc.o
    lxc.c:27:30: fatal error: lxc/lxccontainer.h: No such file or directory
     #include <lxc/lxccontainer.h>
                                  ^
    compilation terminated.
    error: command 'gcc' failed with exit status 1
    
    ----------------------------------------
Command "/usr/bin/python -c "import setuptools, tokenize;__file__='/tmp/pip-build-8Nfx30/lxc-python2/setup.py';exec(compile(getattr(tokenize, 'open', open)(__file__).read().replace('\r\n', '\n'), __file__, 'exec'))" install --record /tmp/pip-l7QFQg-record/install-record.txt --single-version-externally-managed --compile" failed with error code 1 in /tmp/pip-build-8Nfx30/lxc-python2

set_config_item() always returns False (unicode issue)

Python 2.7.8
Debian Wheezy - 3.2.0-4-amd64

Issue

Setting a variable with set_config_item() returns False unconditionally

Explanation

https://github.com/lxc/python2-lxc/blob/master/lxc/__init__.py#L385

This issue is due to:

• the value to be set is unicode or ascii depending on what is fed to the method
• the new_value being returned by get_config_item() is unicode

The following branch then does not work, since in python2 isinstance(<type 'unicode'>, str) returns False, the new value is discarded and the previous value set again.

if (isinstance(value, str) and isinstance(new_value, str) and
                value == new_value): <- Path that should be taken
            return True
            [...]
        elif old_value: <- Path always taken
            set_key(key, old_value)
            return False
        else:
            self.clear_config_item(key)
            return False

Proposed fix

• Cast the value to be set to unicode()
• Change isinstance(value, str) to isinstance(value, unicode) in the branch

set_config_item always appends

Invoking set_config_item appears to always append values rather than updating a matching key.

Once can recreate this with:

import lxc, subprocess
container = lxc.Container('foo')
container.set_config_path("/tmp")
subprocess.check_call("mkdir -p /tmp/foo".split())
subprocess.check_call("touch /tmp/foo/config".split())
container.set_config_item('lxc.utsname', 'foo')
container.set_config_item('lxc.utsname', 'bar')
container.save_config()
print subprocess.check_output("cat /tmp/foo/config".split())

Expect that config contain only:

lxc.utsname = foo

Actual Output:

lxc.utsname = foo
lxc.utsname = bar

Dependencies ?

Hi,

I tried to install your module via pip in order to manage lxc containers through ansible. I guessed I needed the pyhton-dev (and lxc obviously) package, but everytime I

pip install lxc-python2

I run into this error

lxc.c:27:30: fatal error: lxc/lxccontainer.h: No such file or directory

Am I missing something ?

PS : environment is a vagrant VM running debian jessie (debian/jessie64)

Upload to pypi

Please, make it available on the pypi platform. As this is the official binding for python2 other projects as Ansible use it (for lxc_container module), but there's no way just to make it all work out of the box. No way to include this library as a dependency for apt or pip.
Thanks.

Ansible Extras support for LXC 2?

does this work for Ansible 2 on Xenial and LXC 2?

TASK [ansible-role-lxc : Create a started container] ***************************
fatal: [arizblah.blahblah.net]: FAILED! => {"changed": false, "failed": true, "msg": "Failed to find required executable lxc-create"}

Issue running with unprivilege containers

Hi,

I'm trying to use ansible to create lxc unprivileged containers.
It uses python2-lxc but i can't seem to find a way to pass the -t download
option for the create execution.

My example execution runs:

/usr/bin/lxc-create --name test001 --config ~/.config/lxc/default.conf --template ubuntu --bdev dir --logfile /home/rramos/lxc-test001.log --logpriority INFO -- -d ubuntu -r xenial -a amd64

but it should run:

/usr/bin/lxc-create -t download --name test001 --config ~/.config/lxc/default.conf  --logfile /home/rramos/lxc-test001.log --logpriority INFO -- -d ubuntu -r xenial -a amd64

Is there a way to indicate the create method that should run in unpriviledge mode ?

Info on setting unprivileged-containers:

• https://www.stgraber.org/2014/01/17/lxc-1-0-unprivileged-containers/

Could you please branch the project?

Right now there is only one master branch. If the code is stable enough, is it possible for you to branch it like the python3 module? The reason is that I need a stable deployment process to ping to a specific version/branch. Many thanks!

LXC 1.1.3

Hi,

I use the lxc stable ppa on Ubuntu trusty. Since LXC 1.1.3 i can't create container:

The template args failed,

# ps ax | grep 17958
/bin/sh /usr/share/lxc/templates/lxc-download --path=/var/lib/lxc/ubuntu-trusty-amd64-default --name=ubuntu-trusty-amd64-default --rootfs=/var/lib/lxc/ubuntu-trusty-amd64-default/rootfs  н??L?

The source arguments is {"dist": "ubuntu", "release": "trusty", "arch": "amd64", "variant": "default"}
The final arguments is н??L?

Thanks,

python2-lxc cannot be installed on MacOS

At this moment it seems impossible to install python2-lxc on MacOS because there is no brew package that would install the header files needed by the package.

The lxc package does not contain them Homebrew/brew#5326 (comment)

Another alternative would be to start bulding and publishign binary wheels.

python3 support

Ansible task run with python3 interpreter fails when the lxc_container module is involved:

name 'xrange' is not defined

The complete log:

fatal: [x.x.x.x]: FAILED! => {"changed": false, "failed": true, "module_stderr": "Shared connection to x.x.x.x closed.\r\n", "module_stdout": "Traceback (most recent call last):\r\n  File \"/tmp/ansible_6mkfkgb_/ansible_module_lxc_container.py\", line 1767, in <module>\r\n    main()\r\n  File \"/tmp/ansible_6mkfkgb_/ansible_module_lxc_container.py\", line 1761, in main\r\n    lxc_manage.run()\r\n  File \"/tmp/ansible_6mkfkgb_/ansible_module_lxc_container.py\", line 1641, in run\r\n    action()\r\n  File \"/tmp/ansible_6mkfkgb_/ansible_module_lxc_container.py\", line 1161, in _started\r\n    elif not self._container_startup():\r\n  File \"/tmp/ansible_6mkfkgb_/ansible_module_lxc_container.py\", line 961, in _container_startup\r\n    for _ in xrange(timeout):\r\nNameError: name 'xrange' is not defined\r\n", "msg": "MODULE FAILURE", "rc": 0}

Segfault with custom config-path on debian stretch

You can set an alternative default path in /etc/lxc/lxc.conf and it will pick that up and use it. You can specify a path for list_containers() and that works too. If you try to create a Container object then you get a segmentation fault. The value you provide for the path makes no difference (can be '/var/lib/lxc' or '/foo/bar').

I tested this as root.

The Python 3 version of this library works OK.

I could reproduce this with the debian package and installing via pip (which compiled against liblxc1 headers). Also with the package on ubuntu 18.04

Apologies for not providing a patch but Python is not my area of expertise and my guess is that this lies somewhere in the binding of the pathname to the C library.

# python
Python 2.7.13 (default, Nov 24 2017, 17:33:09) 
[GCC 6.3.0 20170516] on linux2
Type "help", "copyright", "credits" or "license" for more information.
>>> import lxc
>>> lxc.list_containers(config_path='/var/lib/lxc')
(u'elm', u'jessie-0', u'munin-test')
>>> c1=lxc.Container(name=u'elm')
>>> c2=lxc.Container(name=u'elm', config_path=u'/var/lib/lxc')
Segmentation fault

Python 2.7 bindings broke with recent Ubuntu update for liblxc1

I'm afraid the Python 2.7 bindings are broken with some recent update for liblxc1 on Ubuntu. I can't give the exact date or version when this started happening, but I know the following worked a few months ago, and now it no longer does:

IPython 2.3.0 -- An enhanced Interactive Python.
?         -> Introduction and overview of IPython's features.
%quickref -> Quick reference.
help      -> Python's own help system.
object?   -> Details about 'object', use 'object??' for extra details.

In [1]: import lxc

In [2]: container = lxc.Container("mycontainer")

In [3]: container.get_ips()
Segmentation fault

If I run the same thing in ipython3, using the in-tree Python 3 bindings, all is well.

Now I realize this is probably really low priority, but as it happens that this breakage blocks the inclusion of an otherwise very useful LXC connection plugin for Ansible; see ansible/ansible#13145 for details.

Ansible, for "reasons" explained here, can't run in a Python 3-only environment. Which is silly and not lxc's problem, but if we could get this module to work again in Python 2.7, that would be a huge win.

Any thoughts on the above, @stgraber? I'd much appreciate your feedback. Thanks!

Is this project up to date?

I tried to build it, ran into following error. Please help. Thanks!

$ python setup.py build
running build
running build_py
creating build
creating build/lib.linux-x86_64-2.7
creating build/lib.linux-x86_64-2.7/lxc
copying lxc/init.py -> build/lib.linux-x86_64-2.7/lxc
running build_ext
building '_lxc' extension
creating build/temp.linux-x86_64-2.7
x86_64-linux-gnu-gcc -pthread -fno-strict-aliasing -DNDEBUG -g -fwrapv -O2 -Wall -Wstrict-prototypes -fPIC -I/usr/include/python2.7 -c lxc.c -o build/temp.linux-x86_64-2.7/lxc.o
lxc.c:27:30: fatal error: lxc/lxccontainer.h: No such file or directory
#include <lxc/lxccontainer.h>
^
compilation terminated.
error: command 'x86_64-linux-gnu-gcc' failed with exit status 1

Include license file

It would be nice if a license file was included in the source explicitly. It would help downstream packagers in providing this to their users ;)