neulab/tldr huggingface dataset:
driver_opts (or driver_opt, or options) Options for the network driver. Either a dictionary of option names and values or a Python list of strings in the format varname=value. The below three examples are equivalent:
mynet: docker_network.present: - driver: macvlan - driver_opts: macvlan_mode=bridge,parent=eth0
mynet: docker_network.present: - driver: macvlan - driver_opts: - macvlan_mode=bridge - parent=eth0
mynet: docker_network.present: - driver: macvlan - driver_opts: - macvlan_mode: bridge - parent: eth0
The options can also simply be passed as a dictionary, though this can be error-prone due to some idiosyncrasies with how PyYAML loads nested data structures:
mynet: docker_network.present: - driver: macvlan - driver_opts: macvlan_mode: bridge parent: eth0
mynet: docker_network.present: - check_duplicate: False
mynet: docker_network.present: - internal: True
labels Add metadata to the network. 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: - enable_ipv6: True
mynet: docker_network.present: - attachable: True
NOTE: This option cannot be reliably managed on CentOS 7. This is because while support for this option was added in API version 1.24, its value was not added to the inpsect results until API version 1.26.  The version of Docker which is available for CentOS 7 runs API version 1.24, meaning that while Salt can pass this argument to the API, it has no way of knowing the value of this config option in an existing Docker network.
mynet: docker_network.present: - scope: local
mynet: docker_network.present: - ingress: True
This state supports networks with either IPv4, or both IPv4 and IPv6. If configuring IPv4, then you can pass the IPAM pool arguments below as individual arguments. However, if configuring IPv4 and IPv6, the arguments must be passed as a list of dictionaries, in the ipam_pools argument (click here for some examples). These docs also have more information on these arguments.
mynet: docker_network.present: - ipam_driver: foo
ipam_opts Options for the IPAM driver. Either a dictionary of option names and values or a Python list of strings in the format varname=value. The below three examples are equivalent:
mynet: docker_network.present: - ipam_driver: foo - ipam_opts: foo=bar,baz=qux
mynet: docker_network.present: - ipam_driver: foo - ipam_opts: - foo=bar - baz=qux
mynet: docker_network.present: - ipam_driver: foo - ipam_opts: - foo: bar - baz: qux
mynet: docker_network.present: - ipam_driver: macvlan - ipam_opts: foo: bar baz: qux
gateway IPv4 or IPv6 gateway for the master subnet
IPAM CONFIGURATION EXAMPLES
Below is an example of an IPv4-only network (keep in mind that subnet is the only required argument).
mynet: docker_network.present: - subnet: 10.0.20.0/24 - iprange: 10.0.20.128/25 - gateway: 10.0.20.254 - aux_addresses: - foo.bar.tld: 10.0.20.50 - hello.world.tld: 10.0.20.51
NOTE: The aux_addresses can be passed differently, in the same way that driver_opts and ipam_opts can.
This same network could also be configured this way:
mynet: docker_network.present: - ipam_pools: - subnet: 10.0.20.0/24 iprange: 10.0.20.128/25 gateway: 10.0.20.254 aux_addresses: foo.bar.tld: 10.0.20.50 hello.world.tld: 10.0.20.51
Here is an example of a mixed IPv4/IPv6 subnet.
mynet: docker_network.present: - ipam_pools: - subnet: 10.0.20.0/24 gateway: 10.0.20.1 - subnet: fe3f:2180:26:1::/123 gateway: fe3f:2180:26:1::1
salt.states.docker_volume Management of Docker volumes
salt.states.docker_volume.absent(name, driver=None) Ensure that a volume is absent.
Changed in version 2017.7.0: This state was renamed from docker.volume_absent to docker_volume.absent
volume_foo: docker_volume.absent
salt.states.docker_volume.present(name, driver=None, driver_opts=None, force=False) Ensure that a volume is present.
Changed in version 2015.8.6: This state no longer deletes and re-creates a volume if the existing volume's driver does not match the driver parameter (unless the force parameter is set to True).
Changed in version 2017.7.0: This state was renamed from docker.volume_present to docker_volume.present
driver Type of driver for that volume.  If None and the volume does not yet exist, the volume will be created using Docker's default driver.  If None and the volume does exist, this function does nothing, even if the existing volume's driver is not the Docker default driver.  (To ensure that an existing volume's driver matches the Docker default, you must explicitly name Docker's default driver here.)
driver_opts Options for the volume driver
force  False If the volume already exists but the existing volume's driver does not match the driver specified by the driver parameter, this parameter controls whether the function errors out (if False) or deletes and re-creates the volume (if True).
volume_foo: docker_volume.present
volume_bar: docker_volume.present - name: bar - driver: local - driver_opts: foo: bar
volume_bar: docker_volume.present - name: bar - driver: local - driver_opts: - foo: bar - option: value
salt.states.drac Management of Dell DRAC
The DRAC module is used to create and manage DRAC cards on Dell servers
Ensure the user damian is present
damian: drac.present: - name: damian - password: secret - permission: login,test_alerts,clear_logs
Ensure the user damian does not exist
damian: drac.absent: - name: damian
Ensure DRAC network is in a consistent state
my_network: drac.network: - ip: 10.225.108.29 - netmask: 255.255.255.224 - gateway: 10.225.108.1
salt.states.drac.absent(name) Ensure a user does not exist on the Dell DRAC
name:  The users username
salt.states.drac.network(ip, netmask, gateway) Ensure the DRAC network settings are consistent
salt.states.drac.present(name, password, permission) Ensure the user exists on the Dell DRAC
password The password used to authenticate
permission The permissions that should be assigned to a user
salt.states.dvs Manage VMware distributed virtual switches (DVSs) and their distributed virtual portgroups (DVportgroups).
Several settings can be changed for DVSs and DVporgroups. Here are two examples covering all of the settings. Fewer settings can be used
DVS 'name': 'dvs1', 'max_mtu': 1000, 'uplink_names': [ 'dvUplink1', 'dvUplink2', 'dvUplink3' ], 'capability': { 'portgroup_operation_supported': false, 'operation_supported': true, 'port_operation_supported': false }, 'lacp_api_version': 'multipleLag', 'contact_email': 'foo@email.com', 'product_info': { 'version': '6.0.0', 'vendor': 'VMware, Inc.', 'name': 'DVS' }, 'network_resource_management_enabled': true, 'contact_name': 'me@email.com', 'infrastructure_traffic_resource_pools': [ { 'reservation': 0, 'limit': 1000, 'share_level': 'high', 'key': 'management', 'num_shares': 100 }, { 'reservation': 0, 'limit': -1, 'share_level': 'normal', 'key': 'faultTolerance', 'num_shares': 50 }, { 'reservation': 0, 'limit': 32000, 'share_level': 'normal', 'key': 'vmotion', 'num_shares': 50 }, { 'reservation': 10000, 'limit': -1, 'share_level': 'normal', 'key': 'virtualMachine', 'num_shares': 50 }, { 'reservation': 0, 'limit': -1, 'share_level': 'custom', 'key': 'iSCSI', 'num_shares': 75 }, { 'reservation': 0, 'limit': -1, 'share_level': 'normal', 'key': 'nfs', 'num_shares': 50 }, { 'reservation': 0, 'limit': -1, 'share_level': 'normal', 'key': 'hbr', 'num_shares': 50 }, { 'reservation': 8750, 'limit': 15000, 'share_level': 'high', 'key': 'vsan', 'num_shares': 100 }, { 'reservation': 0, 'limit': -1, 'share_level': 'normal', 'key': 'vdp', 'num_shares': 50 } ], 'link_discovery_protocol': { 'operation': 'listen', 'protocol': 'cdp' }, 'network_resource_control_version': 'version3', 'description': 'Managed by Salt. Random settings.'
Note: The mandatory attribute is: name.
Portgroup 'security_policy': { 'allow_promiscuous': true, 'mac_changes': false, 'forged_transmits': true }, 'name': 'vmotion-v702', 'out_shaping': { 'enabled': true, 'average_bandwidth': 1500, 'burst_size': 4096, 'peak_bandwidth': 1500 }, 'num_ports': 128, 'teaming': { 'port_order': { 'active': [ 'dvUplink2' ], 'standby': [ 'dvUplink1' ] }, 'notify_switches': false, 'reverse_policy': true, 'rolling_order': false, 'policy': 'failover_explicit', 'failure_criteria': { 'check_error_percent': true, 'full_duplex': false, 'check_duplex': false, 'percentage': 50, 'check_speed': 'minimum', 'speed': 20, 'check_beacon': true } }, 'type': 'earlyBinding', 'vlan_id': 100, 'description': 'Managed by Salt. Random settings.'
Note: The mandatory attributes are: name, type.
salt.states.dvs.dvs_configured(name, dvs) Configures a DVS.
Creates a new DVS, if it doesn't exist in the provided datacenter or reconfigures it if configured differently.
dvs    DVS dict representations (see module sysdocs)
salt.states.dvs.portgroups_configured(name, dvs, portgroups) Configures portgroups on a DVS.
Creates/updates/removes portgroups in a provided DVS
dvs    Name of the DVS
portgroups Portgroup dict representations (see module sysdocs)
salt.states.dvs.uplink_portgroup_configured(name, dvs, uplink_portgroup) Configures the uplink portgroup on a DVS. The state assumes there is only one uplink portgroup.
upling_portgroup Uplink portgroup dict representations (see module sysdocs)
salt.states.elasticsearch State module to manage Elasticsearch.
salt.states.elasticsearch.alias_absent(name, index) Ensure that the index alias is absent.
name   Name of the index alias to remove
index  Name of the index for the alias
salt.states.elasticsearch.alias_present(name, index, definition=None) Ensure that the named index alias is present.
name   Name of the alias
index  Name of the index
definition Optional dict for filters as per https://www.elastic.co/guide/en/elasticsearch/reference/current/indices-aliases.html
mytestalias: elasticsearch.alias_present: - index: testindex - definition: filter: term: user: kimchy
salt.states.elasticsearch.index_absent(name) Ensure that the named index is absent.
name   Name of the index to remove
salt.states.elasticsearch.index_present(name, definition=None) Ensure that the named index is present.
name   Name of the index to add
definition Optional dict for creation parameters as per https://www.elastic.co/guide/en/elasticsearch/reference/current/indices-create-index.html
# Default settings mytestindex: elasticsearch_index.present
# Extra settings mytestindex2: elasticsearch_index.present: - definition: settings: index: number_of_shards: 10
salt.states.elasticsearch.index_template_absent(name) Ensure that the named index template is absent.
salt.states.elasticsearch.index_template_present(name, definition, check_definition=False) Ensure that the named index template is present.
definition Required dict for creation parameters as per https://www.elastic.co/guide/en/elasticsearch/reference/current/indices-templates.html
check_definition If the template already exists and the definition is up to date
mytestindex2_template: elasticsearch.index_template_present: - definition: template: logstash-* order: 1 settings: number_of_shards: 1
salt.states.elasticsearch.pipeline_absent(name) Ensure that the named pipeline is absent
name   Name of the pipeline to remove
salt.states.elasticsearch.pipeline_present(name, definition) Ensure that the named pipeline is present.
definition Required dict for creation parameters as per https://www.elastic.co/guide/en/elasticsearch/reference/master/pipeline.html
test_pipeline: elasticsearch.pipeline_present: - definition: description: example pipeline processors: - set: field: collector_timestamp_millis value: '{{ '{{' }}_ingest.timestamp{{ '}}' }}'
salt.states.elasticsearch.search_template_absent(name) Ensure that the search template is absent
name   Name of the search template to remove
salt.states.elasticsearch.search_template_present(name, definition) Ensure that the named search template is present.
name   Name of the search template to add
definition Required dict for creation parameters as per http://www.elastic.co/guide/en/elasticsearch/reference/current/search-template.html
test_pipeline: elasticsearch.search_template_present: - definition: inline: size: 10
salt.states.elasticsearch_index State module to manage Elasticsearch indices
Deprecated since version 2017.7.0: Use elasticsearch state instead
salt.states.elasticsearch_index.absent(name) Ensure that the named index is absent.
salt.states.elasticsearch_index.present(name, definition=None) New in version 2015.8.0.
Changed in version 2017.3.0: Marked definition as optional.
Ensure that the named index is present.
salt.states.elasticsearch_index_template State module to manage Elasticsearch index templates
salt.states.elasticsearch_index_template.absent(name) Ensure that the named index template is absent.
salt.states.elasticsearch_index_template.present(name, definition) New in version 2015.8.0.
Changed in version 2017.3.0: Marked definition as required.
Ensure that the named index templat eis present.
mytestindex2_template: elasticsearch_index_template.present: - definition: template: logstash-* order: 1 settings: number_of_shards: 1
salt.states.environ Support for getting and setting the environment variables of the current salt process.
salt.states.environ.setenv(name, value, false_unsets=False, clear_all=False, update_minion=False, permanent=False) Set the salt process environment variables.
name   The environment key to set. Must be a string.
value  Either a string or dict. When string, it will be the value set for the environment key of 'name' above.  When a dict, each key/value pair represents an environment variable to set.
permanent On Windows minions this will set the environment variable in the registry so that it is always added as a environment variable when applications open. If you want to set the variable to HKLM instead of HKCU just pass in "HKLM" for this parameter. On all other minion types this will be ignored. Note: This will only take affect on applications opened after this has been set.
a_string_env: environ.setenv: - name: foo - value: bar - update_minion: True
a_dict_env: environ.setenv: - name: does_not_matter - value: foo: bar baz: quux
salt.states.eselect Management of Gentoo configuration using eselect A state module to manage Gentoo configuration via eselect
salt.states.eselect.set_(name, target, module_parameter=None, action_parameter=None) Verify that the given module is set to the given target
name   The name of the module
target The target to be set for this module
profile: eselect.set: - target: hardened/linux/amd64
salt.states.esxcluster Manage VMware ESXi Clusters.
salt.states.esxcluster.cluster_configured(name, cluster_config) Configures a cluster. Creates a new cluster, if it doesn't exist on the vCenter or reconfigures it if configured differently
Supported proxies: esxdatacenter, esxcluster
name   Name of the state. If the state is run in by an esxdatacenter proxy, it will be the name of the cluster.
cluster_config Configuration applied to the cluster.  Complex datastructure following the ESXClusterConfigSchema.  Valid example is:
drs: default_vm_behavior: fullyAutomated enabled: true vmotion_rate: 3 ha: admission_control _enabled: false default_vm_settings: isolation_response: powerOff restart_priority: medium enabled: true hb_ds_candidate_policy: userSelectedDs host_monitoring: enabled options: - key: das.ignoreinsufficienthbdatastore value: 'true' vm_monitoring: vmMonitoringDisabled vm_swap_placement: vmDirectory vsan: auto_claim_storage: false compression_enabled: true dedup_enabled: true enabled: true
salt.states.esxcluster.licenses_configured(name, licenses=None) Configures licenses on the cluster entity
Checks if each license exists on the server:
• if it doesn't, it creates it
Check if license is assigned to the cluster:
if it's not assigned to the cluster:
• assign it to the cluster if there is space
• error if there's no space
• if it's assigned to the cluster nothing needs to be done
salt.states.esxcluster.vsan_datastore_configured(name, datastore_name) Configures the cluster's VSAN datastore
WARNING: The VSAN datastore is created automatically after the first ESXi host is added to the cluster; the state assumes that the datastore exists and errors if it doesn't.
salt.states.esxdatacenter Salt states to create and manage VMware vSphere datacenters (datacenters).
States datacenter_configured Makes sure a datacenter exists and is correctly configured.
If the state is run by an esxdatacenter minion, the name of the datacenter is retrieved from the proxy details, otherwise the datacenter has the same name as the state.
1. Make sure that a datacenter named target_dc exists on the vCenter, using a esxdatacenter proxy:
Proxy minion configuration (connects passthrough to the vCenter):
proxy: proxytype: esxdatacenter datacenter: target_dc vcenter: vcenter.fake.com mechanism: sspi domain: fake.com principal: host
State configuration:
datacenter_state: esxdatacenter.datacenter_configured
salt.states.esxdatacenter.datacenter_configured(name) Makes sure a datacenter exists.
name:  Datacenter name. Ignored if the proxytype is esxdatacenter.
salt.states.esxi Manage VMware ESXi Hosts.
NOTE: Be aware that some functionality in this state module may depend on the type of license attached to the ESXi host.
About This state module was written to be used in conjunction with Salt's ESXi Proxy Minion. For a tutorial on how to use Salt's ESXi Proxy Minion, please refer to the ESXi Proxy Minion Tutorial for configuration examples, dependency installation instructions, how to run remote execution functions against ESXi hosts via a Salt Proxy Minion, and a larger state example.
salt.states.esxi.coredump_configured(name, enabled, dump_ip, host_vnic='vmk0', dump_port=6500) Ensures a host's core dump configuration.
enabled Sets whether or not ESXi core dump collection should be enabled.  This is a boolean value set to True or False to enable or disable core dumps.
Note that ESXi requires that the core dump must be enabled before any other parameters may be set. This also affects the changes results in the state return dictionary. If enabled is False, we can't obtain any previous settings to compare other state variables, resulting in many old references returning None.
Once enabled is True the changes dictionary comparisons will be more accurate. This is due to the way the system coredemp network configuration command returns data.
dump_ip The IP address of host that will accept the dump.
dump_port TCP port to use for the dump. Defaults to 6500.
salt.states.esxi.diskgroups_configured(name, diskgroups, erase_disks=False) Configures the disk groups to use for vsan.
This function will do the following:
1. Check whether or not all disks in the diskgroup spec exist, and raises and errors if they do not.
2. Create diskgroups with the correct disk configurations if diskgroup (identified by the cache disk canonical name) doesn't exist
3. Adds extra capacity disks to the existing diskgroup
{ 'cache_scsi_addr': 'vmhba1:C0:T0:L0', 'capacity_scsi_addrs': [ 'vmhba2:C0:T0:L0', 'vmhba3:C0:T0:L0', 'vmhba4:C0:T0:L0', ] }
name   Mandatory state name
diskgroups Disk group representation containing scsi disk addresses. Scsi addresses are expected for disks in the diskgroup:
erase_disks Specifies whether to erase all partitions on all disks member of the disk group before the disk group is created. Default value is False.
salt.states.esxi.host_cache_configured(name, enabled, datastore, swap_size='100%', dedicated_backing_disk=False, erase_backing_disk=False) Configures the host cache used for swapping.
It will do the following:
1. Checks if backing disk exists
2. Creates the VMFS datastore if doesn't exist (datastore partition will be created and use the entire disk)
3. Raises an error if dedicated_backing_disk is True and partitions already exist on the backing disk
4. Configures host_cache to use a portion of the datastore for caching (either a specific size or a percentage of the datastore)
Percentage swap size (can't be 100%)
{ 'enabled': true, 'datastore': { 'backing_disk_scsi_addr': 'vmhba0:C0:T0:L0', 'vmfs_version': 5, 'name': 'hostcache' } 'dedicated_backing_disk': false 'swap_size': '98%', }
Fixed sized swap size
{ 'enabled': true, 'datastore': { 'backing_disk_scsi_addr': 'vmhba0:C0:T0:L0', 'vmfs_version': 5, 'name': 'hostcache' } 'dedicated_backing_disk': true 'swap_size': '10GiB', }
name   Mandatory state name.
enabled Specifies whether the host cache is enabled.
datastore Specifies the host cache datastore.
swap_size Specifies the size of the host cache swap. Can be a percentage or a value in GiB. Default value is 100%.
dedicated_backing_disk Specifies whether the backing disk is dedicated to the host cache which means it must have no other partitions. Default is False
erase_backing_disk Specifies whether to erase all partitions on the backing disk before the datastore is created. Default value is False.
salt.states.esxi.ntp_configured(name, service_running, ntp_servers=None, service_policy=None, service_restart=False, update_datetime=False) Ensures a host's NTP server configuration such as setting NTP servers, ensuring the NTP daemon is running or stopped, or restarting the NTP daemon for the ESXi host.
service_running Ensures the running state of the ntp daemon for the host. Boolean value where True indicates that ntpd should be running and False indicates that it should be stopped.
ntp_servers A list of servers that should be added to the ESXi host's NTP configuration.
service_policy The policy to set for the NTP service.
NOTE: When setting the service policy to off or on, you must quote the setting. If you don't, the yaml parser will set the string to a boolean, which will cause trouble checking for stateful changes and will error when trying to set the policy on the ESXi host.
service_restart If set to True, the ntp daemon will be restarted, regardless of its previous running state. Default is False.
update_datetime If set to True, the date/time on the given host will be updated to UTC.  Default setting is False. This option should be used with caution since network delays and execution delays can result in time skews.
configure-host-ntp: esxi.ntp_configured: - service_running: True - ntp_servers: - 192.174.1.100 - 192.174.1.200 - service_policy: 'on' - service_restart: True
salt.states.esxi.password_present(name, password) Ensures the given password is set on the ESXi host. Passwords cannot be obtained from host, so if a password is set in this state, the vsphere.update_host_password function will always run (except when using test=True functionality) and the state's changes dictionary will always be populated.
The username for which the password will change is the same username that is used to authenticate against the ESXi host via the Proxy Minion. For example, if the pillar definition for the proxy username is defined as root, then the username that the password will be updated for via this state is root.
password The new password to change on the host.
salt.states.esxi.ssh_configured(name, service_running, ssh_key=None, ssh_key_file=None, service_policy=None, service_restart=False, certificate_verify=None) Manage the SSH configuration for a host including whether or not SSH is running or the presence of a given SSH key. Note: Only one ssh key can be uploaded for root.  Uploading a second key will replace any existing key.
service_running Ensures whether or not the SSH service should be running on a host. Represented as a boolean value where True indicates that SSH should be running and False indicates that SSH should stopped.
In order to update SSH keys, the SSH service must be running.
ssh_key Public SSH key to added to the authorized_keys file on the ESXi host. You can use ssh_key or ssh_key_file, but not both.
ssh_key_file File containing the public SSH key to be added to the authorized_keys file on the ESXi host. You can use ssh_key_file or ssh_key, but not both.
service_restart If set to True, the SSH service will be restarted, regardless of its previous running state. Default is False.
certificate_verify If set to True, the SSL connection must present a valid certificate.  Default is True.
configure-host-ssh: esxi.ssh_configured: - service_running: True - ssh_key_file: /etc/salt/ssh_keys/my_key.pub - service_policy: 'on' - service_restart: True - certificate_verify: True
salt.states.esxi.syslog_configured(name, syslog_configs, firewall=True, reset_service=True, reset_syslog_config=False, reset_configs=None) Ensures the specified syslog configuration parameters. By default, this state will reset the syslog service after any new or changed parameters are set successfully.
syslog_configs Name of parameter to set (corresponds to the command line switch for esxcli without the double dashes (--))
Valid syslog_config values are logdir, loghost, logdir-unique, default-rotate, default-size, and default-timeout.
Each syslog_config option also needs a configuration value to set.  For example, loghost requires URLs or IP addresses to use for logging. Multiple log servers can be specified by listing them, comma-separated, but without spaces before or after commas
reset_syslog_config Resets the syslog service to its default settings. Defaults to False.  If set to True, default settings defined by the list of syslog configs in reset_configs will be reset before running any other syslog settings.
reset_configs A comma-delimited list of parameters to reset. Only runs if reset_syslog_config is set to True. If reset_syslog_config is set to True, but no syslog configs are listed in reset_configs, then reset_configs will be set to all by default.
See syslog_configs parameter above for a list of valid options.
salt.states.esxi.vmotion_configured(name, enabled, device='vmk0') Configures a host's VMotion properties such as enabling VMotion and setting the device VirtualNic that VMotion will use.
enabled Ensures whether or not VMotion should be enabled on a host as a boolean value where True indicates that VMotion should be enabled and False indicates that VMotion should be disabled.
device The device that uniquely identifies the VirtualNic that will be used for VMotion for the host. Defaults to vmk0.
configure-vmotion: esxi.vmotion_configured: - enabled: True - device: sample-device
salt.states.esxi.vsan_configured(name, enabled, add_disks_to_vsan=False) Configures a host's VSAN properties such as enabling or disabling VSAN, or adding VSAN-eligible disks to the VSAN system for the host.
enabled Ensures whether or not VSAN should be enabled on a host as a boolean value where True indicates that VSAN should be enabled and False indicates that VSAN should be disabled.
add_disks_to_vsan If set to True, any VSAN-eligible disks for the given host will be added to the host's VSAN system. Default is False.
salt.states.esxvm Salt state to create, update VMware ESXi Virtual Machines.
States vm_configured Enforces correct virtual machine configuration. Creates, updates and registers a virtual machine.
This state identifies the action which should be taken for the virtual machine and applies that action via the create, update, register state functions.
Supported proxies: esxvm
1. Get the virtual machine my_vm status with an esxvm proxy:
Proxy minion configuration for esxvm proxy:
proxy: proxytype: esxvm datacenter: my_dc vcenter: vcenter.fake.com mechanism: sspi domain: fake.com principal: host
myvm_state: esxvm.vm_configured: - vm_name: my_vm - cpu: {{ {'count': 4, 'cores_per_socket': 2} }} - memory: {{ {'size': 16384, 'unit': 'MB'} }} - image: rhel7_64Guest - version: vmx-12 - interfaces: {{ [{ 'adapter': 'Network adapter 1', 'name': 'my_pg1', 'switch_type': 'distributed', 'adapter_type': 'vmxnet3', 'mac': '00:50:56:00:01:02, 'connectable': { 'start_connected': true, 'allow_guest_control': true, 'connected': true}}, { 'adapter': 'Network adapter 2', 'name': 'my_pg2', 'switch_type': 'distributed', 'adapter_type': 'vmxnet3', 'mac': '00:50:56:00:01:03', 'connectable': { 'start_connected': true, 'allow_guest_control': true, 'connected': true}} ] }} - disks: {{ [{ 'adapter': 'Hard disk 1', 'unit': 'MB', 'size': 51200, 'filename': 'my_vm/sda.vmdk', 'datastore': 'my_datastore', 'address': '0:0', 'thin_provision': true, 'eagerly_scrub': false, 'controller': 'SCSI controller 0'}, { 'adapter': 'Hard disk 2', 'unit': 'MB', 'size': 10240, 'filename': 'my_vm/sdb.vmdk', 'datastore': 'my_datastore', 'address': '0:1', 'thin_provision': true, 'eagerly_scrub': false, 'controller': 'SCSI controller 0'} ] }} - scsi_devices: {{ [{ 'adapter': 'SCSI controller 0', 'type': 'paravirtual', 'bus_sharing': 'no_sharing', 'bus_number': 0} ] }} - serial_ports: {{ [{ 'adapter': 'Serial port 1', 'type': 'network', 'yield': false, 'backing': { 'uri': 'my_uri', 'direction': 'server', 'filename': 'my_file'}, 'connectable': { 'start_connected': true, 'allow_guest_control': true, 'connected': true}} ] }} - datacenter: {{ 'my_dc' }} - datastore: 'my_datastore' - placement: {{ {'cluster': 'my_cluster'} }} - cd_dvd_drives: {{ [] }} - advanced_configs: {{ {'my_param': '1'} }} - template: false - tools: false - power_on: false - deploy: false
vm_updated Updates a virtual machine to a given configuration.
vm_created Creates a virtual machine with a given configuration.
vm_registered Registers a virtual machine with its configuration file path.
Dependencies pyVmomi PyVmomi can be installed via pip:
NOTE: Version 6.0 of pyVmomi has some problems with SSL error handling on certain versions of Python. If using version 6.0 of pyVmomi, Python 2.6, Python 2.7.9, or newer must be present. This is due to an upstream dependency in pyVmomi 6.0 that is not supported in Python versions 2.7 to 2.7.8. If the version of Python is not in the supported range, you will need to install an earlier version of pyVmomi.  See Issue #29537 for more information.
pip install pyVmomi==6.0.0.2016.4
The 5.5.0.2014.1.1 is a known stable version that this original ESXi State Module was developed against. To be able to connect through SSPI you must use pyvmomi 6.0.0.2016.4 or above. The ESXVM State Module was tested with this version.
About This state module was written to be used in conjunction with Salt's ESXi Proxy Minion For a tutorial on how to use Salt's ESXi Proxy Minion, please refer to the ESXi Proxy Minion Tutorial for configuration examples, dependency installation instructions, how to run remote execution functions against ESXi hosts via a Salt Proxy Minion, and a larger state example.
salt.states.esxvm.vm_cloned(name) Clones a virtual machine from a template virtual machine if it doesn't exist and a template is defined.
salt.states.esxvm.vm_configured(name, vm_name, cpu, memory, image, version, interfaces, disks, scsi_devices, serial_ports, datacenter, datastore, placement, cd_dvd_drives=None, sata_controllers=None, advanced_configs=None, template=None, tools=True, power_on=False, deploy=False) Selects the correct operation to be executed on a virtual machine, non existing machines will be created, existing ones will be updated if the config differs.
salt.states.esxvm.vm_created(name, vm_name, cpu, memory, image, version, interfaces, disks, scsi_devices, serial_ports, datacenter, datastore, placement, ide_controllers=None, sata_controllers=None, cd_dvd_drives=None, advanced_configs=None, power_on=False) Creates a virtual machine with the given properties if it doesn't exist.
salt.states.esxvm.vm_registered(vm_name, datacenter, placement, vm_file, power_on=False) Registers a virtual machine if the machine files are available on the main datastore.
salt.states.esxvm.vm_updated(name, vm_name, cpu, memory, image, version, interfaces, disks, scsi_devices, serial_ports, datacenter, datastore, cd_dvd_drives=None, sata_controllers=None, advanced_configs=None, power_on=False) Updates a virtual machine configuration if there is a difference between the given and deployed configuration.
salt.states.etcd_mod Manage etcd Keys New in version 2015.8.0.
This state module supports setting and removing keys from etcd.
Etcd profile configuration can be overridden using following arguments: host, port, username, password, ca, client_key and client_cert.
my-value: etcd.set: - name: /path/to/key - value: value - host: 127.0.0.1 - port: 2379 - username: user - password: pass
Available Functions • set
This will set a value to a key in etcd. Changes will be returned if the key has been created or the value of the key has been updated. This means you can watch these states for changes.
/foo/bar/baz: etcd.set: - value: foo - profile: my_etcd_config
• wait_set
Performs the same functionality as set but only if a watch requisite is True.
/some/file.txt: file.managed: - source: salt://file.txt
/foo/bar/baz: etcd.wait_set: - value: foo - profile: my_etcd_config - watch: - file: /some/file.txt
This will delete a key from etcd. If the key exists then changes will be returned and thus you can watch for changes on the state, if the key does not exist then no changes will occur.
/foo/bar/baz: etcd.rm: - profile: my_etcd_config
• wait_rm
Performs the same functionality as rm but only if a watch requisite is True.
/foo/bar/baz: etcd.wait_rm: - profile: my_etcd_config - watch: - file: /some/file.txt
salt.states.etcd_mod.directory(name, profile=None, **kwargs) Create a directory in etcd.
name   The etcd directory name, for example: /foo/bar/baz.
profile Optional, defaults to None. Sets the etcd profile to use which has been defined in the Salt Master config.
salt.states.etcd_mod.mod_watch(name, **kwargs) The etcd watcher, called to invoke the watch command.  When called, execute a etcd function based on a watch call requisite.
salt.states.etcd_mod.rm(name, recurse=False, profile=None, **kwargs) Deletes a key from etcd
name   The etcd key name to remove, for example /foo/bar/baz.
recurse Optional, defaults to False. If True performs a recursive delete.
salt.states.etcd_mod.set_(name, value, profile=None, **kwargs) Set a key in etcd
name   The etcd key name, for example: /foo/bar/baz.
value  The value the key should contain.
salt.states.etcd_mod.wait_rm(name, recurse=False, profile=None, **kwargs) Deletes a key from etcd only if the watch statement calls it. This function is also aliased as wait_rm.
recurse Optional, defaults to False. If True performs a recursive delete, see: https://python-etcd.readthedocs.io/en/latest/#delete-a-key.
salt.states.etcd_mod.wait_set(name, value, profile=None, **kwargs) Set a key in etcd only if the watch statement calls it. This function is also aliased as wait_set.
profile The etcd profile to use that has been configured on the Salt Master, this is optional and defaults to None.
salt.states.ethtool Configuration of network device
eth0: ethtool.coalesce: - name: eth0 - rx_usecs: 24 - tx_usecs: 48
eth0: ethtool.ring: - name: eth0 - rx: 1024 - tx: 1024
eth0: ethtool.offload: - name: eth0 - tcp_segmentation_offload: on
salt.states.ethtool.coalesce(name, **kwargs) Manage coalescing settings of network device
name   Interface name to apply coalescing settings
eth0: ethtool.coalesce: - name: eth0 - adaptive_rx: on - adaptive_tx: on - rx_usecs: 24 - rx_frame: 0 - rx_usecs_irq: 0 - rx_frames_irq: 0 - tx_usecs: 48 - tx_frames: 0 - tx_usecs_irq: 0 - tx_frames_irq: 0 - stats_block_usecs: 0 - pkt_rate_low: 0 - rx_usecs_low: 0 - rx_frames_low: 0 - tx_usecs_low: 0 - tx_frames_low: 0 - pkt_rate_high: 0 - rx_usecs_high: 0 - rx_frames_high: 0 - tx_usecs_high: 0 - tx_frames_high: 0 - sample_interval: 0
salt.states.ethtool.offload(name, **kwargs) Manage protocol offload and other features of network device
salt.states.ethtool.ring(name, **kwargs) Manage rx/tx ring parameters of network device
Use 'max' word to set with factory maximum
name   Interface name to apply ring parameters
eth0: ethtool.ring: - name: eth0 - rx: 1024 - rx_mini: 0 - rx_jumbo: 0 - tx: max
salt.states.event Send events through Salt's event system during state runs
salt.states.event.fire_master(name, data=None, preload=None, with_env=False, with_grains=False, with_pillar=False, show_changed=True, **kwargs) This function is an alias of send. Send an event to the Salt Master
Accepts the same arguments as the event.send execution module of the same name, with the additional argument:
param show_changed If True, state will show as changed with the data argument as the change value. If False, shows as unchanged.
# ...snip bunch of states above
mycompany/mystaterun/status/update: event.send: - data: status: "Half-way through the state run!"
# ...snip bunch of states below
salt.states.event.mod_watch(name, data=None, preload=None, with_env=False, with_grains=False, with_pillar=False, show_changed=True, **kwargs) This function is an alias of send. Send an event to the Salt Master
salt.states.event.send(name, data=None, preload=None, with_env=False, with_grains=False, with_pillar=False, show_changed=True, **kwargs) Send an event to the Salt Master
Parameters show_changed -- If True, state will show as changed with the data argument as the change value. If False, shows as unchanged.
salt.states.event.wait(name, sfun=None, data=None) Fire an event on the Salt master event bus if called from a watch statement
# Stand up a new web server. apache: pkg: - installed - name: httpd service: - running - enable: True - name: httpd
# Notify the load balancer to update the pool once Apache is running. refresh_pool: event: - wait - name: mycompany/loadbalancer/pool/update - data: new_web_server_ip: {{ grains['ipv4'] | first() }} - watch: - pkg: apache
salt.states.file Operations on regular files, special files, directories, and symlinks Salt States can aggressively manipulate files on a system. There are a number of ways in which files can be managed.
Regular files can be enforced with the file.managed state. This state downloads files from the salt master and places them on the target system. Managed files can be rendered as a jinja, mako, or wempy template, adding a dynamic component to file management.  An example of file.managed which makes use of the jinja templating system would look like this:
/etc/http/conf/http.conf: file.managed: - source: salt://apache/http.conf - user: root - group: root - mode: 644 - attrs: ai - template: jinja - defaults: custom_var: "default value" other_var: 123 {% if grains['os'] == 'Ubuntu' %} - context: custom_var: "override" {% endif %}
It is also possible to use the py renderer as a templating option. The template would be a Python script which would need to contain a function called run(), which returns a string. All arguments to the state will be made available to the Python script as globals. The returned string will be the contents of the managed file. For example:
def run(): lines = ['foo', 'bar', 'baz'] lines.extend([source, name, user, context])  # Arguments as globals return '\n\n'.join(lines)
NOTE: The defaults and context arguments require extra indentation (four spaces instead of the normal two) in order to create a nested dictionary.  More information.
If using a template, any user-defined template variables in the file defined in source must be passed in using the defaults and/or context arguments. The general best practice is to place default values in defaults, with conditional overrides going into context, as seen above.
The template will receive a variable custom_var, which would be accessed in the template using {{ custom_var }}. If the operating system is Ubuntu, the value of the variable custom_var would be override, otherwise it is the default default value
The source parameter can be specified as a list. If this is done, then the first file to be matched will be the one that is used. This allows you to have a default file on which to fall back if the desired file does not exist on the salt fileserver. Here's an example:
/etc/foo.conf: file.managed: - source: - salt://foo.conf.{{ grains['fqdn'] }} - salt://foo.conf.fallback - user: foo - group: users - mode: 644 - attrs: i - backup: minion
NOTE: Salt supports backing up managed files via the backup option. For more details on this functionality please review the backup_mode documentation.
The source parameter can also specify a file in another Salt environment. In this example foo.conf in the dev environment will be used instead.
/etc/foo.conf: file.managed: - source: - 'salt://foo.conf?saltenv=dev' - user: foo - group: users - mode: '0644' - attrs: i
WARNING: When using a mode that includes a leading zero you must wrap the value in single quotes. If the value is not wrapped in quotes it will be read by YAML as an integer and evaluated as an octal.
The names parameter, which is part of the state compiler, can be used to expand the contents of a single state declaration into multiple, single state declarations. Each item in the names list receives its own individual state name and is converted into its own low-data structure. This is a convenient way to manage several files with similar attributes.
salt_master_conf: file.managed: - user: root - group: root - mode: '0644' - names: - /etc/salt/master.d/master.conf: - source: salt://saltmaster/master.conf - /etc/salt/minion.d/minion-99.conf: - source: salt://saltmaster/minion.conf
NOTE: There is more documentation about this feature in the Names declaration section of the Highstate docs.
Special files can be managed via the mknod function. This function will create and enforce the permissions on a special file. The function supports the creation of character devices, block devices, and FIFO pipes. The function will create the directory structure up to the special file if it is needed on the minion. The function will not overwrite or operate on (change major/minor numbers) existing special files with the exception of user, group, and permissions. In most cases the creation of some special files require root permissions on the minion. This would require that the minion to be run as the root user. Here is an example of a character device:
/var/named/chroot/dev/random: file.mknod: - ntype: c - major: 1 - minor: 8 - user: named - group: named - mode: 660
Here is an example of a block device:
/var/named/chroot/dev/loop0: file.mknod: - ntype: b - major: 7 - minor: 0 - user: named - group: named - mode: 660
Here is an example of a fifo pipe:
/var/named/chroot/var/log/logfifo: file.mknod: - ntype: p - user: named - group: named - mode: 660
Directories can be managed via the directory function. This function can create and enforce the permissions on a directory. A directory statement will look like this:
/srv/stuff/substuf: file.directory: - user: fred - group: users - mode: 755 - makedirs: True
If you need to enforce user and/or group ownership or permissions recursively on the directory's contents, you can do so by adding a recurse directive:
/srv/stuff/substuf: file.directory: - user: fred - group: users - mode: 755 - makedirs: True - recurse: - user - group - mode
As a default, mode will resolve to dir_mode and file_mode, to specify both directory and file permissions, use this form:
/srv/stuff/substuf: file.directory: - user: fred - group: users - file_mode: 744 - dir_mode: 755 - makedirs: True - recurse: - user - group - mode
Symlinks can be easily created; the symlink function is very simple and only takes a few arguments:
/etc/grub.conf: file.symlink: - target: /boot/grub/grub.conf
Recursive directory management can also be set via the recurse function. Recursive directory management allows for a directory on the salt master to be recursively copied down to the minion. This is a great tool for deploying large code and configuration systems. A state using recurse would look something like this:
/opt/code/flask: file.recurse: - source: salt://code/flask - include_empty: True
A more complex recurse example:
{% set site_user = 'testuser' %} {% set site_name = 'test_site' %} {% set project_name = 'test_proj' %} {% set sites_dir = 'test_dir' %}
django-project: file.recurse: - name: {{ sites_dir }}/{{ site_name }}/{{ project_name }} - user: {{ site_user }} - dir_mode: 2775 - file_mode: '0644' - template: jinja - source: salt://project/templates_dir - include_empty: True
Retention scheduling can be applied to manage contents of backup directories.  For example:
/var/backups/example_directory: file.retention_schedule: - strptime_format: example_name_%Y%m%dT%H%M%S.tar.bz2 - retain: most_recent: 5 first_of_hour: 4 first_of_day: 14 first_of_week: 6 first_of_month: 6 first_of_year: all
salt.states.file.absent(name, **kwargs) Make sure that the named file or directory is absent. If it exists, it will be deleted. This will work to reverse any of the functions in the file state module. If a directory is supplied, it will be recursively deleted.
name   The path which should be deleted
salt.states.file.accumulated(name, filename, text, **kwargs) Prepare accumulator which can be used in template in file.managed state.  Accumulator dictionary becomes available in template. It can also be used in file.blockreplace.
name   Accumulator name
filename Filename which would receive this accumulator (see file.managed state documentation about name)
text   String or list for adding in accumulator
require_in / watch_in One of them required for sure we fill up accumulator before we manage the file. Probably the same as filename
Given the following:
animals_doing_things: file.accumulated: - filename: /tmp/animal_file.txt - text: ' jumps over the lazy dog.' - require_in: - file: animal_file
animal_file: file.managed: - name: /tmp/animal_file.txt - source: salt://animal_file.txt - template: jinja
One might write a template for animal_file.txt like the following:
The quick brown fox{% for animal in accumulator['animals_doing_things'] %}{{ animal }}{% endfor %}
Collectively, the above states and template file will produce:
Multiple accumulators can be "chained" together.
NOTE: The 'accumulator' data structure is a Python dictionary.  Do not expect any loop over the keys in a deterministic order!
salt.states.file.append(name, text=None, makedirs=False, source=None, source_hash=None, template='jinja', sources=None, source_hashes=None, defaults=None, context=None, ignore_whitespace=True) Ensure that some text appears at the end of a file.
The text will not be appended if it already exists in the file.  A single string of text or a list of strings may be appended.
name   The location of the file to append to.
text   The text to be appended, which can be a single string or a list of strings.
makedirs If the file is located in a path without a parent directory, then the state will fail. If makedirs is set to True, then the parent directories will be created to facilitate the creation of the named file. Defaults to False.
source A single source file to append. This source file can be hosted on either the salt master server, or on an HTTP or FTP server. Both HTTPS and HTTP are supported as well as downloading directly from Amazon S3 compatible URLs with both pre-configured and automatic IAM credentials (see s3.get state documentation). File retrieval from Openstack Swift object storage is supported via swift://container/object_path URLs (see swift.get documentation).
For files hosted on the salt file server, if the file is located on the master in the directory named spam, and is called eggs, the source string is salt://spam/eggs.
If the file is hosted on an HTTP or FTP server, the source_hash argument is also required.
source_hash
This can be one of the following:
1. a source hash string
2. the URI of a file that contains source hash strings
The function accepts the first encountered long unbroken alphanumeric string of correct length as a valid hash, in order from most secure to least secure:
Type    Length ======  ====== sha512     128 sha384      96 sha256      64 sha224      56 sha1        40 md5         32
See the source_hash parameter description for file.managed function for more details and examples.
template The named templating engine will be used to render the appended-to file.  Defaults to jinja. The following templates are supported:
sources A list of source files to append. If the files are hosted on an HTTP or FTP server, the source_hashes argument is also required.
source_hashes A list of source_hashes corresponding to the sources list specified in the sources argument.
ignore_whitespace New in version 2015.8.4.
Spaces and Tabs in text are ignored by default, when searching for the appending content, one space or multiple tabs are the same for salt.  Set this option to False if you want to change this behavior.
Multi-line example:
/etc/motd: file.append: - text: | Thou hadst better eat salt with the Philosophers of Greece, than sugar with the Courtiers of Italy. - Benjamin Franklin
Multiple lines of text:
/etc/motd: file.append: - text: - Trust no one unless you have eaten much salt with him. - "Salt is born of the purest of parents: the sun and the sea."