Introducing the python LXC API

One of our top goals for LXC upstream work during the Ubuntu 12.10 development cycle was reworking the LXC library and turn it from a private library mostly used by the other lxc-* commands into something that’s easy for developers to work with and is accessible from other languages with some bindings.

Although the current implementation isn’t complete enough to consider the API stable and some changes will still happen to it over the months to come, we have pushed the initial implementation to the LXC staging branch on github and put it into the lxc package of Ubuntu 12.10.

The initial version comes with a python3 binding packaged as python3-lxc, that’s what I’ll use now to give you an idea of what’s possible with the API. Note that as we don’t have full user namespaces support at the moment, any code using the LXC API needs to run as root.

First, let’s start with the basics, creating a container, starting it, getting its IP and stopping it:

#!/usr/bin/python3
import lxc
container = lxc.Container("my_container")
container.create("ubuntu", {"release": "precise", "architecture": "amd64"})
container.start()
print(container.get_ips(timeout=10))
container.shutdown(timeout=10)
container.destroy()

So, pretty simple.
It’s also possible to modify the container’s configuration using the .get_config_item(key) and .set_config_item(key, value) functions. For those keys supporting multiple values, a list will be returned and a list will be accepted as a value by .set_config_item.

Network configuration can be accessed through the .network property which is essentially a list of all network interfaces of the container, properties can be changed that way or through .set_config_item and saved to the config file with .save_config().

The API isn’t terribly well documented at this point, help messages are present for all functions but there’s no generated html help yet.

To get a better idea of the functions exported by the API, you may want to look at the API test script. This script uses all the functions and properties exported by the python module so it should be a reasonable reference.

About Stéphane Graber

Project leader of Linux Containers, Linux hacker, Ubuntu core developer, conference organizer and speaker.
This entry was posted in Canonical voices, LXC, Planet Ubuntu and tagged . Bookmark the permalink.

11 Responses to Introducing the python LXC API

  1. PotHix says:

    Æ!!

    Cool! Tried it on archlinux with python3 compiling lxc from source.

    Following your script, when I tried:
    container.create(“ubuntu”, {“release”: “precise”, “architecture”: “amd64”})

    I got: lxc_container: container creation template for pothix exited with 1

    So I tried:
    container.create(“debian”)

    And it worked fine. But container.start() just returns False. =\

    Destroy command is working fine.

    Thanks for submitting this!

    1. You should be able to get some more details on what went wrong in /var/log/lxccontainer.log, look for ERROR lines.

      1. PotHix says:

        Æ!!

        I think that it’s missing my container name here:

        lxc_container 1349111538.849 ERROR lxc_conf – No such file or directory – failed to access to ‘/usr/lib/lxc/rootfs’, check it is present

        What kind of files should be on this rootfs? The container’s rootfs for archlinux was created on “/var/lib/lxc/container_name/rootfs”.

        Thanks for your help.

        1. /usr/lib/lxc/rootfs needs to exist as an empty directory on your system.

          That’s the directory temporarily used by lxc to prepare the rootfs of your container.

          “sudo mkdir -p /usr/lib/lxc/rootfs/” then try start your container again, it should work, or at least give a different error.

  2. xuanmingyi says:

    import lxc
    c=lxc.Container(“a”)
    c.create(“ubuntu”)

    in /var/lib/lxccontainer.log
    lxc_container: No such file or directory – failed to create container path for aa

    how to deal with the error?

    1. Could it be that you’re somehow missing /var/lib/lxc or /var/cache/lxc ?
      If so, try to create them and retry.

  3. Codefendant says:

    Works great, at least when I dont use architecture when creating the container. I also get:
    “lxc_container: container creation template for test exited with 1”
    I get the impression that is the template script failing, not python3-lxc.

    When do you think this will be stable? Would love to start using practically…

  4. Valentin says:

    Any chances I might get this to work under python2.7?

    1. No, the C binding for lxc is python3 only and we don’t intend in supporting python 2.x in there as it’d complicate things quite a bit.

  5. peter says:

    Hi,

    running
    sudo steam-lxc create
    on kubuntu 13.10 with kernel 3.12 I’ve encountered:
    ontainer successfuly created
    lxc_container: failed to clone(0x8000): Invalid argument
    lxc_container: Invalid argument – failed to create subprocess
    lxc_container: failed to clone(0x8000): Invalid argument
    lxc_container: Invalid argument – failed to create subprocess
    lxc_container: failed to clone(0x8000): Invalid argument
    lxc_container: Invalid argument – failed to create subprocess
    lxc_container: failed to clone(0x8000): Invalid argument
    lxc_container: Invalid argument – failed to create subprocess
    lxc_container: failed to clone(0x8000): Invalid argument
    lxc_container: Invalid argument – failed to create subprocess
    lxc_container: failed to clone(0x8000): Invalid argument
    lxc_container: Invalid argument – failed to create subprocess
    lxc_container: failed to clone(0x8000): Invalid argument
    lxc_container: Invalid argument – failed to create subprocess
    lxc_container: failed to clone(0x8000): Invalid argument
    lxc_container: Invalid argument – failed to create subprocess
    lxc_container: failed to clone(0x8000): Invalid argument
    lxc_container: Invalid argument – failed to create subprocess
    lxc_container: failed to clone(0x8000): Invalid argument
    lxc_container: Invalid argument – failed to create subprocess
    lxc_container: failed to clone(0x8000): Invalid argument
    lxc_container: Invalid argument – failed to create subprocess
    lxc_container: failed to clone(0x8000): Invalid argument
    lxc_container: Invalid argument – failed to create subprocess
    lxc_container: failed to clone(0x8000): Invalid argument
    lxc_container: Invalid argument – failed to create subprocess
    lxc_container: failed to clone(0x8000): Invalid argument
    lxc_container: Invalid argument – failed to create subprocess
    lxc_container: failed to clone(0x8000): Invalid argument
    lxc_container: Invalid argument – failed to create subprocess
    lxc_container: failed to clone(0x8000): Invalid argument
    lxc_container: Invalid argument – failed to create subprocess
    lxc_container: failed to clone(0x8000): Invalid argument
    lxc_container: Invalid argument – failed to create subprocess
    lxc_container: failed to clone(0x8000): Invalid argument
    lxc_container: Invalid argument – failed to create subprocess

    Looks like problem is in run_command(self, command, env={}, root=False) method, with starting commands in container using lxc python API
    self.container.attach_wait(
    lxc.attach_run_command, command,
    extra_env_vars=env)

    What should be correct API call for this configuration?
    Thank you.
    Regards.
    Peter

Leave a Reply to Stéphane Graber Cancel reply

Your email address will not be published. Required fields are marked *

This site uses Akismet to reduce spam. Learn how your comment data is processed.