salt.modules.lxc
Control Linux Containers via Salt
- depends
-
lxc package for distribution
lxc >= 1.0 (even beta alpha) is required
-
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.add_veth(name, interface_name, bridge=None, path=None)
-
New 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
New 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.apply_network_profile(name, network_profile, nic_opts=None, 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)
New in version 2015.8.0.
CLI Example:
salt 'minion' lxc.attachable ubuntu
salt.modules.lxc.attachable(name, path=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)
New 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.
New 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.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)
-
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)
New 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
New in version 2015.8.0.
- nic_opts
-
give extra opts overriding network profile values
New 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.clone(name, orig, profile=None, network_profile=None, nic_opts=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(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)
New 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.cloud_init_interface(name, vm_=None, **kwargs)
-
Changed in version 2015.8.0: Function renamed from
lxc.cp
tolxc.copy_to
for consistency with other container types.lxc.cp
will continue to work, however. For versions 2015.2.x and earlier, uselxc.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)
New 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 thedest
argument, an error will be raised.New in version 2015.8.0.
makedirs : False
Create the parent directory on the container if it does not already exist.
New 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.copy_to(name, source, dest, overwrite=False, makedirs=False, path=None)
-
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
New in version 2015.5.0.
Container Creation Arguments
- template
-
The template to use. For example,
ubuntu
orfedora
. For a full list of available templates, check out thelxc.templates
function.Conflicts with the
image
argument.Note
The
download
template requires the following three parameters to be defined inoptions
: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 runlxc-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)New in version 2015.8.0.
salt.modules.lxc.create(name, config=None, profile=None, network_profile=None, nic_opts=None, **kwargs)
-
Destroy the named container.
Warning
Destroys all data associated with the container.
- path
-
path to the container parent directory (default: /var/lib/lxc)
New 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 oflxc-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.destroy(name, stop=False, path=None)
-
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 anout_format
ofcommented
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.edit_conf(conf_file, out_format='simple', read_only=False, lxc_config=None, **kwargs)
-
Returns whether the named container exists.
- path
-
path to the container parent directory (default: /var/lib/lxc)
New in version 2015.8.0.
CLI Example:
salt '*' lxc.exists name
salt.modules.lxc.exists(name, path=None)
-
Freeze the named container
- path
-
path to the container parent directory default: /var/lib/lxc (system)
New in version 2015.8.0.
- startFalse
-
If
True
and the container is stopped, the container will be started before attempting to freeze.New in version 2015.5.0.
- use_vt
-
run the command through VT
New in version 2015.8.0.
CLI Example:
salt '*' lxc.freeze name
salt.modules.lxc.freeze(name, **kwargs)
-
New 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 islxc.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_container_profile(name=None, **kwargs)
-
New 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 islxc.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
, andlink
(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_network_profile(name=None, **kwargs)
-
Returns the value of a cgroup parameter for a container
- path
-
path to the container parent directory default: /var/lib/lxc (system)
New in version 2015.8.0.
CLI Example:
salt '*' lxc.get_parameter container_name memory.limit_in_bytes
salt.modules.lxc.get_parameter(name, parameter, 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_pid(name, path=None)
-
Get the configured lxc root for containers
New in version 2015.8.0.
CLI Example:
salt '*' lxc.get_root_path
salt.modules.lxc.get_root_path(path)
-
New 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.images(dist=None)
-
Returns information about a container
- path
-
path to the container parent directory default: /var/lib/lxc (system)
New in version 2015.8.0.
CLI Example:
salt '*' lxc.info name
salt.modules.lxc.info(name, path=None)
-
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
New 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 theroot
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 passwordNew 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)
New 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.
New 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.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)
-
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)
New in version 2015.8.0.
- limit
-
Return output matching a specific state (frozen, running, or stopped).
New in version 2015.5.0.
CLI Examples:
salt '*' lxc.list salt '*' lxc.list extra=True salt '*' lxc.list limit=running
salt.modules.lxc.list_(extra=False, limit=None, path=None)
-
Return a list of the containers available on the minion
- path
-
path to the container parent directory default: /var/lib/lxc (system)
New in version 2015.8.0.
- active
-
If
True
, return only active (i.e. running) containersNew in version 2015.5.0.
CLI Example:
salt '*' lxc.ls salt '*' lxc.ls active=True
salt.modules.lxc.ls_(active=None, cache=True, path=None)
-
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.read_conf(conf_file, out_format='simple')
-
Reboot a container.
- path
-
path to the container parent default: /var/lib/lxc (system default)
New in version 2015.8.0.
CLI Examples:
salt 'minion' lxc.reboot myvm
salt.modules.lxc.reboot(name, path=None)
-
Reconfigure a container.
This only applies to a few property
- name
-
Name of the container.
- utsname
-
utsname of the container.
New in version 2016.3.0.
- rootfs
-
rootfs of the container.
New 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
New 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.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)
-
New 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)
New in version 2015.8.0.
- lxc_config
-
path to a lxc config file config file will be guessed from container name otherwise
New 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.restart(name, path=None, lxc_config=None, force=False)
-
New in version 2015.5.0.
Run
cmd.retcode
within a containerWarning
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
orlxc.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)
New 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.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')
-
New in version 2015.8.0.
Run
cmd.run
within a containerWarning
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
orlxc.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)
New 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 'ifconfig -a'
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')
-
New in version 2015.5.0.
Run
cmd.run_all
within a containerNote
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)
New 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_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')
-
New in version 2015.5.0.
Run
cmd.run_stderr
within a containerWarning
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)
New 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_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')
-
New in version 2015.5.0.
Run
cmd.run_stdout
within a containerWarning
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
orlxc.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)
New 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 'ifconfig -a'
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')
-
Determine if systemD is running
- path
-
path to the container parent
New in version 2015.8.0.
CLI Example:
salt '*' lxc.running_systemd ubuntu
salt.modules.lxc.running_systemd(name, cache=True, path=None)
-
Search the first bridge which is potentially available as LXC bridge
CLI Example:
salt '*' lxc.search_lxc_bridge
salt.modules.lxc.search_lxc_bridge()
-
Search which bridges are potentially available as LXC bridges
CLI Example:
salt '*' lxc.search_lxc_bridges
salt.modules.lxc.search_lxc_bridges()
-
Changed in version 2015.5.0: The
dnsservers
andsearchdomains
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)
New 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_dns(name, dnsservers=None, searchdomains=None, path=None)
-
Set the value of a cgroup parameter for a container.
- path
-
path to the container parent directory default: /var/lib/lxc (system)
New in version 2015.8.0.
CLI Example:
salt '*' lxc.set_parameter name parameter value
salt.modules.lxc.set_parameter(name, parameter, value, path=None)
-
Changed in version 2015.5.0: Function renamed from
set_pass
toset_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 toFalse
to set a plaintext password (not recommended).New in version 2015.5.0.
- path
-
path to the container parent directory default: /var/lib/lxc (system)
New 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)
-
Start the named container
- path
-
path to the container parent directory default: /var/lib/lxc (system)
New in version 2015.8.0.
- lxc_config
-
path to a lxc config file config file will be guessed from container name otherwise
New in version 2015.8.0.
- use_vt
-
run the command through VT
New in version 2015.8.0.
CLI Example:
salt myminion lxc.start name
salt.modules.lxc.start(name, **kwargs)
-
Returns the state of a container.
- path
-
path to the container parent directory (default: /var/lib/lxc)
New in version 2015.8.0.
CLI Example:
salt '*' lxc.state name
salt.modules.lxc.state(name, path=None)
-
Stop the named container
- path
-
path to the container parent directory default: /var/lib/lxc (system)
New 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
New in version 2015.8.0.
CLI Example:
salt myminion lxc.stop name
salt.modules.lxc.stop(name, kill=False, path=None, use_vt=None)
-
Get the operational state of a systemd based container
- path
-
path to the container parent default: /var/lib/lxc (system default)
New in version 2015.8.0.
CLI Example:
salt myminion lxc.systemd_running_state ubuntu
salt.modules.lxc.systemd_running_state(name, path=None)
-
New in version 2015.5.0.
List the available LXC template scripts installed on the minion
CLI Examples:
salt myminion lxc.templates
salt.modules.lxc.templates()
-
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)
New in version 2015.8.0.
CLI Example:
salt myminion lxc.test_bare_started_state ubuntu
salt.modules.lxc.test_bare_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)
New in version 2015.8.0.
CLI Example:
salt myminion lxc.test_sd_started_state ubuntu
salt.modules.lxc.test_sd_started_state(name, path=None)
-
Unfreeze the named container.
- path
-
path to the container parent directory default: /var/lib/lxc (system)
New in version 2015.8.0.
- use_vt
-
run the command through VT
New in version 2015.8.0.
CLI Example:
salt '*' lxc.unfreeze name
salt.modules.lxc.unfreeze(name, path=None, use_vt=None)
-
Edit LXC configuration options
- path
-
path to the container parent default: /var/lib/lxc (system default)
New 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.update_lxc_conf(name, lxc_conf, lxc_conf_unset, path=None)
-
Return the actual lxc client version
New in version 2015.8.0.
CLI Example:
salt '*' lxc.version
salt.modules.lxc.version()
-
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)
New in version 2015.8.0.
CLI Example:
salt myminion lxc.wait_started ubuntu
salt.modules.lxc.wait_started(name, path=None, timeout=300)
-
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()
, without_format
set tocommented
.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
salt.modules.lxc.write_conf(conf_file, conf)
© 2021 SaltStack.
Licensed under the Apache License, Version 2.0.
https://docs.saltproject.io/en/latest/ref/modules/all/salt.modules.lxc.html