``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.

.. code-block:: none

  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.
