You are viewing docs from a branch that is no longer active. You might want to view docs for the 2015.8.x release instead.

salt.modules.lxc¶

Control Linux Containers via Salt

depends:	lxc package for distribution

lxc >= 1.0 (even beta alpha) is required

salt.modules.lxc.attachable(name)¶

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

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, bootstrap_args=None, bootstrap_shell=None)¶

Install and configure salt in a container.

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

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
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_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 Example:

salt '*' lxc.bootstrap ubuntu

salt.modules.lxc.clone(name, orig, snapshot=False, profile=None, **kwargs)¶

Create a new container.

CLI Example:

salt 'minion' lxc.clone name orig [snapshot=(True|False)] \
        [size=filesystem_size] [vgname=volume_group] \
        [profile=profile_name]

name: Name of the container.
orig: Name of the cloned original container
snapshot: Do we use Copy On Write snapshots (LVM)
size: Size of the container
vgname: LVM volume group(lxc)
profile: A LXC profile (defined in config or pillar).

CLI Example:

salt '*' lxc.clone myclone ubuntu "snapshot=True"

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

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

CLI Example:

salt '*' lxc.cloud_init foo

name: Name of the container. May be None and then guessed from saltcloud mapping.
vm_: saltcloud mapping defaults for the vm

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

CLI Example:

salt '*' lxc.cloud_init_interface foo

name

name of the lxc container to create

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

lgname

if using LVM: lvname

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

ip

ip for the primary nic

mac

mac 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

additionnal 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'}

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

dns servers to set inside the container

autostart

autostart the container at boot time

password

administrative password for the container

users

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

salt.modules.lxc.cp(name, src, dest)¶

Copy a file or directory from the host into a container

CLI Example:

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

salt.modules.lxc.create(name, config=None, profile=None, options=None, **kwargs)¶

Create a new container.

CLI Example:

salt 'minion' lxc.create name [config=config_file] \
        [profile=profile] [template=template_name] \
        [backing=backing_store] [vgname=volume_group] \
        [size=filesystem_size] [options=template_options]

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: A LXC profile (defined in config or pillar).
template: The template to use. E.g., 'ubuntu' or 'fedora'.
backing: The type of storage to use. Set to 'lvm' to use an LVM group. Defaults to filesystem within /var/lib/lxc/.
vgname: Name of the LVM volume group in which to create the volume for this container. Only applicable if backing=lvm. Defaults to 'lxc'.
fstype: fstype to use on LVM lv.
size: Size of the volume to create. Only applicable if backing=lvm. Defaults to 1G.
options: Template specific options to pass to the lxc-create command.

salt.modules.lxc.destroy(name, stop=True)¶

Destroy the named container. WARNING: Destroys all data associated with the container.

CLI Example:

salt '*' lxc.destroy name [stop=(True|False)]

salt.modules.lxc.edit_conf(conf_file, out_format='simple', **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.

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 Examples:

salt 'minion' lxc.edit_conf /etc/lxc/mycontainer.conf             out_format=commented lxc.network.type=veth

salt.modules.lxc.exists(name)¶

Returns whether the named container exists.

CLI Example:

salt '*' lxc.exists name

salt.modules.lxc.freeze(name)¶

Freeze the named container.

CLI Example:

salt '*' lxc.freeze name

salt.modules.lxc.get_base(**kwargs)¶

If the needed base does not exist, then create it, if it does exist create nothing and return the name of the base lxc container so it can be cloned.

CLI Example:

salt 'minion' lxc.init name [cpuset=cgroups_cpuset] \
        [nic=nic_profile] [profile=lxc_profile] \
        [nic_opts=nic_opts] [image=network image path]\
        [seed=(True|False)] [install=(True|False)] \
        [config=minion_config]

salt.modules.lxc.get_parameter(name, parameter)¶

Returns the value of a cgroup parameter for a container.

CLI Example:

salt '*' lxc.get_parameter name parameter

salt.modules.lxc.info(name)¶

Returns information about a container.

CLI Example:

salt '*' lxc.info name

salt.modules.lxc.init(name, cpuset=None, cpushare=None, memory=None, nic='default', profile=None, nic_opts=None, cpu=None, autostart=True, password=None, users=None, dnsservers=None, bridge=None, gateway=None, pub_key=None, priv_key=None, force_install=False, unconditional_install=False, 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.

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=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'

name

Name of the container.

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. (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).

users

Sysadmins users to set the administrative password to e.g. [root, ubuntu, sysadmin], default [root] and [root, ubuntu] on ubuntu

password

Set the initial password for default sysadmin users, at least root but also can be used for sudoers, e.g. [root, ubuntu, sysadmin]

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

nic_opts

Extra options for network interfaces. E.g:

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

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

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.

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

clone

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

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

salt.modules.lxc.list_(extra=False)¶

List defined containers classified by status. Status can be running, stopped, and frozen.

extra
Also get per container specific info at once. Warning: it will not return a collection of list but a collection of mappings by status and then per container name:
{'running': ['foo']} # normal mode
{'running': {'foo': {'info1': 'bar'}} # extra mode

CLI Example:

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

salt.modules.lxc.ls()¶

Return just a list of the containers available

CLI Example:

salt '*' lxc.ls

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.

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.run_cmd(name, cmd, no_start=False, preserve_state=True, stdout=True, stderr=False, use_vt=False, keep_env='http_proxy, https_proxy, no_proxy')¶

Run a command inside the container.

CLI Example:

salt 'minion' name command [no_start=(True|False)] \
        [preserve_state=(True|False)] [stdout=(True|False)] \
        [stderr=(True|False)]

name: Name of the container on which to operate.
cmd: Command to run
no_start: If the container is not running, don't start it. Default: False
preserve_state: After running the command, return the container to its previous state. Default: True
stdout:: Return stdout. Default: True
stderr:: Return stderr. Default: False
use_vt: use saltstack utils.vt to stream output to console
keep_env: A list of env vars to preserve. May be passed as commma-delimited list. Defaults to http_proxy,https_proxy.

Note

If stderr and stdout are both False, the return code is returned. If stderr and stdout are both True, the pid and return code are also returned.

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

Update container DNS configuration and possibly also resolv.conf one.

CLI Example:

salt-call -lall lxc.set_dns ubuntu ['8.8.8.8', '4.4.4.4']

salt.modules.lxc.set_parameter(name, parameter, value)¶

Set the value of a cgroup parameter for a container.

CLI Example:

salt '*' lxc.set_parameter name parameter value

salt.modules.lxc.set_pass(name, users, password)¶

Set the password of one or more system users inside containers

CLI Example:

salt '*' lxc.set_pass container-name root foo

salt.modules.lxc.start(name, restart=False)¶

Start the named container.

CLI Example:

salt '*' lxc.start name

salt.modules.lxc.state(name)¶

Returns the state of a container.

CLI Example:

salt '*' lxc.state name

salt.modules.lxc.stop(name, kill=True)¶

Stop the named container.

CLI Example:

salt '*' lxc.stop name

salt.modules.lxc.templates(templates_dir='/usr/share/lxc/templates')¶

Returns a list of existing templates

CLI Example:

salt '*' lxc.templates

salt.modules.lxc.unfreeze(name)¶

Unfreeze the named container.

CLI Example:

salt '*' lxc.unfreeze name

salt.modules.lxc.update_lxc_conf(name, lxc_conf, lxc_conf_unset)¶

Edit LXC configuration options

CLI Example:

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

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.hwaddr': '$CONTAINER_MACADDR'},
    {'lxc.network.ipv4': '$CONTAINER_IPADDR'},
    {'lxc.network.name': '$CONTAINER_DEVICENAME'},
]

CLI Examples:

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

You are viewing docs for an inactive release, 2014.7.6. Switch to docs for the latest stable release, 2015.8.x, or to a recent doc build from the develop branch.

saltstack.com