neulab/tldr huggingface dataset:
salt.states.cyg.installed(name, cyg_arch='x86_64', mirrors=None) Make sure that a package is installed.
cyg_arch x86_64 The cygwin architecture to install the package into. Current options are x86 and x86_64
mirrors None List of mirrors to check.  None will use a default mirror (kernel.org)
rsync: cyg.installed: - mirrors: - http://mirror/without/public/key: "" - http://mirror/with/public/key: http://url/of/public/key
salt.states.cyg.removed(name, cyg_arch='x86_64', mirrors=None) Make sure that a package is not installed.
name   The name of the package to uninstall
cyg_arch x86_64 The cygwin architecture to remove the package from. Current options are x86 and x86_64
rsync: cyg.removed: - mirrors: - http://mirror/without/public/key: "" - http://mirror/with/public/key: http://url/of/public/key
salt.states.cyg.updated(name=None, cyg_arch='x86_64', mirrors=None) Make sure all packages are up to date.
name   None No affect, salt fails poorly without the arg available
cyg_arch x86_64 The cygwin architecture to update.  Current options are x86 and x86_64
rsync: cyg.updated: - mirrors: - http://mirror/without/public/key: "" - http://mirror/with/public/key: http://url/of/public/key
salt.states.ddns Dynamic DNS updates Ensure a DNS record is present or absent utilizing RFC 2136 type dynamic updates.
NOTE: The dnspython module is required when managing DDNS using a TSIG key. If you are not using a TSIG key, DDNS is allowed by ACLs based on IP address and the dnspython module is not required.
webserver: ddns.present: - zone: example.com - ttl: 60 - data: 111.222.333.444 - nameserver: 123.234.345.456 - keyfile: /srv/salt/dnspy_tsig_key.txt
salt.states.ddns.absent(name, zone, data=None, rdtype=None, **kwargs) Ensures that the named DNS record is absent.
name   The host portion of the DNS record, e.g., 'webserver'. Name and zone are concatenated when the entry is created unless name includes a trailing dot, so make sure that information is not duplicated in these two arguments.
zone   The zone to check
data   Data for the DNS record. E.g., the IP address for an A record. If omitted, all records matching name (and rdtype, if provided) will be purged.
rdtype DNS resource type. If omitted, all types will be purged.
**kwargs Additional arguments the ddns.update function may need (e.g.  nameserver, keyfile, keyname).  Note that the nsupdate key file can’t be reused by this function, the keyfile and other arguments must follow the dnspython spec.
salt.states.ddns.present(name, zone, ttl, data, rdtype='A', **kwargs) Ensures that the named DNS record is present with the given ttl.
zone   The zone to check/update
ttl    TTL for the record
data   Data for the DNS record. E.g., the IP address for an A record.
rdtype DNS resource type. Default 'A'.
salt.states.debconfmod Management of debconf selections depends
• debconf-utils package
The debconfmod state module manages the enforcement of debconf selections, this state can set those selections prior to package installation.
Available Functions The debconfmod state has two functions, the set and set_file functions
set    Set debconf selections from the state itself
set_file Set debconf selections from a file
nullmailer-debconf: debconf.set: - name: nullmailer - data: 'shared/mailname': {'type': 'string', 'value': 'server.domain.tld'} 'nullmailer/relayhost': {'type': 'string', 'value': 'mail.domain.tld'}
ferm-debconf: debconf.set: - name: ferm - data: 'ferm/enable': {'type': 'boolean', 'value': True}
NOTE: Due to how PyYAML imports nested dicts (see here), the values in the data dict must be indented four spaces instead of two.
If you're setting debconf values that requires dpkg-reconfigure, you can use the onchanges requisite to reconfigure your package:
set-default-shell: debconf.set: - name: dash - data: 'dash/sh': {'type': 'boolean', 'value': false}
reconfigure-dash: cmd.run: - name: dpkg-reconfigure -f noninteractive dash - onchanges: - debconf: set-default-shell
Every time the set-default-shell state changes, the reconfigure-dash state will also run.
NOTE: For boolean types, the value should be true or false, not 'true' or 'false'.
salt.states.debconfmod.set(name, data, **kwargs) Set debconf selections
<state_id>: debconf.set: - name: <name> - data: <question>: {'type': <type>, 'value': <value>} <question>: {'type': <type>, 'value': <value>}
name:  The package name to set answers for.
data:  A set of questions/answers for debconf. Note that everything under this must be indented twice.
question: The question the is being pre-answered
type:  The type of question that is being asked (string, boolean, select, etc.)
value: The answer to the question
salt.states.debconfmod.set_file(name, source, template=None, context=None, defaults=None, **kwargs) Set debconf selections from a file or a template
<state_id>: debconf.set_file: - source: salt://pathto/pkg.selections
<state_id>: debconf.set_file: - source: salt://pathto/pkg.selections?saltenv=myenvironment
<state_id>: debconf.set_file: - source: salt://pathto/pkg.selections.jinja2 - template: jinja - context: some_value: "false"
source: The location of the file containing the package selections
template If this setting is applied then the named templating engine will be used to render the package selections file, currently jinja, mako, and wempy are supported
salt.states.dellchassis Manage chassis via Salt Proxies.
Below is an example state that sets basic parameters:
my-dell-chassis: dellchassis.chassis: - chassis_name: my-dell-chassis - datacenter: dc-1-us - location: my-location - mode: 2 - idrac_launch: 1 - slot_names: - server-1: my-slot-name - server-2: my-other-slot-name - blade_power_states: - server-1: on - server-2: off - server-3: powercycle
However, it is possible to place the entire set of chassis configuration data in pillar. Here's an example pillar structure:
proxy: host: 10.27.20.18 admin_username: root fallback_admin_username: root passwords: - super-secret - old-secret proxytype: fx2
chassis: name: fx2-1 username: root password: saltstack1 datacenter: london location: rack-1-shelf-3 management_mode: 2 idrac_launch: 0 slot_names: - 'server-1': blade1 - 'server-2': blade2
servers: server-1: idrac_password: saltstack1 ipmi_over_lan: True ip: 172.17.17.132 netmask: 255.255.0.0 gateway: 172.17.17.1 server-2: idrac_password: saltstack1 ipmi_over_lan: True ip: 172.17.17.2 netmask: 255.255.0.0 gateway: 172.17.17.1 server-3: idrac_password: saltstack1 ipmi_over_lan: True ip: 172.17.17.20 netmask: 255.255.0.0 gateway: 172.17.17.1 server-4: idrac_password: saltstack1 ipmi_over_lan: True ip: 172.17.17.2 netmask: 255.255.0.0 gateway: 172.17.17.1
switches: switch-1: ip: 192.168.1.2 netmask: 255.255.255.0 gateway: 192.168.1.1 snmp: nonpublic password: saltstack1 switch-2: ip: 192.168.1.3 netmask: 255.255.255.0 gateway: 192.168.1.1 snmp: nonpublic password: saltstack1
And to go with it, here's an example state that pulls the data from the pillar stated above:
{% set details = pillar.get('proxy:chassis', {}) %} standup-step1: dellchassis.chassis: - name: {{ details['name'] }} - location: {{ details['location'] }} - mode: {{ details['management_mode'] }} - idrac_launch: {{ details['idrac_launch'] }} - slot_names: {% for entry details['slot_names'] %} - {{ next(iter(entry)) }}: {{ entry[next(iter(entry))]  }} {% endfor %}
blade_powercycle: dellchassis.chassis: - blade_power_states: - server-1: powercycle - server-2: powercycle - server-3: powercycle - server-4: powercycle
# Set idrac_passwords for blades.  racadm needs them to be called 'server-x' {% for k, v in details['servers'].iteritems() %} {{ k }}: dellchassis.blade_idrac: - idrac_password: {{ v['idrac_password'] }} {% endfor %}
# Set management ip addresses, passwords, and snmp strings for switches {% for k, v in details['switches'].iteritems() %} {{ k }}-switch-setup: dellchassis.switch: - name: {{ k }} - ip: {{ v['ip'] }} - netmask: {{ v['netmask'] }} - gateway: {{ v['gateway'] }} - password: {{ v['password'] }} - snmp: {{ v['snmp'] }} {% endfor %}
NOTE: This state module relies on the dracr.py execution module, which runs racadm commands on the chassis, blades, etc. The racadm command runs very slowly and, depending on your state, the proxy minion return might timeout before the racadm commands have completed. If you are repeatedly seeing minions timeout after state calls, please use the -t CLI argument to increase the timeout variable.
salt '*' state.sls my-dell-chasis-state-name -t 60
NOTE: The Dell CMC units perform adequately but many iDRACs are excruciatingly slow.  Some functions can take minutes to execute.
salt.states.dellchassis.blade_idrac(name, idrac_password=None, idrac_ipmi=None, idrac_ip=None, idrac_netmask=None, idrac_gateway=None, idrac_dnsname=None, idrac_dhcp=None) Set parameters for iDRAC in a blade.
• idrac_password -- Password to use to connect to the iDRACs directly (idrac_ipmi and idrac_dnsname must be set directly on the iDRAC.  They can't be set through the CMC.  If this password is present, use it instead of the CMC password)
• idrac_ipmi -- Enable/Disable IPMI over LAN
• idrac_ip -- Set IP address for iDRAC
• idrac_netmask -- Set netmask for iDRAC
• idrac_gateway -- Set gateway for iDRAC
• idrac_dhcp -- Turn on DHCP for iDRAC (True turns on, False does nothing becaause setting a static IP will disable DHCP).
NOTE: If any of the IP address settings is configured, all of ip, netmask, and gateway must be present
salt.states.dellchassis.chassis(name, chassis_name=None, password=None, datacenter=None, location=None, mode=None, idrac_launch=None, slot_names=None, blade_power_states=None) Manage a Dell Chassis.
chassis_name The name of the chassis.
datacenter The datacenter in which the chassis is located
location The location of the chassis.
password Password for the chassis. Note: If this password is set for the chassis, the current implementation of this state will set this password both on the chassis and the iDrac passwords on any configured blades. If the password for the blades should be distinct, they should be set separately with the blade_idrac function.
mode   The management mode of the chassis. Viable options are:
• 0: None
• 1: Monitor
• 2: Manage and Monitor
idrac_launch The iDRAC launch method of the chassis. Viable options are:
• 0: Disabled (launch iDRAC using IP address)
• 1: Enabled (launch iDRAC using DNS name)
slot_names The names of the slots, provided as a list identified by their slot numbers.
blade_power_states The power states of a blade server, provided as a list and identified by their server numbers. Viable options are:
• on: Ensure the blade server is powered on.
• off: Ensure the blade server is powered off.
• powercycle: Power cycle the blade server.
my-dell-chassis: dellchassis.chassis: - chassis_name: my-dell-chassis - location: my-location - datacenter: london - mode: 2 - idrac_launch: 1 - slot_names: - 1: my-slot-name - 2: my-other-slot-name - blade_power_states: - server-1: on - server-2: off - server-3: powercycle
salt.states.dellchassis.firmware_update(hosts=None, directory='') State to update the firmware on host using the racadm command
firmwarefile filename (string) starting with salt://
host   string representing the hostname supplied to the racadm command
directory Directory name where firmwarefile will be downloaded
dell-chassis-firmware-update: dellchassis.firmware_update: hosts: cmc: salt://firmware_cmc.exe server-1: salt://firmware.exe directory: /opt/firmwares
salt.states.dellchassis.switch(name, ip=None, netmask=None, gateway=None, dhcp=None, password=None, snmp=None) Manage switches in a Dell Chassis.
name   The switch designation (e.g. switch-1, switch-2)
ip     The Static IP Address of the switch
netmask The netmask for the static IP
gateway The gateway for the static IP
dhcp   True: Enable DHCP False: Do not change DHCP setup (disabling DHCP is automatic when a static IP is set)
password The access (root) password for the switch
snmp   The SNMP community string for the switch
my-dell-chassis: dellchassis.switch: - switch: switch-1 - ip: 192.168.1.1 - netmask: 255.255.255.0 - gateway: 192.168.1.254 - dhcp: True - password: secret - snmp: public
salt.states.disk Disk monitoring state
Monitor the state of disk resources.
The disk.status function can be used to report that the used space of a filesystem is within the specified limits.
used_space: disk.status: - name: /dev/xda1 - maximum: 79% - minimum: 11%
It can be used with an onfail requisite, for example, to take additional action in response to or in preparation for other states.
storage_threshold: disk.status: - name: /dev/xda1 - maximum: 97%
clear_cache: cmd.run: - name: rm -r /var/cache/app - onfail: - disk: storage_threshold
To use kilobytes (KB) for minimum and maximum rather than percents, specify the absolute flag:
used_space: disk.status: - name: /dev/xda1 - minimum: 1024 KB - maximum: 1048576 KB - absolute: True
salt.states.disk.status(name, maximum=None, minimum=None, absolute=False, free=False) Return the current disk usage stats for the named mount point
name   Disk mount or directory for which to check used space
maximum The maximum disk utilization
minimum The minimum disk utilization
absolute By default, the utilization is measured in percentage. Set the absolute flag to use kilobytes.
free   By default, minimum & maximum refer to the amount of used space.  Set to True to evaluate the free space instead.
salt.states.docker_container Management of Docker containers
These states were moved from the docker state module (formerly called dockerng) in the 2017.7.0 release. When running the docker_container.running state for the first time after upgrading to 2017.7.0, your container(s) may be replaced. The changes may show diffs for certain parameters which say that the old value was an empty string, and the new value is None. This is due to the fact that in prior releases Salt was passing empty strings for these values when creating the container if they were undefined in the SLS file, where now Salt simply does not pass any arguments not explicitly defined in the SLS file. Subsequent runs of the state should not replace the container if the configuration remains unchanged.
NOTE: To pull from a Docker registry, authentication must be configured. See here for more information on how to configure access to docker registries in Pillar data.
salt.states.docker_container.absent(name, force=False) Ensure that a container is absent
force  False Set to True to remove the container even if it is running
mycontainer: docker_container.absent
multiple_containers: docker_container.absent: - names: - foo - bar - baz
salt.states.docker_container.mod_watch(name, sfun=None, **kwargs) The docker_container watcher, called to invoke the watch command.
salt.states.docker_container.run(name, image=None, bg=False, failhard=True, replace=False, force=False, skip_translate=None, ignore_collisions=False, validate_ip_addrs=True, client_timeout=60, **kwargs) New in version 2018.3.0.
NOTE: If no tag is specified in the image name, and nothing matching the specified image is pulled on the minion, the docker pull that retrieves the image will pull all tags for the image. A tag of latest is not implicit for the pull. For this reason, it is recommended to specify the image in repo:tag notation.
Like the cmd.run state, only for Docker.  Does the equivalent of a docker run and returns information about the container that was created, as well as its output.
This state accepts the same arguments as docker_container.running, with the exception of watch_action, start, and shutdown_timeout (though the force argument has a different meaning in this state).
In addition, this state accepts the arguments from docker.logs, with the exception of follow, to control how logs are returned.
Additionally, the following arguments are supported:
creates A path or list of paths. Only run if one or more of the specified paths do not exist on the minion.
bg     False If True, run container in background and do not await or deliver its results.
NOTE: This may not be useful in cases where other states depend on the results of this state. Also, the logs will be inaccessible once the container exits if auto_remove is set to True, so keep this in mind.
failhard True If True, the state will return a False result if the exit code of the container is non-zero. When this argument is set to False, the state will return a True result regardless of the container's exit code.
NOTE: This has no effect if bg is set to True.
salt myminion docker.run_container myuser/myimage command=/usr/local/bin/myscript.sh
USAGE EXAMPLE
{% set pkg_version = salt.pillar.get('pkg_version', '1.0-1') %} build_package: docker_container.run: - image: myuser/builder:latest - binds: /home/myuser/builds:/build_dir - command: /scripts/build.sh {{ pkg_version }} - creates: /home/myuser/builds/myapp-{{ pkg_version }}.noarch.rpm - replace: True - networks: - mynet - require: - docker_network: mynet
salt.states.docker_container.running(name, image=None, skip_translate=None, ignore_collisions=False, validate_ip_addrs=True, force=False, watch_action='force', start=True, shutdown_timeout=None, client_timeout=60, networks=None, **kwargs)
image  Image to use for the container
NOTE: This state will pull the image if it is not present. However, if the image needs to be built from a Dockerfile or loaded from a saved image, or if you would like to use requisites to trigger a replacement of the container when the image is updated, then the docker_image.present state should be used to manage the image.
Changed in version 2018.3.0: If no tag is specified in the image name, and nothing matching the specified image is pulled on the minion, the docker pull that retrieves the image will pull all tags for the image. A tag of latest is no longer implicit for the pull. For this reason, it is recommended to specify the image in repo:tag notation.
For example, imagine that there is an issue with processing the port_bindings argument, and the following configuration no longer works as expected:
mycontainer: docker_container.running: - image: 7.3.1611 - port_bindings: - 10.2.9.10:8080:80
By using skip_translate, you can forego the input translation and configure the port binding in the format docker-py needs:
mycontainer: docker_container.running: - image: 7.3.1611 - skip_translate: port_bindings - port_bindings: {8080: [('10.2.9.10', 80)], '4193/udp': 9314}
ignore_collisions False Since many of docker-py's arguments differ in name from their CLI counterparts (with which most Docker users are more familiar), Salt detects usage of these and aliases them to the docker-py version of that argument so that both CLI and API versions of a given argument are supported. However, if both the alias and the docker-py version of the same argument (e.g. env and environment) are used, an error will be raised. Set this argument to True to suppress these errors and keep the docker-py version of the argument.
force  False Set this parameter to True to force Salt to re-create the container irrespective of whether or not it is configured as desired.
watch_action force Control what type of action is taken when this state watches another state that has changes. The default action is force, which runs the state with force set to True, triggering a rebuild of the container.
If any other value is passed, it will be assumed to be a kill signal.  If the container matches the specified configuration, and is running, then the action will be to send that signal to the container. Kill signals can be either strings or numbers, and are defined in the Standard Signals section of the signal(7) manpage. Run man 7 signal on a Linux host to browse this manpage. For example:
mycontainer: docker_container.running: - image: busybox - watch_action: SIGHUP - watch: - file: some_file
NOTE: If the container differs from the specified configuration, or is not running, then instead of sending a signal to the container, the container will be re-created/started and no signal will be sent.
start  True Set to False to suppress starting of the container if it exists, matches the desired configuration, but is not running. This is useful for data-only containers, or for non-daemonized container processes, such as the Django migrate and collectstatic commands. In instances such as this, the container only needs to be started the first time.
shutdown_timeout If the container needs to be replaced, the container will be stopped using docker.stop. If a shutdown_timout is not set, and the container was created using stop_timeout, that timeout will be used. If neither of these values were set, then a timeout of 10 seconds will be used.
Changed in version 2017.7.0: This option was renamed from stop_timeout to shutdown_timeout to accommodate the stop_timeout container configuration setting.
NETWORK MANAGEMENT
Changed in version 2019.2.0: If the networks option is used, any networks (including the default bridge network) which are not specified will be disconnected.
The networks argument can be used to ensure that a container is attached to one or more networks. Optionally, arguments can be passed to the networks. In the example below, net1 is being configured with arguments, while net2 and bridge are being configured without arguments:
foo: docker_container.running: - image: myuser/myimage:foo - networks: - net1: - aliases: - bar - baz - ipv4_address: 10.0.20.50 - net2 - bridge - require: - docker_network: net1 - docker_network: net2
The supported arguments are the ones from the docker-py's connect_container_to_network function (other than container and net_id).
IMPORTANT: Unlike with the arguments described in the CONTAINER CONFIGURATION PARAMETERS section below, these network configuration parameters are not translated at all.  Consult the connect_container_to_network documentation for the correct type/format of data to pass.
To start a container with no network connectivity (only possible in 2019.2.0 and later) pass this option as an empty list. For example:
foo: docker_container.running: - image: myuser/myimage:foo - networks: []
CONTAINER CONFIGURATION PARAMETERS
foo: docker_container.running: - image: bar/baz:latest - auto_remove: True
<read_only> can be either rw for read-write access, or ro for read-only access. When omitted, it is assumed to be read-write.
Binds can be expressed as a comma-separated list or a YAML list. The below two examples are equivalent:
foo: docker_container.running: - image: bar/baz:latest - binds: /srv/www:/var/www:ro,/etc/foo.conf:/usr/local/etc/foo.conf:rw
foo: docker_container.running: - image: bar/baz:latest - binds: - /srv/www:/var/www:ro - /home/myuser/conf/foo.conf:/etc/foo.conf:rw
However, in cases where both ro/rw and an selinux context are combined, the only option is to use a YAML list, like so:
foo: docker_container.running: - image: bar/baz:latest - binds: - /srv/www:/var/www:ro,Z - /home/myuser/conf/foo.conf:/etc/foo.conf:rw,Z
Since the second bind in the previous example is mounted read-write, the rw and comma can be dropped. For example:
foo: docker_container.running: - image: bar/baz:latest - binds: - /srv/www:/var/www:ro,Z - /home/myuser/conf/foo.conf:/etc/foo.conf:Z
foo: docker_container.running: - image: bar/baz:latest - blkio_weight: 100
blkio_weight_device Block IO weight (relative device weight), specified as a list of expressions in the format PATH:RATE
foo: docker_container.running: - image: bar/baz:latest - blkio_weight_device: /dev/sda:100
cap_add List of capabilities to add within the container. Can be expressed as a comma-separated list or a Python list. The below two examples are equivalent:
foo: docker_container.running: - image: bar/baz:latest - cap_add: SYS_ADMIN,MKNOD
foo: docker_container.running: - image: bar/baz:latest - cap_add: - SYS_ADMIN - MKNOD
NOTE: This option requires Docker 1.2.0 or newer.
cap_drop List of capabilities to drop within the container. Can be expressed as a comma-separated list or a Python list. The below two examples are equivalent:
foo: docker_container.running: - image: bar/baz:latest - cap_drop: SYS_ADMIN,MKNOD
foo: docker_container.running: - image: bar/baz:latest - cap_drop: - SYS_ADMIN - MKNOD
foo: docker_container.running: - image: bar/baz:latest - command: bash
foo: docker_container.running: - image: bar/baz:latest - cpuset_cpus: "0,1"
foo: docker_container.running: - image: bar/baz:latest - cpuset_mems: "0,1"
foo: docker_container.running: - image: bar/baz:latest - cpu_group: 100000
foo: docker_container.running: - image: bar/baz:latest - cpu_period: 50000
foo: docker_container.running: - image: bar/baz:latest - cpu_shares: 512
foo: docker_container.running: - image: bar/baz:latest - detach: True
devices List of host devices to expose within the container. Can be expressed as a comma-separated list or a YAML list. The below two examples are equivalent:
foo: docker_container.running: - image: bar/baz:latest - devices: /dev/net/tun,/dev/xvda1:/dev/xvda1,/dev/xvdb1:/dev/xvdb1:r
foo: docker_container.running: - image: bar/baz:latest - devices: - /dev/net/tun - /dev/xvda1:/dev/xvda1 - /dev/xvdb1:/dev/xvdb1:r
device_read_bps Limit read rate (bytes per second) from a device, specified as a list of expressions in the format PATH:RATE, where RATE is either an integer number of bytes, or a string ending in kb, mb, or gb. Can be expressed as a comma-separated list or a YAML list. The below two examples are equivalent:
foo: docker_container.running: - image: bar/baz:latest - devices_read_bps: /dev/sda:1mb,/dev/sdb:5mb
foo: docker_container.running: - image: bar/baz:latest - devices_read_bps: - /dev/sda:1mb - /dev/sdb:5mb
device_read_iops Limit read rate (I/O per second) from a device, specified as a list of expressions in the format PATH:RATE, where RATE is a number of I/O operations. Can be expressed as a comma-separated list or a YAML list. The below two examples are equivalent:
foo: docker_container.running: - image: bar/baz:latest - devices_read_iops: /dev/sda:1000,/dev/sdb:500
foo: docker_container.running: - image: bar/baz:latest - devices_read_iops: - /dev/sda:1000 - /dev/sdb:500
device_write_bps Limit write rate (bytes per second) from a device, specified as a list of expressions in the format PATH:RATE, where RATE is either an integer number of bytes, or a string ending in kb, mb, or gb. Can be expressed as a comma-separated list or a YAML list. The below two examples are equivalent:
foo: docker_container.running: - image: bar/baz:latest - devices_write_bps: /dev/sda:1mb,/dev/sdb:5mb
foo: docker_container.running: - image: bar/baz:latest - devices_write_bps: - /dev/sda:1mb - /dev/sdb:5mb
device_write_iops Limit write rate (I/O per second) from a device, specified as a list of expressions in the format PATH:RATE, where RATE is a number of I/O operations. Can be expressed as a comma-separated list or a YAML list. The below two examples are equivalent:
foo: docker_container.running: - image: bar/baz:latest - devices_write_iops: /dev/sda:1000,/dev/sdb:500
foo: docker_container.running: - image: bar/baz:latest - devices_write_iops: - /dev/sda:1000 - /dev/sdb:500
dns    List of DNS nameservers. Can be expressed as a comma-separated list or a YAML list. The below two examples are equivalent:
foo: docker_container.running: - image: bar/baz:latest - dns: 8.8.8.8,8.8.4.4
foo: docker_container.running: - image: bar/baz:latest - dns: - 8.8.8.8 - 8.8.4.4
dns_opt Additional options to be added to the container’s resolv.conf file.  Can be expressed as a comma-separated list or a YAML list. The below two examples are equivalent:
foo: docker_container.running: - image: bar/baz:latest - dns_opt: ndots:9
foo: docker_container.running: - image: bar/baz:latest - dns_opt: - ndots:9
dns_search List of DNS search domains. Can be expressed as a comma-separated list or a YAML list. The below two examples are equivalent:
foo: docker_container.running: - image: bar/baz:latest - dns_search: foo1.domain.tld,foo2.domain.tld
foo: docker_container.running: - image: bar/baz:latest - dns_search: - foo1.domain.tld - foo2.domain.tld
foo: docker_container.running: - image: bar/baz:latest - dommainname: domain.tld
entrypoint Entrypoint for the container
foo: docker_container.running: - image: bar/baz:latest - entrypoint: "mycmd --arg1 --arg2"
This argument can also be specified as a list:
foo: docker_container.running: - image: bar/baz:latest - entrypoint: - mycmd - --arg1 - --arg2
environment Either a list of variable/value mappings, or a list of strings in the format VARNAME=value. The below three examples are equivalent:
foo: docker_container.running: - image: bar/baz:latest - environment: - VAR1: value - VAR2: value
foo: docker_container.running: - image: bar/baz:latest - environment: 'VAR1=value,VAR2=value'
foo: docker_container.running: - image: bar/baz:latest - environment: - VAR1=value - VAR2=value
extra_hosts Additional hosts to add to the container's /etc/hosts file. Can be expressed as a comma-separated list or a Python list. The below two examples are equivalent:
foo: docker_container.running: - image: bar/baz:latest - extra_hosts: web1:10.9.8.7,web2:10.9.8.8
foo: docker_container.running: - image: bar/baz:latest - extra_hosts: - web1:10.9.8.7 - web2:10.9.8.8
NOTE: This option requires Docker 1.3.0 or newer.
group_add List of additional group names and/or IDs that the container process will run as. Can be expressed as a comma-separated list or a YAML list.  The below two examples are equivalent:
foo: docker_container.running: - image: bar/baz:latest - group_add: web,network
foo: docker_container.running: - image: bar/baz:latest - group_add: - web - network
hostname Hostname of the container. If not provided, the value passed as the container's``name`` will be used for the hostname.
foo: docker_container.running: - image: bar/baz:latest - hostname: web1
WARNING: hostname cannot be set if network_mode is set to host. The below example will result in an error:
foo: docker_container.running: - image: bar/baz:latest - hostname: web1 - network_mode: host
interactive (or stdin_open) False Leave stdin open, even if not attached
foo: docker_container.running: - image: bar/baz:latest - interactive: True
foo: docker_container.running: - image: bar/baz:latest - ipc_mode: container:foo
foo: docker_container.running: - image: bar/baz:latest - ipc_mode: host
foo: docker_container.running: - image: bar/baz:latest - isolation: hyperv
labels Add metadata to the container. Labels can be set both with and without values, and labels with values can be passed either as key=value or key: value pairs. For example, while the below would be very confusing to read, it is technically valid, and demonstrates the different ways in which labels can be passed:
mynet: docker_network.present: - labels: - foo - bar=baz - hello: world
The labels can also simply be passed as a YAML dictionary, though this can be error-prone due to some idiosyncrasies with how PyYAML loads nested data structures:
foo: docker_network.present: - labels: foo: '' bar: baz hello: world
Changed in version 2018.3.0: Methods for specifying labels can now be mixed. Earlier releases required either labels with or without values.
links  Link this container to another. Links can be specified as a list of mappings or a comma-separated or Python list of expressions in the format <container_name_or_id>:<link_alias>. The below three examples are equivalent:
foo: docker_container.running: - image: bar/baz:latest - links: - web1: link1 - web2: link2
foo: docker_container.running: - image: bar/baz:latest - links: web1:link1,web2:link2
foo: docker_container.running: - image: bar/baz:latest - links: - web1:link1 - web2:link2
log_driver and log_opt Set container's logging driver and options to configure that driver.  Requires Docker 1.6 or newer.
foo: docker_container.running: - image: bar/baz:latest - log_driver: syslog - log_opt: - syslog-address: tcp://192.168.0.42 - syslog-facility: daemon
The log_opt can also be expressed as a comma-separated or YAML list of key=value pairs. The below two examples are equivalent to the above one:
foo: docker_container.running: - image: bar/baz:latest - log_driver: syslog - log_opt: "syslog-address=tcp://192.168.0.42,syslog-facility=daemon"
foo: docker_container.running: - image: bar/baz:latest - log_driver: syslog - log_opt: - syslog-address=tcp://192.168.0.42 - syslog-facility=daemon
lxc_conf Additional LXC configuration parameters to set before starting the container. Either a list of variable/value mappings, or a list of strings in the format VARNAME=value. The below three examples are equivalent:
foo: docker_container.running: - image: bar/baz:latest - lxc_conf: - lxc.utsname: docker - lxc.arch: x86_64
foo: docker_container.running: - image: bar/baz:latest - lxc_conf: lxc.utsname=docker,lxc.arch=x86_64
foo: docker_container.running: - image: bar/baz:latest - lxc_conf: - lxc.utsname=docker - lxc.arch=x86_64
foo: docker_container.running: - image: bar/baz:latest - mac_address: 01:23:45:67:89:0a
foo: docker_container.running: - image: bar/baz:latest - mem_limit: 512M
foo: docker_container.running: - image: bar/baz:latest - mem_swappiness: 60
foo: docker_container.running: - image: bar/baz:latest - memswap_limit: 1G
foo: docker_container.running: - image: bar/baz:latest - network_disabled: True
WARNING: Using host mode gives the container full access to the hosts system's services (such as D-bus), and is therefore considered insecure.
foo: docker_container.running: - image: bar/baz:latest - network_mode: "none"
foo: docker_container.running: - image: bar/baz:latest - network_mode: container:web1
foo: docker_container.running: - image: bar/baz:latest - oom_kill_disable: False
foo: docker_container.running: - image: bar/baz:latest - oom_score_adj: 500
foo: docker_container.running: - image: bar/baz:latest - pid_mode: host
NOTE: This option requires Docker 1.5.0 or newer.
foo: docker_container.running: - image: bar/baz:latest - pids_limit: 2000
port_bindings (or publish) Bind exposed ports. Port bindings should be passed in the same way as the --publish argument to the docker run CLI command:
Multiple bindings can be separated by commas, or expressed as a YAML list, and port ranges can be defined using dashes. The below two examples are equivalent:
foo: docker_container.running: - image: bar/baz:latest - port_bindings: "4505-4506:14505-14506,2123:2123/udp,8080"
foo: docker_container.running: - image: bar/baz:latest - port_bindings: - 4505-4506:14505-14506 - 2123:2123/udp - 8080
ports  A list of ports to expose on the container. Can either be a comma-separated list or a YAML list. If the protocol is omitted, the port will be assumed to be a TCP port. The below two examples are equivalent:
foo: docker_container.running: - image: bar/baz:latest - ports: 1111,2222/udp
foo: docker_container.running: - image: bar/baz:latest - ports: - 1111 - 2222/udp
foo: docker_container.running: - image: bar/baz:latest - privileged: True
publish_all_ports (or publish_all) False Publish all ports to the host
foo: docker_container.running: - image: bar/baz:latest - ports: 8080 - publish_all_ports: True
foo: docker_container.running: - image: bar/baz:latest - read_only: True
foo: docker_container.running: - image: bar/baz:latest - restart_policy: on-failure:5
bar: docker_container.running: - image: bar/baz:latest - restart_policy: always
security_opt (or security_opts): Security configuration for MLS systems such as SELinux and AppArmor.  Can be expressed as a comma-separated list or a YAML list. The below two examples are equivalent:
foo: docker_container.running: - image: bar/baz:latest - security_opt: apparmor:unconfined
foo: docker_container.running: - image: bar/baz:latest - security_opt: - apparmor:unconfined
foo: docker_container.running: - image: bar/baz:latest - shm_size: 128M
stop_signal Specify the signal docker will send to the container when stopping.  Useful when running systemd as PID 1 inside the container.
foo: docker_container.running: - image: bar/baz:latest - stop_signal: SIGRTMIN+3
NOTE: This option requires Docker 1.9.0 or newer and docker-py 1.7.0 or newer.
foo: docker_container.running: - image: bar/baz:latest - stop_timeout: 5
NOTE: In releases prior to 2017.7.0, this option was not set in the container configuration, but rather this timeout was enforced only when shutting down an existing container to replace it. To remove the ambiguity, and to allow for the container to have a stop timeout set for it, the old stop_timeout argument has been renamed to shutdown_timeout, while stop_timeout now refer's to the container's configured stop timeout.
storage_opt Storage driver options for the container. Can be either a list of strings in the format option=value, or a list of mappings between option and value. The below three examples are equivalent:
foo: docker_container.running: - image: bar/baz:latest - storage_opt: - dm.basesize: 40G
foo: docker_container.running: - image: bar/baz:latest - storage_opt: dm.basesize=40G
foo: docker_container.running: - image: bar/baz:latest - storage_opt: - dm.basesize=40G
sysctls (or sysctl) Set sysctl options for the container. Can be either a list of strings in the format option=value, or a list of mappings between option and value. The below three examples are equivalent:
foo: docker_container.running: - image: bar/baz:latest - sysctls: - fs.nr_open: 1048576 - kernel.pid_max: 32768
foo: docker_container.running: - image: bar/baz:latest - sysctls: fs.nr_open=1048576,kernel.pid_max=32768
foo: docker_container.running: - image: bar/baz:latest - sysctls: - fs.nr_open=1048576 - kernel.pid_max=32768
tmpfs  A map of container directories which should be replaced by tmpfs mounts and their corresponding mount options.
foo: docker_container.running: - image: bar/baz:latest - tmpfs: - /run: rw,noexec,nosuid,size=65536k
foo: docker_container.running: - image: bar/baz:latest - tty: True
ulimits List of ulimits. These limits should be passed in the format <ulimit_name>:<soft_limit>:<hard_limit>, with the hard limit being optional. Can be expressed as a comma-separated list or a YAML list.  The below two examples are equivalent:
foo: docker_container.running: - image: bar/baz:latest - ulimits: nofile=1024:1024,nproc=60
foo: docker_container.running: - image: bar/baz:latest - ulimits: - nofile=1024:1024 - nproc=60
foo: docker_container.running: - image: bar/baz:latest - user: foo
userns_mode (or user_ns_mode) Sets the user namsepace mode, when the user namespace remapping option is enabled
foo: docker_container.running: - image: bar/baz:latest - userns_mode: host
volumes (or volume) List of directories to expose as volumes. Can be expressed as a comma-separated list or a YAML list. The below two examples are equivalent:
foo: docker_container.running: - image: bar/baz:latest - volumes: /mnt/vol1,/mnt/vol2
foo: docker_container.running: - image: bar/baz:latest - volumes: - /mnt/vol1 - /mnt/vol2
volumes_from Container names or IDs from which the container will get volumes. Can be expressed as a comma-separated list or a YAML list. The below two examples are equivalent:
foo: docker_container.running: - image: bar/baz:latest - volumes_from: foo
foo: docker_container.running: - image: bar/baz:latest - volumes_from: - foo
volume_driver sets the container's volume driver
foo: docker_container.running: - image: bar/baz:latest - volume_driver: foobar
foo: docker_container.running: - image: bar/baz:latest - working_dir: /var/log/nginx
salt.states.docker_container.stopped(name=None, containers=None, shutdown_timeout=None, unpause=False, error_on_absent=True, **kwargs) Ensure that a container (or containers) is stopped
name   Name or ID of the container
containers Run this state on more than one container at a time. The following two examples accomplish the same thing:
stopped_containers: docker_container.stopped: - names: - foo - bar - baz
stopped_containers: docker_container.stopped: - containers: - foo - bar - baz
However, the second example will be a bit quicker since Salt will stop all specified containers in a single run, rather than executing the state separately on each image (as it would in the first example).
shutdown_timeout Timeout for graceful shutdown of the container. If this timeout is exceeded, the container will be killed. If this value is not passed, then the container's configured stop_timeout will be observed. If stop_timeout was also unset on the container, then a timeout of 10 seconds will be used.
unpause False Set to True to unpause any paused containers before stopping. If unset, then an error will be raised for any container that was paused.
error_on_absent True By default, this state will return an error if any of the specified containers are absent. Set this to False to suppress that error.
salt.states.docker_image Management of Docker images
These states were moved from the docker state module (formerly called dockerng) in the 2017.7.0 release.
salt.states.docker_image.absent(name=None, images=None, force=False) Ensure that an image is absent from the Minion. Image names can be specified either using repo:tag notation, or just the repo name (in which case a tag of latest is assumed).
images Run this state on more than one image at a time. The following two examples accomplish the same thing:
remove_images: docker_image.absent: - names: - busybox - centos:6 - nginx
remove_images: docker_image.absent: - images: - busybox - centos:6 - nginx
However, the second example will be a bit quicker since Salt will do all the deletions in a single run, rather than executing the state separately on each image (as it would in the first example).
force  False Salt will fail to remove any images currently in use by a container.  Set this option to true to remove the image even if it is already present.
NOTE: This option can also be overridden by Pillar data. If the Minion has a pillar variable named docker.running.force which is set to True, it will turn on this option. This pillar variable can even be set at runtime. For example:
salt myminion state.sls docker_stuff pillar="{docker.force: True}"
If this pillar variable is present and set to False, then it will turn off this option.
For more granular control, setting a pillar variable named docker.force.image_name will affect only the named image.
salt.states.docker_image.mod_watch(name, sfun=None, **kwargs) The docker_image  watcher, called to invoke the watch command.
salt.states.docker_image.present(name, tag=None, build=None, load=None, force=False, insecure_registry=False, client_timeout=60, dockerfile=None, sls=None, base='opensuse/python', saltenv='base', pillarenv=None, pillar=None, **kwargs) Changed in version 2018.3.0: The tag argument has been added. It is now required unless pulling from a registry.
Ensure that an image is present. The image can either be pulled from a Docker registry, built from a Dockerfile, loaded from a saved image, or built by running SLS files against a base image.
If none of the build, load, or sls arguments are used, then Salt will pull from the configured registries. If the specified image already exists, it will not be pulled unless force is set to True. Here is an example of a state that will pull an image from the Docker Hub:
myuser/myimage: docker_image.present: - tag: mytag
tag    Tag name for the image. Required when using build, load, or sls to create the image, but optional if pulling from a repository.
build  Path to directory on the Minion containing a Dockerfile
myuser/myimage: docker_image.present: - build: /home/myuser/docker/myimage - tag: mytag
myuser/myimage: docker_image.present: - build: /home/myuser/docker/myimage - tag: mytag - dockerfile: Dockerfile.alternative
The image will be built using docker.build and the specified image name and tag will be applied to it.
Changed in version 2018.3.0: The tag must be manually specified using the tag argument.
load   Loads a tar archive created with docker.save (or the docker save Docker CLI command), and assigns it the specified repo and tag.
myuser/myimage: docker_image.present: - load: salt://path/to/image.tar - tag: mytag
force  False Set this parameter to True to force Salt to pull/build/load the image even if it is already present.
client_timeout Timeout in seconds for the Docker client. This is not a timeout for the state, but for receiving a response from the API.
dockerfile Allows for an alternative Dockerfile to be specified.  Path to alternative Dockefile is relative to the build path for the Docker container.
sls    Allow for building of image with docker.sls_build by specifying the SLS files with which to build. This can be a list or comma-separated string.
myuser/myimage: docker_image.present: - tag: latest - sls: - webapp1 - webapp2 - base: centos - saltenv: base
base   Base image with which to start docker.sls_build
saltenv Specify the environment from which to retrieve the SLS indicated by the mods parameter.
Changed in version 2018.3.0: Now uses the effective saltenv if not explicitly passed. In earlier versions, base was assumed as a default.
salt.states.docker_network Management of Docker networks
salt.states.docker_network.absent(name) Ensure that a network is absent.
name   Name of the network
network_foo: docker_network.absent
salt.states.docker_network.present(name, skip_translate=None, ignore_collisions=False, validate_ip_addrs=True, containers=None, reconnect=True, **kwargs) Changed in version 2018.3.0: Support added for network configuration options other than driver and driver_opts, as well as IPAM configuration.
Ensure that a network is present
NOTE: This state supports all arguments for network and IPAM pool configuration which are available for the release of docker-py installed on the minion. For that reason, the arguments described below in the NETWORK CONFIGURATION and IP ADDRESS MANAGEMENT (IPAM) sections may not accurately reflect what is available on the minion. The docker.get_client_args function can be used to check the available arguments for the installed version of docker-py (they are found in the network_config and ipam_config sections of the return data), but Salt will not prevent a user from attempting to use an argument which is unsupported in the release of Docker which is installed. In those cases, network creation be attempted but will fail.
skip_translate This function translates Salt SLS input into the format which docker-py expects. However, in the event that Salt's translation logic fails (due to potential changes in the Docker Remote API, or to bugs in the translation code), this argument can be used to exert granular control over which arguments are translated and which are not.
validate_ip_addrs True For parameters which accept IP addresses/subnets as input, validation will be performed. To disable, set this to False.
containers A list of containers which should be connected to this network.
NOTE: As of the 2018.3.0 release, this is not the recommended way of managing a container's membership in a network, for a couple reasons:
1. It does not support setting static IPs, aliases, or links in the container's IP configuration.
2. If a docker_container.running state replaces a container, it will not be reconnected to the network until the docker_network.present state is run again. Since containers often have require requisites to ensure that the network is present, this means that the docker_network.present state ends up being run before the docker_container.running, leaving the container unattached at the end of the Salt run.
For these reasons, it is recommended to use docker_container.running's network management support.
reconnect True If containers is not used, and the network is replaced, then Salt will keep track of the containers which were connected to the network and reconnect them to the network after it is replaced. Salt will first attempt to reconnect using the same IP the container had before the network was replaced. If that fails (for instance, if the network was replaced because the subnet was modified), then the container will be reconnected without an explicit IP address, and its IP will be assigned by Docker.
Set this option to False to keep Salt from trying to reconnect containers. This can be useful in some cases when managing static IPs in docker_container.running. For instance, if a network's subnet is modified, it is likely that the static IP will need to be updated in the docker_container.running state as well. When the network is replaced, the initial reconnect attempt would fail, and the container would be reconnected with an automatically-assigned IP address. Then, when the docker_container.running state executes, it would disconnect the network again and reconnect using the new static IP. Disabling the reconnect behavior in these cases would prevent the unnecessary extra reconnection.
mynet: docker_network.present: - driver: macvlan