CONSFIGURATOR.PROPERTY.LXC

API reference

Properties and combinators

Property: LXC:INSTALLED

(lxc:installed)

Install the LXC userspace tools.

Property: LXC:USER-CONTAINER-STARTED

(lxc:user-container-started host &optional owner)

Ensure the LXC unprivileged container for the host designated by HOST owned by OWNER, defaulting to the current user, is started. (I.e., if HOST is a string, ensure the container named HOST is started; if HOST is a HOST value, start the container whose name is HOST’s hostname.)

Property: LXC:USER-CONTAINER-STOPPED

(lxc:user-container-stopped host &optional owner)

Ensure the LXC unprivileged container for the host designated by HOST owned by OWNER, defaulting to the current user, is stopped.

Macro: LXC:WHEN-USER-CONTAINER-RUNNING

(lxc:when-user-container-running host &body propapps)

Apply PROPAPPS only when the unprivileged LXC for the host designated by HOST and owned by OWNER, defaulting to the current user, is already started.

Property: LXC:USER-CONTAINERS-AUTOSTART

(lxc:user-containers-autostart user)

Install a systemd user unit for USER to autostart all LXC user containers owned by that user which have lxc.start.auto turned on. Also ensures that lingering is enabled for USER, so the user unit triggers at system boot.

A limitation of the current implementation is that it assumes XDG_CONFIG_HOME is ~/.config.

Property: LXC:USERNET-VETH-USABLE-BY

(lxc:usernet-veth-usable-by user &optional interface count)

Ensure that USER is allowed to attach up to COUNT unprivileged LXCs to the LXC-managed bridge INTERFACE.

As a special case, INTERFACE may also be “none”, which gives USER permission to create veth pairs where the peer outside the container is not attached to any bridge.

Property: LXC:USER-CONTAINER-FOR

(lxc:user-container-for options user host &optional additional-properties)

Build an unprivileged, non-system-wide LXC container for HOST. Must be applied using a connection chain which grants root access, primarily for the sake of bootstrapping the container’s root filesystem. Once built, however, the container will be launched by USER, which should be non-root.

If the container has already been bootstrapped and is running at the time this property is applied, enter the container and apply all its properties.

OPTIONS is a plist of keyword parameters:

  • :AUTOSTART – Lisp boolean corresponding to lxc.start.auto in the container’s config file, and also determines whether applying this property attempts to start the container. Defaults to nil. See also LXC:USER-CONTAINERS-AUTOSTART.

  • :PRELUDE-LINES – additional lines to prepend to the container’s configuration file, before the lines generated by this property. See lxc.container.conf(5). The default value is usually sufficient; if you add lines, you will probably want to include the lines from the default value too.

  • :ADDITIONAL-LINES – additional lines to append to the container’s configuration file, after the lines generated by this property. See lxc.container.conf(5). In most cases you will need to include, at a minimum, lines setting up a network interface for the container. The default value serves as an example of a standard way to do this; if you use them unmodified, you will also need to apply LXC:USERNET-VETH-USABLE-BY for USER before this property.

  • :UID-MAPS – a list of the form (INSIDE OUTSIDE COUNT), or a list of such lists, specifying the subordinate UIDs for the container’s user namespace. OUTSIDE is the beginning of a UID range, as seen from outside the container, and INSIDE is the UID that OUTSIDE is mapped to, as seen from inside the container. COUNT is the number of consecutive UIDs mapped. This property will ensure that USER has permission to use that range of UIDs by updating /etc/subuid if necessary.

As a special case, if NIL, instead use the first range of UIDs assigned to
USER in /etc/subuid, with a value of zero for INSIDE, and do not modify
/etc/subuid.  (If you want to use the first range of UIDs assigned to USER
in /etc/subuid and also other ranges, you must specify them all explicitly
and cannot rely on this special case.)

It is usually sufficient not to specify this parameter, as distribution
scripts automatically add an entry to /etc/subuid for each regular user,
and most containers use a value of zero for INSIDE.

- :GID-MAPS -- as :UID-MAPS, but for GIDs and /etc/subgid.

- :CHROOT-OPTIONS -- passed on to CHROOT:OS-BOOTSTRAPPED-FOR, which see.

A limitation of the current implementation is that the root filesystem of the container is always created under ~/.local/share/lxc/HOSTNAME where HOSTNAME is the hostname of HOST, ignoring any configured XDG_DATA_HOME for USER.

Internally we use setns(2) to enter the container. See “Connections which use setns(2) to enter containers” in the Consfigurator manual for security implications.

Property: LXC:USER-CONTAINER

(lxc:user-container options user properties)

Like LXC:USER-CONTAINER-FOR but define a new host using PROPERTIES.

Utility functions

Function: LXC:LXC-LS

(lxc:lxc-ls &optional owner &rest args)

Return the lines of output from lxc-ls(1) called with ARGS and for OWNER.