# salt.modules.lxc

Control Linux Containers via Salt

depends:

  lxc package for distribution

lxc >= 1.0 (even beta alpha) is required

salt.modules.lxc.add_veth(name, interface_name, bridge=None, path=None)

  Add a veth to a container. Note : this function doesn't update the container config, just add the interface at runtime

  name

    Name of the container

  interface_name

    Name of the interface in the container

  bridge

    Name of the bridge to attach the interface to (facultative)

  CLI Examples:

      salt '*' lxc.add_veth container_name eth1 br1
      salt '*' lxc.add_veth container_name eth1

salt.modules.lxc.apply_network_profile(name, network_profile, nic_opts=None, path=None)

  Added in version 2015.5.0.

  Apply a network profile to a container

  network_profile

    profile name or default values (dict)

  nic_opts

    values to override in defaults (dict) indexed by nic card names

  path

    path to the container parent

    Added in version 2015.8.0.

  CLI Examples:

      salt 'minion' lxc.apply_network_profile web1 centos
      salt 'minion' lxc.apply_network_profile web1 centos \
              nic_opts="{'eth0': {'mac': 'xx:xx:xx:xx:xx:xx'}}"
      salt 'minion' lxc.apply_network_profile web1 \
              "{'eth0': {'mac': 'xx:xx:xx:xx:xx:yy'}}"
              nic_opts="{'eth0': {'mac': 'xx:xx:xx:xx:xx:xx'}}"

  The special case to disable use of ethernet nics:

      salt 'minion' lxc.apply_network_profile web1 centos \
              "{eth0: {disable: true}}"

salt.modules.lxc.attachable(name, path=None)

  Return True if the named container can be attached to via the lxc-attach command

  path

    path to the container parent default: /var/lib/lxc (system default)

    Added in version 2015.8.0.

  CLI Example:

      salt 'minion' lxc.attachable ubuntu

salt.modules.lxc.bootstrap(name, config=None, approve_key=True, install=True, pub_key=None, priv_key=None, bootstrap_url=None, force_install=False, unconditional_install=False, path=None, bootstrap_delay=None, bootstrap_args=None, bootstrap_shell=None)

  Install and configure salt in a container.

  config

    Minion configuration options. By default, the `master` option is set to the target host's master.

  approve_key

    Request a pre-approval of the generated minion key. Requires that the salt-master be configured to either auto-accept all keys or expect a signing request from the target host. Default: `True`

  path

    path to the container parent default: /var/lib/lxc (system default)

    Added in version 2015.8.0.

  pub_key

    Explicit public key to pressed the minion with (optional). This can be either a filepath or a string representing the key

  priv_key

    Explicit private key to pressed the minion with (optional). This can be either a filepath or a string representing the key

  bootstrap_delay

    Delay in seconds between end of container creation and bootstrapping. Useful when waiting for container to obtain a DHCP lease.

    Added in version 2015.5.0.

  bootstrap_url

    url, content or filepath to the salt bootstrap script

  bootstrap_args

    salt bootstrap script arguments

  bootstrap_shell

    shell to execute the script into

  install

    Whether to attempt a full installation of salt-minion if needed.

  force_install

    Force installation even if salt-minion is detected, this is the way to run vendor bootstrap scripts even if a salt minion is already present in the container

  unconditional_install

    Run the script even if the container seems seeded

  CLI Examples:

      salt 'minion' lxc.bootstrap container_name [config=config_data] \
              [approve_key=(True|False)] [install=(True|False)]

salt.modules.lxc.clone(name, orig, profile=None, network_profile=None, nic_opts=None, **kwargs)

  Create a new container as a clone of another container

  name

    Name of the container

  orig

    Name of the original container to be cloned

  profile

    Profile to use in container cloning (see `lxc.get_container_profile`). Values in a profile will be overridden by the Container Cloning Arguments listed below.

  path

    path to the container parent directory default: /var/lib/lxc (system)

    Added in version 2015.8.0.

  Container Cloning Arguments

  snapshot

    Use Copy On Write snapshots (LVM)

  size1G

    Size of the volume to create. Only applicable if `backing=lvm`.

  backing

    The type of storage to use. Set to `lvm` to use an LVM group. Defaults to filesystem within /var/lib/lxc.

  network_profile

    Network profile to use for container

    Added in version 2015.8.0.

  nic_opts

    give extra opts overriding network profile values

    Added in version 2015.8.0.

  CLI Examples:

      salt '*' lxc.clone myclone orig=orig_container
      salt '*' lxc.clone myclone orig=orig_container snapshot=True

salt.modules.lxc.cloud_init(name, vm_=None, **kwargs)

  Thin wrapper to lxc.init to be used from the saltcloud lxc driver

  name

    Name of the container may be None and then guessed from saltcloud mapping

  vm_

    saltcloud mapping defaults for the vm

  CLI Example:

      salt '*' lxc.cloud_init foo

salt.modules.lxc.cloud_init_interface(name, vm_=None, **kwargs)

  Interface between salt.cloud.lxc driver and lxc.init `vm_` is a mapping of vm opts in the salt.cloud format as documented for the lxc driver.

  This can be used either:

  - from the salt cloud driver

  - because you find the argument to give easier here than using directly lxc.init

  Warning

  BE REALLY CAREFUL CHANGING DEFAULTS !!! IT'S A RETRO COMPATIBLE INTERFACE WITH THE SALT CLOUD DRIVER (ask kiorky).

  name

    name of the lxc container to create

  pub_key

    public key to preseed the minion with. Can be the keycontent or a filepath

  priv_key

    private key to preseed the minion with. Can be the keycontent or a filepath

  path

    path to the container parent directory (default: /var/lib/lxc)

    Added in version 2015.8.0.

  profile

    profile selection

  network_profile

    network profile selection

  nic_opts

    per interface settings compatibles with network profile (ipv4/ipv6/link/gateway/mac/netmask)

    eg:

        - {'eth0': {'mac': '00:16:3e:01:29:40',
                    'gateway': None, (default)
                    'link': 'br0', (default)
                    'gateway': None, (default)
                    'netmask': '', (default)
                    'ip': '22.1.4.25'}}

  unconditional_install

    given to lxc.bootstrap (see relative doc)

  force_install

    given to lxc.bootstrap (see relative doc)

  config

    any extra argument for the salt minion config

  dnsservers

    list of DNS servers to set inside the container

  dns_via_dhcp

    do not set the dns servers, let them be set by the dhcp.

  autostart

    autostart the container at boot time

  password

    administrative password for the container

  bootstrap_delay

    delay before launching bootstrap script at Container init

  Warning

  Legacy but still supported options:

  from_container

    which container we use as a template when running lxc.clone

  image

    which template do we use when we are using lxc.create. This is the default mode unless you specify something in from_container

  backing

    which backing store to use. Values can be: overlayfs, dir(default), lvm, zfs, brtfs

  fstype

    When using a blockdevice level backing store, which filesystem to use on

  size

    When using a blockdevice level backing store, which size for the filesystem to use on

  snapshot

    Use snapshot when cloning the container source

  vgname

    if using LVM: vgname

  lvname

    if using LVM: lvname

  thinpool:

    if using LVM: thinpool

  ip

    ip for the primary nic

  mac

    mac address for the primary nic

  netmask

    netmask for the primary nic (24) = `vm_.get('netmask', '24')`

  bridge

    bridge for the primary nic (lxcbr0)

  gateway

    network gateway for the container

  additional_ips

    additional ips which will be wired on the main bridge (br0) which is connected to internet. Be aware that you may use manual virtual mac addresses providen by you provider (online, ovh, etc). This is a list of mappings {ip: '', mac: '', netmask:''} Set gateway to None and an interface with a gateway to escape from another interface that eth0. eg:

        - {'mac': '00:16:3e:01:29:40',
           'gateway': None, (default)
           'link': 'br0', (default)
           'netmask': '', (default)
           'ip': '22.1.4.25'}

  users

    administrative users for the container default: [root] and [root, ubuntu] on ubuntu

  default_nic

    name of the first interface, you should really not override this

  CLI Example:

      salt '*' lxc.cloud_init_interface foo

salt.modules.lxc.copy_to(name, source, dest, overwrite=False, makedirs=False, path=None)

  Changed in version 2015.8.0: Function renamed from `lxc.cp` to `lxc.copy_to` for consistency with other container types. `lxc.cp` will continue to work, however. For versions 2015.2.x and earlier, use `lxc.cp`.

  Copy a file or directory from the host into a container

  name

    Container name

  source

    File to be copied to the container

  path

    path to the container parent default: /var/lib/lxc (system default)

    Added in version 2015.8.0.

  dest

    Destination on the container. Must be an absolute path.

    Changed in version 2015.5.0: If the destination is a directory, the file will be copied into that directory.

  overwriteFalse

    Unless this option is set to `True`, then if a file exists at the location specified by the `dest` argument, an error will be raised.

    Added in version 2015.8.0.

  makedirs : False

  > Create the parent directory on the container if it does not already exist.

  > Added in version 2015.5.0.

  CLI Example:

      salt 'minion' lxc.copy_to /tmp/foo /root/foo
      salt 'minion' lxc.cp /tmp/foo /root/foo

salt.modules.lxc.cp(name, source, dest, overwrite=False, makedirs=False, path=None)

  This function is an alias of `copy_to`.

  > Changed in version 2015.8.0: Function renamed from `lxc.cp` to `lxc.copy_to` for consistency with other container types. `lxc.cp` will continue to work, however. For versions 2015.2.x and earlier, use `lxc.cp`.

  > Copy a file or directory from the host into a container

  > name

  >   Container name

  > source

  >   File to be copied to the container

  > path

  >   path to the container parent default: /var/lib/lxc (system default)

  >   Added in version 2015.8.0.

  > dest

  >   Destination on the container. Must be an absolute path.

  >   Changed in version 2015.5.0: If the destination is a directory, the file will be copied into that directory.

  > overwriteFalse

  >   Unless this option is set to `True`, then if a file exists at the location specified by the `dest` argument, an error will be raised.

  >   Added in version 2015.8.0.

  > makedirs : False

  > > Create the parent directory on the container if it does not already exist.

  > > Added in version 2015.5.0.

  > CLI Example:

  >     salt 'minion' lxc.copy_to /tmp/foo /root/foo
  >     salt 'minion' lxc.cp /tmp/foo /root/foo

salt.modules.lxc.create(name, config=None, profile=None, network_profile=None, nic_opts=None, **kwargs)

  Create a new container.

  name

    Name of the container

  config

    The config file to use for the container. Defaults to system-wide config (usually in /etc/lxc/lxc.conf).

  profile

    Profile to use in container creation (see `lxc.get_container_profile`). Values in a profile will be overridden by the Container Creation Arguments listed below.

  network_profile

    Network profile to use for container

    Added in version 2015.5.0.

  Container Creation Arguments

  template

    The template to use. For example, `ubuntu` or `fedora`. For a full list of available templates, check out the `lxc.templates` function.

    Conflicts with the `image` argument.

    Note

    The `download` template requires the following three parameters to be defined in `options`:

    - dist - The name of the distribution

    - release - Release name/version

    - arch - Architecture of the container

    The available images can be listed using the `lxc.images` function.

  options

    Template-specific options to pass to the lxc-create command. These correspond to the long options (ones beginning with two dashes) that the template script accepts. For example:

        options='{"dist": "centos", "release": "6", "arch": "amd64"}'

    For available template options, refer to the lxc template scripts which are usually located under `/usr/share/lxc/templates`, or run `lxc-create -t <template> -h`.

  image

    A tar archive to use as the rootfs for the container. Conflicts with the `template` argument.

  backing

    The type of storage to use. Set to `lvm` to use an LVM group. Defaults to filesystem within /var/lib/lxc.

  fstype

    Filesystem type to use on LVM logical volume

  size1G

    Size of the volume to create. Only applicable if `backing=lvm`.

  vgnamelxc

    Name of the LVM volume group in which to create the volume for this container. Only applicable if `backing=lvm`.

  lvname

    Name of the LVM logical volume in which to create the volume for this container. Only applicable if `backing=lvm`.

  thinpool

    Name of a pool volume that will be used for thin-provisioning this container. Only applicable if `backing=lvm`.

  nic_opts

    give extra opts overriding network profile values

  path

    parent path for the container creation (default: /var/lib/lxc)

  zfsroot

    Name of the ZFS root in which to create the volume for this container. Only applicable if `backing=zfs`. (default: tank/lxc)

    Added in version 2015.8.0.

salt.modules.lxc.destroy(name, stop=False, path=None)

  Destroy the named container.

  Warning

  Destroys all data associated with the container.

  path

    path to the container parent directory (default: /var/lib/lxc)

    Added in version 2015.8.0.

  stopFalse

    If `True`, the container will be destroyed even if it is running/frozen.

    Changed in version 2015.5.0: Default value changed to `False`. This more closely matches the behavior of `lxc-destroy(1)`, and also makes it less likely that an accidental command will destroy a running container that was being used for important things.

  CLI Examples:

      salt '*' lxc.destroy foo
      salt '*' lxc.destroy foo stop=True

salt.modules.lxc.edit_conf(conf_file, out_format='simple', read_only=False, lxc_config=None, **kwargs)

  Edit an LXC configuration file. If a setting is already present inside the file, its value will be replaced. If it does not exist, it will be appended to the end of the file. Comments and blank lines will be kept in-tact if they already exist in the file.

  out_format:

    Set to simple if you need backward compatibility (multiple items for a simple key is not supported)

  read_only:

    return only the edited configuration without applying it to the underlying lxc configuration file

  lxc_config:

    List of dict containning lxc configuration items For network configuration, you also need to add the device it belongs to, otherwise it will default to eth0. Also, any change to a network parameter will result in the whole network reconfiguration to avoid mismatchs, be aware of that !

  After the file is edited, its contents will be returned. By default, it will be returned in `simple` format, meaning an unordered dict (which may not represent the actual file order). Passing in an `out_format` of `commented` will return a data structure which accurately represents the order and content of the file.

  CLI Example:

      salt 'minion' lxc.edit_conf /etc/lxc/mycontainer.conf \
          out_format=commented lxc.network.type=veth
      salt 'minion' lxc.edit_conf /etc/lxc/mycontainer.conf \
          out_format=commented \
          lxc_config="[{'lxc.network.name': 'eth0', \
                        'lxc.network.ipv4': '1.2.3.4'},
                       {'lxc.network.name': 'eth2', \
                        'lxc.network.ipv4': '1.2.3.5',\
                        'lxc.network.gateway': '1.2.3.1'}]"

salt.modules.lxc.exists(name, path=None)

  Returns whether the named container exists.

  path

    path to the container parent directory (default: /var/lib/lxc)

    Added in version 2015.8.0.

  CLI Example:

      salt '*' lxc.exists name

salt.modules.lxc.freeze(name, **kwargs)

  Freeze the named container

  path

    path to the container parent directory default: /var/lib/lxc (system)

    Added in version 2015.8.0.

  startFalse

    If `True` and the container is stopped, the container will be started before attempting to freeze.

    Added in version 2015.5.0.

  use_vt

    run the command through VT

    Added in version 2015.8.0.

  CLI Example:

      salt '*' lxc.freeze name

salt.modules.lxc.get_container_profile(name=None, **kwargs)

  Added in version 2015.5.0.

  Gather a pre-configured set of container configuration parameters. If no arguments are passed, an empty profile is returned.

  Profiles can be defined in the minion or master config files, or in pillar or grains, and are loaded using `config.get`. The key under which LXC profiles must be configured is `lxc.container_profile.profile_name`. An example container profile would be as follows:

      lxc.container_profile:
        ubuntu:
          template: ubuntu
          backing: lvm
          vgname: lxc
          size: 1G

  Parameters set in a profile can be overridden by passing additional container creation arguments (such as the ones passed to `lxc.create`) to this function.

  A profile can be defined either as the name of the profile, or a dictionary of variable names and values. See the LXC Tutorial for more information on how to use LXC profiles.

  CLI Example:

      salt-call lxc.get_container_profile centos
      salt-call lxc.get_container_profile ubuntu template=ubuntu backing=overlayfs

salt.modules.lxc.get_network_profile(name=None, **kwargs)

  Added in version 2015.5.0.

  Gather a pre-configured set of network configuration parameters. If no arguments are passed, the following default profile is returned:

      {'eth0': {'link': 'br0', 'type': 'veth', 'flags': 'up'}}

  Profiles can be defined in the minion or master config files, or in pillar or grains, and are loaded using `config.get`. The key under which LXC profiles must be configured is `lxc.network_profile`. An example network profile would be as follows:

      lxc.network_profile.centos:
        eth0:
          link: br0
          type: veth
          flags: up

  To disable networking entirely:

      lxc.network_profile.centos:
        eth0:
          disable: true

  Parameters set in a profile can be overridden by passing additional arguments to this function.

  A profile can be passed either as the name of the profile, or a dictionary of variable names and values. See the LXC Tutorial for more information on how to use network profiles.

  Warning

  The `ipv4`, `ipv6`, `gateway`, and `link` (bridge) settings in network profiles will only work if the container doesn't redefine the network configuration (for example in `/etc/sysconfig/network-scripts/ifcfg-<interface_name>` on RHEL/CentOS, or `/etc/network/interfaces` on Debian/Ubuntu/etc.)

  CLI Example:

      salt-call lxc.get_network_profile default

salt.modules.lxc.get_parameter(name, parameter, path=None)

  Returns the value of a cgroup parameter for a container

  path

    path to the container parent directory default: /var/lib/lxc (system)

    Added in version 2015.8.0.

  CLI Example:

      salt '*' lxc.get_parameter container_name memory.limit_in_bytes

salt.modules.lxc.get_pid(name, path=None)

  Returns a container pid. Throw an exception if the container isn't running.

  CLI Example:

      salt '*' lxc.get_pid name

salt.modules.lxc.get_root_path(path)

  Get the configured lxc root for containers

  Added in version 2015.8.0.

  CLI Example:

      salt '*' lxc.get_root_path

salt.modules.lxc.images(dist=None)

  Added in version 2015.5.0.

  List the available images for LXC's `download` template.

  distNone

    Filter results to a single Linux distribution

  CLI Examples:

      salt myminion lxc.images
      salt myminion lxc.images dist=centos

salt.modules.lxc.info(name, path=None)

  Returns information about a container

  path

    path to the container parent directory default: /var/lib/lxc (system)

    Added in version 2015.8.0.

  CLI Example:

      salt '*' lxc.info name

salt.modules.lxc.init(name, config=None, cpuset=None, cpushare=None, memory=None, profile=None, network_profile=None, nic_opts=None, cpu=None, autostart=True, password=None, password_encrypted=None, users=None, dnsservers=None, searchdomains=None, bridge=None, gateway=None, pub_key=None, priv_key=None, force_install=False, unconditional_install=False, bootstrap_delay=None, bootstrap_args=None, bootstrap_shell=None, bootstrap_url=None, **kwargs)

  Initialize a new container.

  This is a partial idempotent function as if it is already provisioned, we will reset a bit the lxc configuration file but much of the hard work will be escaped as markers will prevent re-execution of harmful tasks.

  name

    Name of the container

  image

    A tar archive to use as the rootfs for the container. Conflicts with the `template` argument.

  cpus

    Select a random number of cpu cores and assign it to the cpuset, if the cpuset option is set then this option will be ignored

  cpuset

    Explicitly define the cpus this container will be bound to

  cpushare

    cgroups cpu shares

  autostart

    autostart container on reboot

  memory

    cgroups memory limit, in MB

    Changed in version 2015.5.0: If no value is passed, no limit is set. In earlier Salt versions, not passing this value causes a 1024MB memory limit to be set, and it was necessary to pass `memory=0` to set no limit.

  gateway

    the ipv4 gateway to use the default does nothing more than lxcutils does

  bridge

    the bridge to use the default does nothing more than lxcutils does

  network_profile

    Network profile to use for the container

    Added in version 2015.5.0.

  nic_opts

    Extra options for network interfaces, will override

    `{"eth0": {"hwaddr": "aa:bb:cc:dd:ee:ff", "ipv4": "10.1.1.1", "ipv6": "2001:db8::ff00:42:8329"}}`

    or

    `{"eth0": {"hwaddr": "aa:bb:cc:dd:ee:ff", "ipv4": "10.1.1.1/24", "ipv6": "2001:db8::ff00:42:8329"}}`

  users

    Users for which the password defined in the `password` param should be set. Can be passed as a comma separated list or a python list. Defaults to just the `root` user.

  password

    Set the initial password for the users defined in the `users` parameter

  password_encryptedFalse

    Set to `True` to denote a password hash instead of a plaintext password

    Added in version 2015.5.0.

  profile

    A LXC profile (defined in config or pillar). This can be either a real profile mapping or a string to retrieve it in configuration

  start

    Start the newly-created container

  dnsservers

    list of dns servers to set in the container, default [] (no setting)

  seed

    Seed the container with the minion config. Default: `True`

  install

    If salt-minion is not already installed, install it. Default: `True`

  config

    Optional config parameters. By default, the id is set to the name of the container.

  master

    salt master (default to minion's master)

  master_port

    salt master port (default to minion's master port)

  pub_key

    Explicit public key to preseed the minion with (optional). This can be either a filepath or a string representing the key

  priv_key

    Explicit private key to preseed the minion with (optional). This can be either a filepath or a string representing the key

  approve_key

    If explicit preseeding is not used; Attempt to request key approval from the master. Default: `True`

  path

    path to the container parent directory default: /var/lib/lxc (system)

    Added in version 2015.8.0.

  clone_from

    Original from which to use a clone operation to create the container. Default: `None`

  bootstrap_delay

    Delay in seconds between end of container creation and bootstrapping. Useful when waiting for container to obtain a DHCP lease.

    Added in version 2015.5.0.

  bootstrap_url

    See lxc.bootstrap

  bootstrap_shell

    See lxc.bootstrap

  bootstrap_args

    See lxc.bootstrap

  force_install

    Force installation even if salt-minion is detected, this is the way to run vendor bootstrap scripts even if a salt minion is already present in the container

  unconditional_install

    Run the script even if the container seems seeded

  CLI Example:

      salt 'minion' lxc.init name [cpuset=cgroups_cpuset] \
              [cpushare=cgroups_cpushare] [memory=cgroups_memory] \
              [nic=nic_profile] [profile=lxc_profile] \
              [nic_opts=nic_opts] [start=(True|False)] \
              [seed=(True|False)] [install=(True|False)] \
              [config=minion_config] [approve_key=(True|False) \
              [clone_from=original] [autostart=True] \
              [priv_key=/path_or_content] [pub_key=/path_or_content] \
              [bridge=lxcbr0] [gateway=10.0.3.1] \
              [dnsservers[dns1,dns2]] \
              [users=[foo]] [password='secret'] \
              [password_encrypted=(True|False)]

salt.modules.lxc.list_(extra=False, limit=None, path=None)

  List containers classified by state

  extra

    Also get per-container specific info. This will change the return data. Instead of returning a list of containers, a dictionary of containers and each container's output from `lxc.info`.

  path

    path to the container parent directory default: /var/lib/lxc (system)

    Added in version 2015.8.0.

  limit

    Return output matching a specific state (frozen, running, or stopped).

    Added in version 2015.5.0.

  CLI Examples:

      salt '*' lxc.list
      salt '*' lxc.list extra=True
      salt '*' lxc.list limit=running

salt.modules.lxc.ls_(active=None, cache=True, path=None)

  Return a list of the containers available on the minion

  path

    path to the container parent directory default: /var/lib/lxc (system)

    Added in version 2015.8.0.

  active

    If `True`, return only active (i.e. running) containers

    Added in version 2015.5.0.

  CLI Example:

      salt '*' lxc.ls
      salt '*' lxc.ls active=True

salt.modules.lxc.read_conf(conf_file, out_format='simple')

  Read in an LXC configuration file. By default returns a simple, unsorted dict, but can also return a more detailed structure including blank lines and comments.

  out_format:

    set to 'simple' if you need the old and unsupported behavior. This won't support the multiple lxc values (eg: multiple network nics)

  CLI Examples:

      salt 'minion' lxc.read_conf /etc/lxc/mycontainer.conf
      salt 'minion' lxc.read_conf /etc/lxc/mycontainer.conf out_format=commented

salt.modules.lxc.reboot(name, path=None)

  Reboot a container.

  path

    path to the container parent default: /var/lib/lxc (system default)

    Added in version 2015.8.0.

  CLI Examples:

      salt 'minion' lxc.reboot myvm

salt.modules.lxc.reconfigure(name, cpu=None, cpuset=None, cpushare=None, memory=None, profile=None, network_profile=None, nic_opts=None, bridge=None, gateway=None, autostart=None, utsname=None, rootfs=None, path=None, **kwargs)

  Reconfigure a container.

  This only applies to a few property

  name

    Name of the container.

  utsname

    utsname of the container.

    Added in version 2016.3.0.

  rootfs

    rootfs of the container.

    Added in version 2016.3.0.

  cpu

    Select a random number of cpu cores and assign it to the cpuset, if the cpuset option is set then this option will be ignored

  cpuset

    Explicitly define the cpus this container will be bound to

  cpushare

    cgroups cpu shares.

  autostart

    autostart container on reboot

  memory

    cgroups memory limit, in MB. (0 for nolimit, None for old default 1024MB)

  gateway

    the ipv4 gateway to use the default does nothing more than lxcutils does

  bridge

    the bridge to use the default does nothing more than lxcutils does

  nic

    Network interfaces profile (defined in config or pillar).

  nic_opts

    Extra options for network interfaces, will override

    `{"eth0": {"mac": "aa:bb:cc:dd:ee:ff", "ipv4": "10.1.1.1", "ipv6": "2001:db8::ff00:42:8329"}}`

    or

    `{"eth0": {"mac": "aa:bb:cc:dd:ee:ff", "ipv4": "10.1.1.1/24", "ipv6": "2001:db8::ff00:42:8329"}}`

  path

    path to the container parent

    Added in version 2015.8.0.

  CLI Example:

      salt-call -lall mc_lxc_fork.reconfigure foobar nic_opts="{'eth1': {'mac': '00:16:3e:dd:ee:44'}}" memory=4

salt.modules.lxc.remove(name, stop=False, path=None)

  This function is an alias of `destroy`.

  > Destroy the named container.

  > Warning

  > Destroys all data associated with the container.

  > path

  >   path to the container parent directory (default: /var/lib/lxc)

  >   Added in version 2015.8.0.

  > stopFalse

  >   If `True`, the container will be destroyed even if it is running/frozen.

  >   Changed in version 2015.5.0: Default value changed to `False`. This more closely matches the behavior of `lxc-destroy(1)`, and also makes it less likely that an accidental command will destroy a running container that was being used for important things.

  > CLI Examples:

  >     salt '*' lxc.destroy foo
  >     salt '*' lxc.destroy foo stop=True

salt.modules.lxc.restart(name, path=None, lxc_config=None, force=False)

  Added in version 2015.5.0.

  Restart the named container. If the container was not running, the container will merely be started.

  name

    The name of the container

  path

    path to the container parent directory default: /var/lib/lxc (system)

    Added in version 2015.8.0.

  lxc_config

    path to a lxc config file config file will be guessed from container name otherwise

    Added in version 2015.8.0.

  forceFalse

    If `True`, the container will be force-stopped instead of gracefully shut down

  CLI Example:

      salt myminion lxc.restart name

salt.modules.lxc.retcode(name, cmd, no_start=False, preserve_state=True, stdin=None, python_shell=True, output_loglevel='debug', use_vt=False, path=None, ignore_retcode=False, chroot_fallback=False, keep_env='http_proxy,https_proxy,no_proxy')

  Added in version 2015.5.0.

  Run `cmd.retcode` within a container

  Warning

  Many shell builtins do not work, failing with stderr similar to the following:

      lxc_container: No such file or directory - failed to exec 'command'

  The same error will be displayed in stderr if the command being run does not exist. If the retcode is nonzero and not what was expected, try using `lxc.run_stderr` or `lxc.run_all`.

  name

    Name of the container in which to run the command

  cmd

    Command to run

  no_startFalse

    If the container is not running, don't start it

  preserve_stateTrue

    After running the command, return the container to its previous state

  path

    path to the container parent default: /var/lib/lxc (system default)

    Added in version 2015.8.0.

  stdinNone

    Standard input to be used for the command

  output_logleveldebug

    Level at which to log the output from the command. Set to `quiet` to suppress logging.

  use_vtFalse

    Use SaltStack's utils.vt to stream output to console `output=all`.

  keep_envhttp_proxy,https_proxy,no_proxy

    A list of env vars to preserve. May be passed as commma-delimited list.

  chroot_fallback

    if the container is not running, try to run the command using chroot default: false

  CLI Example:

      salt myminion lxc.retcode mycontainer 'ip addr show'

salt.modules.lxc.run(name, cmd, no_start=False, preserve_state=True, stdin=None, python_shell=True, output_loglevel='debug', use_vt=False, path=None, ignore_retcode=False, chroot_fallback=False, keep_env='http_proxy,https_proxy,no_proxy')

  Added in version 2015.8.0.

  Run `cmd.run` within a container

  Warning

  Many shell builtins do not work, failing with stderr similar to the following:

      lxc_container: No such file or directory - failed to exec 'command'

  The same error will be displayed in stderr if the command being run does not exist. If no output is returned using this function, try using `lxc.run_stderr` or `lxc.run_all`.

  name

    Name of the container in which to run the command

  cmd

    Command to run

  path

    path to the container parent default: /var/lib/lxc (system default)

    Added in version 2015.8.0.

  no_startFalse

    If the container is not running, don't start it

  preserve_stateTrue

    After running the command, return the container to its previous state

  stdinNone

    Standard input to be used for the command

  output_logleveldebug

    Level at which to log the output from the command. Set to `quiet` to suppress logging.

  use_vtFalse

    Use SaltStack's utils.vt to stream output to console. Assumes `output=all`.

  chroot_fallback

    if the container is not running, try to run the command using chroot default: false

  keep_envhttp_proxy,https_proxy,no_proxy

    A list of env vars to preserve. May be passed as commma-delimited list.

  CLI Example:

      salt myminion lxc.run mycontainer 'ip addr show'

salt.modules.lxc.run_all(name, cmd, no_start=False, preserve_state=True, stdin=None, python_shell=True, output_loglevel='debug', use_vt=False, path=None, ignore_retcode=False, chroot_fallback=False, keep_env='http_proxy,https_proxy,no_proxy')

  Added in version 2015.5.0.

  Run `cmd.run_all` within a container

  Note

  While the command is run within the container, it is initiated from the host. Therefore, the PID in the return dict is from the host, not from the container.

  Warning

  Many shell builtins do not work, failing with stderr similar to the following:

      lxc_container: No such file or directory - failed to exec 'command'

  The same error will be displayed in stderr if the command being run does not exist.

  name

    Name of the container in which to run the command

  path

    path to the container parent default: /var/lib/lxc (system default)

    Added in version 2015.8.0.

  cmd

    Command to run

  no_startFalse

    If the container is not running, don't start it

  preserve_stateTrue

    After running the command, return the container to its previous state

  stdinNone

    Standard input to be used for the command

  output_logleveldebug

    Level at which to log the output from the command. Set to `quiet` to suppress logging.

  use_vtFalse

    Use SaltStack's utils.vt to stream output to console `output=all`.

  keep_envhttp_proxy,https_proxy,no_proxy

    A list of env vars to preserve. May be passed as commma-delimited list.

  chroot_fallback

    if the container is not running, try to run the command using chroot default: false

  CLI Example:

      salt myminion lxc.run_all mycontainer 'ip addr show'

salt.modules.lxc.run_stderr(name, cmd, no_start=False, preserve_state=True, stdin=None, python_shell=True, output_loglevel='debug', use_vt=False, path=None, ignore_retcode=False, chroot_fallback=False, keep_env='http_proxy,https_proxy,no_proxy')

  Added in version 2015.5.0.

  Run `cmd.run_stderr` within a container

  Warning

  Many shell builtins do not work, failing with stderr similar to the following:

      lxc_container: No such file or directory - failed to exec 'command'

  The same error will be displayed if the command being run does not exist.

  name

    Name of the container in which to run the command

  cmd

    Command to run

  path

    path to the container parent default: /var/lib/lxc (system default)

    Added in version 2015.8.0.

  no_startFalse

    If the container is not running, don't start it

  preserve_stateTrue

    After running the command, return the container to its previous state

  stdinNone

    Standard input to be used for the command

  output_logleveldebug

    Level at which to log the output from the command. Set to `quiet` to suppress logging.

  use_vtFalse

    Use SaltStack's utils.vt to stream output to console `output=all`.

  keep_envhttp_proxy,https_proxy,no_proxy

    A list of env vars to preserve. May be passed as commma-delimited list.

  chroot_fallback

    if the container is not running, try to run the command using chroot default: false

  CLI Example:

      salt myminion lxc.run_stderr mycontainer 'ip addr show'

salt.modules.lxc.run_stdout(name, cmd, no_start=False, preserve_state=True, stdin=None, python_shell=True, output_loglevel='debug', use_vt=False, path=None, ignore_retcode=False, chroot_fallback=False, keep_env='http_proxy,https_proxy,no_proxy')

  Added in version 2015.5.0.

  Run `cmd.run_stdout` within a container

  Warning

  Many shell builtins do not work, failing with stderr similar to the following:

      lxc_container: No such file or directory - failed to exec 'command'

  The same error will be displayed in stderr if the command being run does not exist. If no output is returned using this function, try using `lxc.run_stderr` or `lxc.run_all`.

  name

    Name of the container in which to run the command

  cmd

    Command to run

  path

    path to the container parent default: /var/lib/lxc (system default)

    Added in version 2015.8.0.

  no_startFalse

    If the container is not running, don't start it

  preserve_stateTrue

    After running the command, return the container to its previous state

  stdinNone

    Standard input to be used for the command

  output_logleveldebug

    Level at which to log the output from the command. Set to `quiet` to suppress logging.

  use_vtFalse

    Use SaltStack's utils.vt to stream output to console `output=all`.

  keep_envhttp_proxy,https_proxy,no_proxy

    A list of env vars to preserve. May be passed as commma-delimited list.

  chroot_fallback

    if the container is not running, try to run the command using chroot default: false

  CLI Example:

      salt myminion lxc.run_stdout mycontainer 'ip addr show'

salt.modules.lxc.running_systemd(name, cache=True, path=None)

  Determine if systemD is running

  path

    path to the container parent

    Added in version 2015.8.0.

  CLI Example:

      salt '*' lxc.running_systemd ubuntu

salt.modules.lxc.search_lxc_bridge()

  Search the first bridge which is potentially available as LXC bridge

  CLI Example:

      salt '*' lxc.search_lxc_bridge

salt.modules.lxc.search_lxc_bridges()

  Search which bridges are potentially available as LXC bridges

  CLI Example:

      salt '*' lxc.search_lxc_bridges

salt.modules.lxc.set_dns(name, dnsservers=None, searchdomains=None, path=None)

  Changed in version 2015.5.0: The `dnsservers` and `searchdomains` parameters can now be passed as a comma-separated list.

  Update /etc/resolv.confo

  path

  > path to the container parent default: /var/lib/lxc (system default)

  > Added in version 2015.8.0.

  CLI Example:

      salt myminion lxc.set_dns ubuntu "['8.8.8.8', '4.4.4.4']"

salt.modules.lxc.set_parameter(name, parameter, value, path=None)

  Set the value of a cgroup parameter for a container.

  path

    path to the container parent directory default: /var/lib/lxc (system)

    Added in version 2015.8.0.

  CLI Example:

      salt '*' lxc.set_parameter name parameter value

salt.modules.lxc.set_pass(name, users, password, encrypted=True, path=None)

  This function is an alias of `set_password`.

  > Changed in version 2015.5.0: Function renamed from `set_pass` to `set_password`. Additionally, this function now supports (and defaults to using) a password hash instead of a plaintext password.

  > Set the password of one or more system users inside containers

  > users

  >   Comma-separated list (or python list) of users to change password

  > password

  >   Password to set for the specified user(s)

  > encryptedTrue

  >   If true, `password` must be a password hash. Set to `False` to set a plaintext password (not recommended).

  >   Added in version 2015.5.0.

  > path

  >   path to the container parent directory default: /var/lib/lxc (system)

  >   Added in version 2015.8.0.

  > CLI Example:

  >     salt '*' lxc.set_pass container-name root '$6$uJ2uAyLU$KoI67t8As/0fXtJOPcHKGXmUpcoYUcVR2K6x93walnShTCQvjRwq25yIkiCBOqgbfdKQSFnAo28/ek6716vEV1'
  >     salt '*' lxc.set_pass container-name root foo encrypted=False

salt.modules.lxc.set_password(name, users, password, encrypted=True, path=None)

  Changed in version 2015.5.0: Function renamed from `set_pass` to `set_password`. Additionally, this function now supports (and defaults to using) a password hash instead of a plaintext password.

  Set the password of one or more system users inside containers

  users

    Comma-separated list (or python list) of users to change password

  password

    Password to set for the specified user(s)

  encryptedTrue

    If true, `password` must be a password hash. Set to `False` to set a plaintext password (not recommended).

    Added in version 2015.5.0.

  path

    path to the container parent directory default: /var/lib/lxc (system)

    Added in version 2015.8.0.

  CLI Example:

      salt '*' lxc.set_pass container-name root '$6$uJ2uAyLU$KoI67t8As/0fXtJOPcHKGXmUpcoYUcVR2K6x93walnShTCQvjRwq25yIkiCBOqgbfdKQSFnAo28/ek6716vEV1'
      salt '*' lxc.set_pass container-name root foo encrypted=False

salt.modules.lxc.start(name, **kwargs)

  Start the named container

  path

    path to the container parent directory default: /var/lib/lxc (system)

    Added in version 2015.8.0.

  lxc_config

    path to a lxc config file config file will be guessed from container name otherwise

    Added in version 2015.8.0.

  use_vt

    run the command through VT

    Added in version 2015.8.0.

  CLI Example:

      salt myminion lxc.start name

salt.modules.lxc.state(name, path=None)

  Returns the state of a container.

  path

    path to the container parent directory (default: /var/lib/lxc)

    Added in version 2015.8.0.

  CLI Example:

      salt '*' lxc.state name

salt.modules.lxc.stop(name, kill=False, path=None, use_vt=None)

  Stop the named container

  path

    path to the container parent directory default: /var/lib/lxc (system)

    Added in version 2015.8.0.

  kill: False

    Do not wait for the container to stop, kill all tasks in the container. Older LXC versions will stop containers like this irrespective of this argument.

    Changed in version 2015.5.0: Default value changed to `False`

  use_vt

    run the command through VT

    Added in version 2015.8.0.

  CLI Example:

      salt myminion lxc.stop name

salt.modules.lxc.systemd_running_state(name, path=None)

  Get the operational state of a systemd based container

  path

    path to the container parent default: /var/lib/lxc (system default)

    Added in version 2015.8.0.

  CLI Example:

      salt myminion lxc.systemd_running_state ubuntu

salt.modules.lxc.templates()

  Added in version 2015.5.0.

  List the available LXC template scripts installed on the minion

  CLI Examples:

      salt myminion lxc.templates

salt.modules.lxc.test_bare_started_state(name, path=None)

  Test if a non systemd container is fully started For now, it consists only to test if the container is attachable

  path

    path to the container parent default: /var/lib/lxc (system default)

    Added in version 2015.8.0.

  CLI Example:

      salt myminion lxc.test_bare_started_state ubuntu

salt.modules.lxc.test_sd_started_state(name, path=None)

  Test if a systemd container is fully started

  path

    path to the container parent default: /var/lib/lxc (system default)

    Added in version 2015.8.0.

  CLI Example:

      salt myminion lxc.test_sd_started_state ubuntu

salt.modules.lxc.unfreeze(name, path=None, use_vt=None)

  Unfreeze the named container.

  path

    path to the container parent directory default: /var/lib/lxc (system)

    Added in version 2015.8.0.

  use_vt

    run the command through VT

    Added in version 2015.8.0.

  CLI Example:

      salt '*' lxc.unfreeze name

salt.modules.lxc.update_lxc_conf(name, lxc_conf, lxc_conf_unset, path=None)

  Edit LXC configuration options

  path

    path to the container parent default: /var/lib/lxc (system default)

    Added in version 2015.8.0.

  CLI Example:

      salt myminion lxc.update_lxc_conf ubuntu \
              lxc_conf="[{'network.ipv4.ip':'10.0.3.5'}]" \
              lxc_conf_unset="['lxc.utsname']"

salt.modules.lxc.version()

  Return the actual lxc client version

  Added in version 2015.8.0.

  CLI Example:

      salt '*' lxc.version

salt.modules.lxc.wait_started(name, path=None, timeout=300)

  Check that the system has fully inited

  This is actually very important for systemD based containers

  see https://github.com/saltstack/salt/issues/23847

  path

    path to the container parent default: /var/lib/lxc (system default)

    Added in version 2015.8.0.

  CLI Example:

      salt myminion lxc.wait_started ubuntu

salt.modules.lxc.write_conf(conf_file, conf)

  Write out an LXC configuration file

  This is normally only used internally. The format of the data structure must match that which is returned from `lxc.read_conf()`, with `out_format` set to `commented`.

  An example might look like:

      [
          {'lxc.utsname': '$CONTAINER_NAME'},
          '# This is a commented line\n',
          '\n',
          {'lxc.mount': '$CONTAINER_FSTAB'},
          {'lxc.rootfs': {'comment': 'This is another test',
                          'value': 'This is another test'}},
          '\n',
          {'lxc.network.type': 'veth'},
          {'lxc.network.flags': 'up'},
          {'lxc.network.link': 'br0'},
          {'lxc.network.mac': '$CONTAINER_MACADDR'},
          {'lxc.network.ipv4': '$CONTAINER_IPADDR'},
          {'lxc.network.name': '$CONTAINER_DEVICENAME'},
      ]

  CLI Example:

      salt 'minion' lxc.write_conf /etc/lxc/mycontainer.conf \
          out_format=commented