neulab/tldr huggingface dataset:
If one would need execute a command on the device but connecting using different parameters (due to various causes, e.g., unable to authenticate the user specified in the Pillar as the authentication system - say TACACS+ is not available, or the DNS resolver is currently down and would like to temporarily use the IP address instead, etc.), it implies updating the Pillar data and restarting the Proxy Minion process restart.  In particular cases like that, you can pass the force_reconnect=True keyword argument, together with the alternative connection details, to enforce the command to be executed over a separate connection.
For example, if the usual command is salt '*' net.arp, you can use the following to connect using a different username instead: salt '*' net.arp username=my-alt-usr force_reconnect=True.
salt.proxy.napalm.alive(opts) Return the connection status with the remote device.
salt.proxy.napalm.call(method, *args, **kwargs) Calls a specific method from the network driver instance.  Please check the readthedocs page for the updated list of getters.
• method -- specifies the name of the method to be called
• params -- contains the mapping between the name and the values of the parameters needed to call the method
Returns A dictionary with three keys:
• result (True/False): if the operation succeeded
• out (object): returns the object as-is from the call
• comment (string): provides more details in case the call failed
• traceback (string): complete traceback in case of exception. Please submit an issue including this traceback on the correct driver repo and make sure to read the FAQ
__proxy__['napalm.call']('cli' **{ 'commands': [ 'show version', 'show chassis fan' ] })
salt.proxy.napalm.fns() Method called by NAPALM grains module.
salt.proxy.napalm.get_device() Returns the network device object.
salt.proxy.napalm.get_grains() Retrieve facts from the network device.
salt.proxy.napalm.grains_refresh() Refresh the grains.
salt.proxy.napalm.init(opts) Opens the connection with the network device.
salt.proxy.napalm.initialized() Connection finished initializing?
salt.proxy.napalm.ping() Connection open successfully?
salt.proxy.napalm.shutdown(opts) Closes connection with the device.
salt.proxy.netmiko_px Netmiko New in version 2019.2.0.
Proxy module for managing network devices via Netmiko.
Pillar The netmiko proxy configuration requires the following parameters in order to connect to the network device:
• always_alive - In certain less dynamic environments, maintaining the remote connection permanently open with the network device is not always beneficial. In that case, the user can select to initialize the connection only when needed, by setting this option to False. By default this option is set to True (maintains the connection with the remote network device)
• multiprocessing - Overrides the multiprocessing option, per proxy minion, as the Netmiko communication channel is mainly SSH (default: False)
• connection_timeout - The number of seconds to attempt to connect to the device in seconds.  (default: 300)
Proxy Pillar Example proxy: proxytype: netmiko device_type: juniper_junos host: router1.example.com username: example password: example
proxy: proxytype: netmiko device_type: cisco_ios ip: 1.2.3.4 username: test use_keys: true secret: w3@k
salt.proxy.netmiko_px.alive(opts) Return the connection status with the network device.
salt.proxy.netmiko_px.args() Return the Netmiko device args.
salt.proxy.netmiko_px.call(method, *args, **kwargs) Calls an arbitrary netmiko method.
salt.proxy.netmiko_px.conn() Return the connection object.
salt.proxy.netmiko_px.connection(connection_timeout=300)
salt.proxy.netmiko_px.init(opts) Open the connection to the network device managed through netmiko.
salt.proxy.netmiko_px.initialized() Connection finished initializing?
salt.proxy.netmiko_px.make_con(connection_timeout=300)
salt.proxy.netmiko_px.ping() Connection open successfully?
salt.proxy.netmiko_px.shutdown(opts) Closes connection with the device.
salt.proxy.nxos Proxy Minion for Cisco NX-OS Switches
The Cisco NX-OS Proxy Minion is supported on NX-OS devices for the following connection types: 1) Connection Type SSH 2) Connection Type NX-API (If Supported By The Device and Image Version).
SSH uses the built in SSHConnection module in salt.utils.vt_helper
To configure the proxy minion for ssh:
proxy: proxytype: nxos connection: ssh host: 192.168.187.100 username: admin password: admin prompt_name: nxos-switch ssh_args: '-o PubkeyAuthentication=no' key_accept: True
To configure the proxy minion for nxapi:
proxy: proxytype: nxos connection: nxapi host: 192.168.187.100 username: admin password: admin transport: http port: 80 verify: False save_config: False
proxytype: (REQUIRED) Use this proxy minion nxos
connection: (REQUIRED) connection transport type.  Choices: ssh, nxapi Default: ssh
host:  (REQUIRED) login ip address or dns hostname.
username: (REQUIRED) login username.
password: (REQUIRED) login password.
Connection SSH Args:
prompt_name: (REQUIRED when connection is ssh) (REQUIRED, this or prompt_regex below, but not both) The name in the prompt on the switch.  Recommended to use your device's hostname.
prompt_regex: (REQUIRED when connection is ssh) (REQUIRED, this or prompt_name above, but not both) A regular expression that matches the prompt on the switch and any other possible prompt at which you need the proxy minion to continue sending input. This feature was specifically developed for situations where the switch may ask for confirmation.  prompt_name above would not match these, and so the session would timeout.
nxos-switch#.*|\(y\/n\)\?.*
This should match
nxos-switch#
Flash complete.  Reboot this switch (y/n)? [n]
If neither prompt_name nor prompt_regex is specified the prompt will be defaulted to
.+#$
which should match any number of characters followed by a # at the end of the line.  This may be far too liberal for most installations.
ssh_args: Extra optional arguments used for connecting to switch.
key_accept: Whether or not to accept the host key of the switch on initial login.  Default: False
Connection NXAPI Args:
transport: (REQUIRED) when connection is nxapi.  Choices: http, https Default: https
port:  (REQUIRED) when connection is nxapi.  Default: 80
verify: (REQUIRED) when connection is nxapi.  Either a boolean, in which case it controls whether we verify the NX-API TLS certificate, or a string, in which case it must be a path to a CA bundle to use.  Default: True
The functions from the proxy minion can be run from the salt commandline using the salt.modules.nxos execution module.
salt.proxy.nxos.grains() Helper function for nxos execution module functions that need to retrieve nxos grains using the proxy minion.
salt.proxy.nxos.grains_refresh() Helper function for nxos execution module functions that need to refresh nxos grains using the proxy minion.
salt.proxy.nxos.init(opts=None) Required.  Initialize device connection using ssh or nxapi connection type.
salt.proxy.nxos.initialized() Since grains are loaded in many different places and some of those places occur before the proxy can be initialized, return whether the init() function has been called.
salt.proxy.nxos.ping() Helper function for nxos execution module functions that need to ping the nxos device using the proxy minion.
salt.proxy.nxos.proxy_config(commands, save_config=None) Helper function for nxos execution module functions that need to configure an nxos device using the proxy minion.
salt.proxy.nxos.sendline(commands, method='cli_show_ascii', **kwargs) Helper function for nxos execution module functions that need to send commands to an nxos device using the proxy minion.
salt.proxy.nxos.shutdown() Not supported.  Only used as a place holder to satisfy shutdown function requirement.
salt.proxy.nxos_api Proxy Minion to manage Cisco Nexus Switches (NX-OS) over the NX-API
Proxy module for managing Cisco Nexus switches via the NX-API.
Usage NOTE: To be able to use this module you need to enable to NX-API on your switch, by executing feature nxapi in configuration mode.
Pillar The nxos_api proxy configuration requires the following parameters in order to connect to the network switch:
Proxy Pillar Example proxy: proxytype: nxos_api host: switch1.example.com username: example password: example
salt.proxy.nxos_api.get_conn_args() Returns the connection arguments of the Proxy Minion.
salt.proxy.nxos_api.init(opts) Open the connection to the Nexsu switch over the NX-API.
As the communication is HTTP based, there is no connection to maintain, however, in order to test the connectivity and make sure we are able to bring up this Minion, we are executing a very simple command (show clock) which doesn't come with much overhead and it's sufficient to confirm we are indeed able to connect to the NX-API endpoint as configured.
salt.proxy.nxos_api.initialized() Connection finished initializing?
salt.proxy.nxos_api.ping() Connection open successfully?
salt.proxy.nxos_api.rpc(commands, method='cli', **kwargs) Executes an RPC request over the NX-API.
salt.proxy.nxos_api.shutdown(opts) Closes connection with the device.
salt.proxy.panos Proxy Minion interface module for managing Palo Alto firewall devices New in version 2018.3.0.
This proxy minion enables Palo Alto firewalls (hereafter referred to as simply 'panos') to be treated individually like a Salt Minion.
The panos proxy leverages the XML API functionality on the Palo Alto firewall. The Salt proxy must have access to the Palo Alto firewall on HTTPS (tcp/443).
Pillar Proxy minions get their configuration from Salt's Pillar. Every proxy must have a stanza in Pillar and a reference in the Pillar top-file that matches the ID. There are four connection options available for the panos proxy module.
• Direct Device (Password)
• Direct Device (API Key)
• Panorama Pass-Through (Password)
• Panorama Pass-Through (API Key)
Direct Device (Password) The direct device configuration configures the proxy to connect directly to the device with username and password.
proxy: proxytype: panos host: <ip or dns name of panos host> username: <panos username> password: <panos password> verify_ssl: True
proxytype The proxytype key and value pair is critical, as it tells Salt which interface to load from the proxy directory in Salt's install hierarchy, or from /srv/salt/_proxy on the Salt Master (if you have created your own proxy module, for example). To use this panos Proxy Module, set this to panos.
host The location, or ip/dns, of the panos host. Required.
username The username used to login to the panos host. Required.
password The password used to login to the panos host. Required.
Direct Device (API Key) Palo Alto devices allow for access to the XML API with a generated 'API key'_ instead of username and password.
proxy: proxytype: panos host: <ip or dns name of panos host> apikey: <panos generated api key>
apikey The generated XML API key for the panos host. Required.
Panorama Pass-Through (Password) The Panorama pass-through method sends all connections through the Panorama management system. It passes the connections to the appropriate device using the serial number of the Palo Alto firewall.
This option will reduce the number of connections that must be present for the proxy server. It will only require a connection to the Panorama server.
The username and password will be for authentication to the Panorama server, not the panos device.
proxy: proxytype: panos serial: <serial number of panos host> host: <ip or dns name of the panorama server> username: <panorama server username> password: <panorama server password>
serial The serial number of the panos host. Required.
host The location, or ip/dns, of the Panorama server. Required.
username The username used to login to the Panorama server. Required.
password The password used to login to the Panorama server. Required.
Panorama Pass-Through (API Key) The Panorama server can also utilize a generated 'API key'_ for authentication.
proxy: proxytype: panos serial: <serial number of panos host> host: <ip or dns name of the panorama server> apikey: <panos generated api key>
apikey The generated XML API key for the Panorama server. Required.
salt.proxy.panos.call(payload=None) This function captures the query string and sends it to the Palo Alto device.
salt.proxy.panos.grains() Get the grains from the proxied device
salt.proxy.panos.grains_refresh() Refresh the grains from the proxied device
salt.proxy.panos.init(opts) This function gets called when the proxy starts up. For panos devices, a determination is made on the connection type and the appropriate connection details that must be cached.
salt.proxy.panos.initialized() Since grains are loaded in many different places and some of those places occur before the proxy can be initialized, return whether our init() function has been called
salt.proxy.panos.is_required_version(required_version='0.0.0') Because different versions of Palo Alto support different command sets, this function will return true if the current version of Palo Alto supports the required command.
salt.proxy.panos.ping() Returns true if the device is reachable, else false.
salt.proxy.panos.shutdown() Shutdown the connection to the proxy device. For this proxy, shutdown is a no-op.
salt.proxy.philips_hue Philips HUE lamps module for proxy.
First create a new user on the Hue bridge by following the Meet hue instructions.
proxy: proxytype: philips_hue host: [hostname or ip] user: [username]
class salt.proxy.philips_hue.Const Constants for the lamp operations.
COLOR_BLUE = {'hue': 46920, 'sat': 254}
COLOR_DAYLIGHT = {'xy': [0.3806, 0.3576]}
COLOR_GREEN = {'hue': 25500, 'sat': 254}
COLOR_ORANGE = {'hue': 12000, 'sat': 254}
COLOR_PINK = {'xy': [0.3688, 0.2095]}
COLOR_PURPLE = {'xy': [0.3787, 0.1724]}
COLOR_RED = {'hue': 0, 'sat': 254}
COLOR_WHITE = {'xy': [0.3227, 0.329]}
COLOR_YELLOW = {'xy': [0.4432, 0.5154]}
LAMP_OFF = {'on': False, 'transitiontime': 0}
LAMP_ON = {'on': True, 'transitiontime': 0}
salt.proxy.philips_hue.call_alert(*args, **kwargs) Lamp alert
• id: Specifies a device ID. Can be a comma-separated values. All, if omitted.
• on: Turns on or off an alert. Default is True.
salt '*' hue.alert salt '*' hue.alert id=1 salt '*' hue.alert id=1,2,3 on=false
salt.proxy.philips_hue.call_blink(*args, **kwargs) Blink a lamp. If lamp is ON, then blink ON-OFF-ON, otherwise OFF-ON-OFF.
• pause: Time in seconds. Can be less than 1, i.e. 0.7, 0.5 sec.
salt '*' hue.blink id=1 salt '*' hue.blink id=1,2,3
salt.proxy.philips_hue.call_brightness(*args, **kwargs) Set an effect to the lamp.
• value: 0~255 brightness of the lamp.
• transition: Transition 0~200. Default 0.
salt '*' hue.brightness value=100 salt '*' hue.brightness id=1 value=150 salt '*' hue.brightness id=1,2,3 value=255
salt.proxy.philips_hue.call_color(*args, **kwargs) Set a color to the lamp.
color: Fixed color. Values are: red, green, blue, orange, pink, white, yellow, daylight, purple. Default white.
• transition: Transition 0~200.
Advanced:
gamut: XY coordinates. Use gamut according to the Philips HUE devices documentation. More: http://www.developers.meethue.com/documentation/hue-xy-values
salt '*' hue.color salt '*' hue.color id=1 salt '*' hue.color id=1,2,3 oolor=red transition=30 salt '*' hue.color id=1 gamut=0.3,0.5
salt.proxy.philips_hue.call_effect(*args, **kwargs) Set an effect to the lamp.
• type: Type of the effect. Possible values are "none" or "colorloop". Default "none".
salt '*' hue.effect salt '*' hue.effect id=1 salt '*' hue.effect id=1,2,3 type=colorloop
salt.proxy.philips_hue.call_lights(*args, **kwargs) Get info about all available lamps.
salt '*' hue.lights salt '*' hue.lights id=1 salt '*' hue.lights id=1,2,3
salt.proxy.philips_hue.call_ping(*args, **kwargs) Ping the lamps by issuing a short inversion blink to all available devices.
salt '*' hue.ping
salt.proxy.philips_hue.call_rename(*args, **kwargs) Rename a device.
• id: Specifies a device ID. Only one device at a time.
• title: Title of the device.
salt '*' hue.rename id=1 title='WC for cats'
salt.proxy.philips_hue.call_status(*args, **kwargs) Return the status of the lamps.
salt '*' hue.status salt '*' hue.status id=1 salt '*' hue.status id=1,2,3
salt.proxy.philips_hue.call_switch(*args, **kwargs) Switch lamp ON/OFF.
If no particular state is passed, then lamp will be switched to the opposite state.
• on: True or False. Inverted current, if omitted
salt '*' hue.switch salt '*' hue.switch id=1 salt '*' hue.switch id=1,2,3 on=True
salt.proxy.philips_hue.call_temperature(*args, **kwargs) Set the mired color temperature. More: http://en.wikipedia.org/wiki/Mired
• value: 150~500.
salt '*' hue.temperature value=150 salt '*' hue.temperature value=150 id=1 salt '*' hue.temperature value=150 id=1,2,3
salt.proxy.philips_hue.init(cnf) Initialize the module.
salt.proxy.philips_hue.ping(*args, **kw) Ping the lamps.
salt.proxy.philips_hue.shutdown(opts, *args, **kw) Shuts down the service.
salt.proxy.rest_sample This is a simple proxy-minion designed to connect to and communicate with the bottle-based web service contained in https://github.com/saltstack/salt-contrib/tree/master/proxyminion_rest_example
salt.proxy.rest_sample.alive(opts)
salt.proxy.rest_sample.fix_outage()
salt.proxy.rest_sample.fns()
salt.proxy.rest_sample.grains() Get the grains from the proxied device
salt.proxy.rest_sample.grains_refresh() Refresh the grains from the proxied device
salt.proxy.rest_sample.id(opts) Return a unique ID for this proxy minion.  This ID MUST NOT CHANGE.  If it changes while the proxy is running the salt-master will get really confused and may stop talking to this minion
salt.proxy.rest_sample.init(opts)
salt.proxy.rest_sample.initialized() Since grains are loaded in many different places and some of those places occur before the proxy can be initialized, return whether our init() function has been called
salt.proxy.rest_sample.package_install(name, **kwargs) Install a "package" on the REST server
salt.proxy.rest_sample.package_list() List "packages" installed on the REST server
salt.proxy.rest_sample.package_remove(name) Remove a "package" on the REST server
salt.proxy.rest_sample.package_status(name) Check the installation status of a package on the REST server
salt.proxy.rest_sample.ping() Is the REST server up?
salt.proxy.rest_sample.service_list() List "services" on the REST server
salt.proxy.rest_sample.service_restart(name) Restart a "service" on the REST server
salt.proxy.rest_sample.service_start(name) Start a "service" on the REST server
salt.proxy.rest_sample.service_status(name) Check if a service is running on the REST server
salt.proxy.rest_sample.service_stop(name) Stop a "service" on the REST server
salt.proxy.rest_sample.shutdown(opts) For this proxy shutdown is a no-op
salt.proxy.rest_sample.test_from_state() Test function so we have something to call from a state :return:
salt.proxy.rest_sample.uptodate(name) Call the REST endpoint to see if the packages on the "server" are up to date.
salt.proxy.ssh_sample This is a simple proxy-minion designed to connect to and communicate with a server that exposes functionality via SSH.  This can be used as an option when the device does not provide an api over HTTP and doesn't have the python stack to run a minion.
salt.proxy.ssh_sample.fns() Method called by grains module.
salt.proxy.ssh_sample.grains() Get the grains from the proxied device
salt.proxy.ssh_sample.grains_refresh() Refresh the grains from the proxied device
salt.proxy.ssh_sample.init(opts) Required.  Can be used to initialize the server connection.
salt.proxy.ssh_sample.initialized() Since grains are loaded in many different places and some of those places occur before the proxy can be initialized, return whether our init() function has been called
salt.proxy.ssh_sample.package_install(name, **kwargs) Install a "package" on the ssh server
salt.proxy.ssh_sample.package_list() List "packages" by executing a command via ssh This function is called in response to the salt command
salt.proxy.ssh_sample.package_remove(name) Remove a "package" on the ssh server
salt.proxy.ssh_sample.parse(out) Extract json from out.
Parameter out: Type string. The data returned by the ssh command.
salt.proxy.ssh_sample.ping() Required.  Ping the device on the other end of the connection
salt.proxy.ssh_sample.service_list() Start a "service" on the ssh server
salt.proxy.ssh_sample.service_restart(name) Restart a "service" on the ssh server
salt.proxy.ssh_sample.service_start(name) Start a "service" on the ssh server
salt.proxy.ssh_sample.service_stop(name) Stop a "service" on the ssh server
salt.proxy.ssh_sample.shutdown(opts) Disconnect
salt.proxy.vcenter Proxy Minion interface module for managing VMWare vCenters.
codeauthor Rod McKenzie (roderick.mckenzie@morganstanley.com)
codeauthor Alexandru Bleotu (alexandru.bleotu@morganstanley.com)
Configuration To use this proxy module, please use on of the following configurations:
proxy: proxytype: vcenter vcenter: <ip or dns name of parent vcenter> username: <vCenter username> mechanism: userpass passwords: - first_password - second_password - third_password
proxy: proxytype: vcenter vcenter: <ip or dns name of parent vcenter> username: <vCenter username> domain: <user domain> mechanism: sspi principal: <host kerberos principal>
proxytype The proxytype key and value pair is critical, as it tells Salt which interface to load from the proxy directory in Salt's install hierarchy, or from /srv/salt/_proxy on the Salt Master (if you have created your own proxy module, for example). To use this Proxy Module, set this to vcenter.
vcenter The location of the VMware vCenter server (host of ip). Required
username The username used to login to the vcenter, such as root.  Required only for userpass.
passwords A list of passwords to be used to try and login to the vCenter server. At least one password in this list is required if mechanism is userpass
The proxy integration will try the passwords listed in order.
domain User domain. Required if mechanism is sspi
principal Kerberos principal. Rquired if mechanism is sspi
protocol If the vCenter is not using the default protocol, set this value to an alternate protocol. Default is https.
salt-proxy --proxyid <id of the cluster>
salt-key -a <id you gave the vcenter host>
At this point you can execute one-off commands against the vcenter. For example, you can get if the proxy can actually connect to the vCenter:
salt <id> vsphere.test_vcenter_connection
It's important to understand how this particular proxy works. Salt.modules.vsphere is a standard Salt execution module.
If you pull up the docs for it you'll see that almost every function in the module takes credentials and a targets either a vcenter or a host. When credentials and a host aren't passed, Salt runs commands through pyVmomi against the local machine. If you wanted, you could run functions from this module on any host where an appropriate version of pyVmomi is installed, and that host would reach out over the network and communicate with the ESXi host.
salt.proxy.vcenter.find_credentials() Cycle through all the possible credentials and return the first one that works.
salt.proxy.vcenter.get_details() Function that returns the cached details
salt.proxy.vcenter.init(opts) This function gets called when the proxy starts up.  For login the protocol and port are cached.
salt.proxy.vcenter.ping() Returns True.
salt vcenter test.ping
salt.proxy.vcenter.shutdown() Shutdown the connection to the proxy device. For this proxy, shutdown is a no-op.
queue modules ┌──────────────┬──────────────────────────┐ │pgjsonb_queue │ New in version 2016.3.0. │ ├──────────────┼──────────────────────────┤ │sqlite_queue  │ New in version 2014.7.0. │ └──────────────┴──────────────────────────┘
salt.queues.pgjsonb_queue New in version 2016.3.0.
This is a queue with postgres as the backend.  It uses the jsonb store to store information for queues.
To enable this queue, the following needs to be configured in your master config. These are the defaults:
queue.pgjsonb.host: 'salt' queue.pgjsonb.user: 'salt' queue.pgjsonb.password: 'salt' queue.pgjsonb.dbname: 'salt' queue.pgjsonb.port: 5432
-- -- Table structure for table `salt` -- DROP TABLE IF EXISTS salt; CREATE OR REPLACE TABLE salt( id SERIAL PRIMARY KEY, data jsonb NOT NULL );
salt-run queue.insert test '{"name": "redis", "host": "172.16.0.8", "port": 6379}' backend=pgjsonb salt-run queue.process_queue test all backend=pgjsonb
salt.queues.pgjsonb_queue.delete(queue, items) Delete an item or items from a queue
salt.queues.pgjsonb_queue.handle_queue_creation(queue)
salt.queues.pgjsonb_queue.insert(queue, items) Add an item or items to a queue
salt.queues.pgjsonb_queue.list_items(queue) List contents of a queue
salt.queues.pgjsonb_queue.list_length(queue) Provide the number of items in a queue
salt.queues.pgjsonb_queue.list_queues() Return a list of Salt Queues on the Salt Master
salt.queues.pgjsonb_queue.pop(queue, quantity=1, is_runner=False) Pop one or more or all items from the queue return them.
salt.queues.sqlite_queue New in version 2014.7.0.
This is the default local master event queue built on sqlite.  By default, an sqlite3 database file is created in the sqlite_queue_dir which is found at:
/var/cache/salt/master/queues
It's possible to store the sqlite3 database files by setting sqlite_queue_dir to another location:
sqlite_queue_dir: /home/myuser/salt/master/queues
salt.queues.sqlite_queue.delete(queue, items) Delete an item or items from a queue
salt.queues.sqlite_queue.insert(queue, items) Add an item or items to a queue
salt.queues.sqlite_queue.list_items(queue) List contents of a queue
salt.queues.sqlite_queue.list_length(queue) Provide the number of items in a queue
salt.queues.sqlite_queue.list_queues() Return a list of Salt Queues on the Salt Master
salt.queues.sqlite_queue.pop(queue, quantity=1, is_runner=False) Pop one or more or all items from the queue return them.
roster modules ┌─────────────┬─────────────────────────────┐ │ansible      │ Read in an Ansible          │ │             │ inventory file or script    │ ├─────────────┼─────────────────────────────┤ │cache        │ The cache roster provides a │ │             │ flexible interface to the   │ │             │ Salt Masters' minion cache  │ │             │ to access regular minions   │ │             │ over salt-ssh.              │ ├─────────────┼─────────────────────────────┤ │cloud        │ Use the cloud cache on the  │ │             │ master to derive IPv4       │ │             │ addresses based on minion   │ │             │ ID.                         │ ├─────────────┼─────────────────────────────┤ │clustershell │ This roster resolves        │ │             │ hostname in a               │ │             │ pdsh/clustershell style.    │ ├─────────────┼─────────────────────────────┤ │dir          │ Create a salt roster out of │ │             │ a flat directory of files.  │ ├─────────────┼─────────────────────────────┤ │flat         │ Read in the roster from a   │ │             │ flat file using the         │ │             │ renderer system             │ ├─────────────┼─────────────────────────────┤ │range        │ This roster resolves        │ │             │ targets from a range        │ │             │ server.                     │ ├─────────────┼─────────────────────────────┤ │scan         │ Scan a netmask or ipaddr    │ │             │ for open ssh ports          │ ├─────────────┼─────────────────────────────┤ │sshconfig    │ Parses roster entries out   │ │             │ of Host directives from SSH │ │             │ config                      │ ├─────────────┼─────────────────────────────┤ │terraform    │ Dynamic roster from         │ │             │ terraform current state     │ └─────────────┴─────────────────────────────┘
salt.roster.ansible Read in an Ansible inventory file or script
Flat inventory files should be in the regular ansible inventory format.
[servers] salt.gtmanfred.com ansible_ssh_user=gtmanfred ansible_ssh_host=127.0.0.1 ansible_ssh_port=22 ansible_ssh_pass='password'
[desktop] home ansible_ssh_user=gtmanfred ansible_ssh_host=12.34.56.78 ansible_ssh_port=23 ansible_ssh_pass='password'
[computers:children] desktop servers
[names:vars] http_port=80
then salt-ssh can be used to hit any of them
[~]# salt-ssh -N all test.ping salt.gtmanfred.com: True home: True [~]# salt-ssh -N desktop test.ping home: True [~]# salt-ssh -N computers test.ping salt.gtmanfred.com: True home: True [~]# salt-ssh salt.gtmanfred.com test.ping salt.gtmanfred.com: True
There is also the option of specifying a dynamic inventory, and generating it on the fly
#!/bin/bash echo '{ "servers": [ "salt.gtmanfred.com" ], "desktop": [ "home" ], "computers": { "hosts": [], "children": [ "desktop", "servers" ] }, "_meta": { "hostvars": { "salt.gtmanfred.com": { "ansible_ssh_user": "gtmanfred", "ansible_ssh_host": "127.0.0.1", "ansible_sudo_pass": "password", "ansible_ssh_port": 22 }, "home": { "ansible_ssh_user": "gtmanfred", "ansible_ssh_host": "12.34.56.78", "ansible_sudo_pass": "password", "ansible_ssh_port": 23 } } } }'
This is the format that an inventory script needs to output to work with ansible, and thus here.
[~]# salt-ssh --roster-file /etc/salt/hosts salt.gtmanfred.com test.ping salt.gtmanfred.com: True
Any of the [groups] or direct hostnames will return.  The 'all' is special, and returns everything.
salt.roster.ansible.targets(tgt, tgt_type='glob', **kwargs) Return the targets from the ansible inventory_file Default: /etc/salt/roster
salt.roster.cache The cache roster provides a flexible interface to the Salt Masters' minion cache to access regular minions over salt-ssh.
New in version 2017.7.0: .IP • 2 grains, pillar, mine data matching
• SDB URLs
• IPv6 support
• roster_order per config key
• default order changed to industry-wide best practices
• CIDR range selection
Targeting This roster supports all matching and targeting of the Salt Master.  The matching will be done using only the Salt Master's cache.
The Roster Order The roster's composition can be configured using roster_order.  In the roster_order you can define any roster key and fill it with a parameter overriding the one in roster_defaults:
roster_order: host: id          # use the minion id as hostname
You can define lists of parameters as well, the first result from the list will become the value.
Selecting a host # default roster_order: host: - ipv6-private  # IPv6 addresses in private ranges - ipv6-global   # IPv6 addresses in global ranges - ipv4-private  # IPv4 addresses in private ranges - ipv4-public   # IPv4 addresses in public ranges - ipv4-local    # loopback addresses
This is the default roster_order.  It prefers IPv6 over IPv4 addresses and private addresses over public ones.  The relevant data will be fetched from the cache in-order, and the first match will fill the host key.
Other address selection parameters are also possible:
roster_order: host: - global|public|private|local    # Both IPv6 and IPv4 addresses in that range - 2000::/3                       # CIDR networks, both IPv4 and IPv6 are supported
Using cached data Several cached libraries can be selected using the library: `` prefix, followed by the library key.  This can be referenced using the same ``: syntax as e.g. pillar.get.  Lists of references are also supported during the lookup, as are Salt SDB URLs.
This should be especially useful for the other roster keys:
roster_order: host: - grain: fqdn_ip4                # Lookup this grain - mine: network.ip_addrs         # Mine data lookup works the same
password: sdb://vault/ssh_pass     # Salt SDB URLs are also supported
user: - pillar: ssh:auth:user          # Lookup this pillar key - sdb://osenv/USER               # Lookup this env var through sdb
priv: - pillar:                        # Lists are also supported - salt:ssh:private_key - ssh:auth:private_key
salt.roster.cache.targets(tgt, tgt_type='glob', **kwargs) Return the targets from the Salt Masters' minion cache.  All targets and matchers are supported.
The resulting roster can be configured using roster_order and roster_default.
salt.roster.cloud Use the cloud cache on the master to derive IPv4 addresses based on minion ID.
This roster requires that the minion in question was created using at least the 2015.5.0 version of Salt Cloud. Starting with the 2015.5.0 release, Salt Cloud maintains an index of minions that it creates and deletes. This index tracks the provider and profile configuration used to provision the minion, including authentication information. So long as this configuration remains current, it can be used by Salt SSH to log into any minion in the index.
To connect as a user other than root, modify the cloud configuration file usually located at /etc/salt/cloud. For example, add the following:
ssh_username: my_user sudo: True
salt.roster.cloud.extract_ipv4(roster_order, ipv4) Extract the preferred IP address from the ipv4 grain
salt.roster.cloud.targets(tgt, tgt_type='glob', **kwargs) Return the targets from the flat yaml file, checks opts for location but defaults to /etc/salt/roster
salt.roster.clustershell This roster resolves hostname in a pdsh/clustershell style.
depends clustershell, https://github.com/cea-hpc/clustershell
When you want to use host globs for target matching, use --roster clustershell. For example:
salt-ssh --roster clustershell 'server_[1-10,21-30],test_server[5,7,9]' test.ping
salt.roster.clustershell.targets(tgt, tgt_type='glob', **kwargs) Return the targets
salt.roster.dir Create a salt roster out of a flat directory of files.
Each filename in the directory is a minion id.  The contents of each file is rendered using the salt renderer system.
Consider the following configuration for example:
config/master: ...  roster: dir roster_dir: config/roster.d ...
Where the directory config/roster.d contains two files:
config/roster.d/minion-x: host: minion-x.example.com port: 22 sudo: true user: ubuntu
config/roster.d/minion-y: host: minion-y.example.com port: 22 sudo: true user: gentoo
The roster would find two minions: minion-x and minion-y, with the given host, port, sudo and user settings.
The directory roster also extends the concept of roster defaults by supporting a roster_domain value in config: ...  roster_domain: example.org ...
If that option is set, then any roster without a 'host' setting will have an implicit host of its minion id + '.' + the roster_domain. (The default roster_domain is the empty string, so you can also name the files the fully qualified name of each host. However, if you do that, then the fully qualified name of each host is also the minion id.)
This makes it possible to avoid having to specify the hostnames when you always want them to match their minion id plus some domain.
salt.roster.dir.targets(tgt, tgt_type='glob', **kwargs) Return the targets from the directory of flat yaml files, checks opts for location.
salt.roster.flat Read in the roster from a flat file using the renderer system
salt.roster.flat.targets(tgt, tgt_type='glob', **kwargs) Return the targets from the flat yaml file, checks opts for location but defaults to /etc/salt/roster
salt.roster.range This roster resolves targets from a range server.
depends seco.range, https://github.com/ytoolshed/range
When you want to use a range query for target matching, use --roster range. For example:
salt-ssh --roster range '%%%example.range.cluster' test.ping
salt.roster.range.target_glob(tgt, hosts)
salt.roster.range.target_range(tgt, hosts)
salt.roster.range.targets(tgt, tgt_type='range', **kwargs) Return the targets from a range query
salt.roster.scan Scan a netmask or ipaddr for open ssh ports
class salt.roster.scan.RosterMatcher(tgt, tgt_type) Matcher for the roster data structure
targets() Return ip addrs based on netmask, sitting in the "glob" spot because it is the default
salt.roster.scan.targets(tgt, tgt_type='glob', **kwargs) Return the targets from the flat yaml file, checks opts for location but defaults to /etc/salt/roster
salt.roster.sshconfig Parses roster entries out of Host directives from SSH config
salt-ssh --roster sshconfig '*' -r "echo hi"
class salt.roster.sshconfig.RosterMatcher(raw, tgt, tgt_type) Matcher for the roster data structure
get_data(minion) Return the configured ip
ret_glob_minions() Return minions that match via glob
targets() Execute the correct tgt_type routine and return
salt.roster.sshconfig.parse_ssh_config(lines) Parses lines from the SSH config to create roster targets.
Parameters lines -- Individual lines from the ssh config file
Returns Dictionary of targets in similar style to the flat roster
salt.roster.sshconfig.targets(tgt, tgt_type='glob', **kwargs) Return the targets from the flat yaml file, checks opts for location but defaults to /etc/salt/roster
salt.roster.terraform Dynamic roster from terraform current state This roster module allows you dynamically generate the roster from the terraform resources defined with the Terraform Salt provider.
It exposes all salt_host resources with the same attributes to the salt-ssh roster, making it completely independent of the type of terraform resource, and providing the integration using terraform constructs with interpolation.
Basic Example Given a simple salt-ssh tree with a Saltfile:
salt-ssh: config_dir: etc/salt max_procs: 30 wipe_ssh: True
and etc/salt/master:
root_dir: . file_roots: base: - srv/salt pillar_roots: base: - srv/pillar roster: terraform
In the same folder as your Saltfile, create terraform file with resources like cloud instances, virtual machines, etc. For every single one of those that you want to manage with Salt, create a salt_host resource:
resource "salt_host" "dbminion" { salt_id = "dbserver" host = "${libvirt_domain.vm-db.network_interface.0.addresses.0}" user = "root" passwd = "linux" }
You can use the count attribute to create multiple roster entries with a single definition. Please refer to the Terraform Salt provider for more detailed examples.
salt.roster.terraform.targets(tgt, tgt_type='glob', **kwargs) Returns the roster from the terraform state file, checks opts for location, but defaults to terraform.tfstate
│ssh           │ A Runner module interface   │ │              │ on top of the salt-ssh      │ │              │ Python API.                 │ ├──────────────┼─────────────────────────────┤ │state         │ Execute orchestration       │ │              │ functions                   │ ├──────────────┼─────────────────────────────┤ │survey        │ A general map/reduce style  │ │              │ salt runner for aggregating │ │              │ results returned by several │ │              │ different minions.          │ ├──────────────┼─────────────────────────────┤ │test          │ This runner is used only    │ │              │ for test purposes and       │ │              │ servers no production       │ │              │ purpose                     │ ├──────────────┼─────────────────────────────┤ │thin          │ The thin runner is used to  │ │              │ manage the salt thin        │ │              │ systems.                    │ ├──────────────┼─────────────────────────────┤ │vault         │                             │ │              │        maintainer           │ │              │               SaltStack     │ ├──────────────┼─────────────────────────────┤ │venafiapi     │ Support for Venafi          │ ├──────────────┼─────────────────────────────┤ │virt          │ Control virtual machines    │ │              │ via Salt                    │ ├──────────────┼─────────────────────────────┤ │vistara       │ Vistara Runner              │ ├──────────────┼─────────────────────────────┤ │winrepo       │ Runner to manage Windows    │ │              │ software repo               │ └──────────────┴─────────────────────────────┘
salt.runners.asam Novell ASAM Runner New in version 2015.8.0.
Runner to interact with Novell ASAM Fan-Out Driver
To use this runner, set up the Novell Fan-Out Driver URL, username and password in the master configuration at /etc/salt/master or /etc/salt/master.d/asam.conf:
asam: prov1.domain.com username: "testuser" password: "verybadpass" verify_ssl: true prov2.domain.com username: "testuser" password: "verybadpass" verify_ssl: true
NOTE: Optionally, protocol and port can be specified if the Fan-Out Driver server is not using the defaults. Default is protocol: https and port: 3451.
class salt.runners.asam.ASAMHTMLParser
handle_starttag(tag, attrs)
salt.runners.asam.add_platform(name, platform_set, server_url) To add an ASAM platform using the specified ASAM platform set on the Novell Fan-Out Driver
salt-run asam.add_platform my-test-vm test-platform-set prov1.domain.com
salt.runners.asam.list_platform_sets(server_url) To list all ASAM platform sets present on the Novell Fan-Out Driver
salt-run asam.list_platform_sets prov1.domain.com
salt.runners.asam.list_platforms(server_url) To list all ASAM platforms present on the Novell Fan-Out Driver
salt-run asam.list_platforms prov1.domain.com
salt.runners.asam.remove_platform(name, server_url) To remove specified ASAM platform from the Novell Fan-Out Driver
salt-run asam.remove_platform my-test-vm prov1.domain.com
salt.runners.auth Authentication runner for creating, deleting, and managing eauth tokens.
salt.runners.auth.del_token(token) Delete an eauth token by name
salt-run auth.del_token 6556760736e4077daa601baec2b67c24
salt.runners.auth.mk_token(**load) Create an eauth token using provided credentials
Non-root users may specify an expiration date -- if allowed via the token_expire_user_override setting -- by passing an additional token_expire param. This overrides the token_expire setting of the same name in the Master config and is how long a token should live in seconds.
salt-run auth.mk_token username=saltdev password=saltdev eauth=auto
# Create a token valid for three years. salt-run auth.mk_token username=saltdev password=saltdev eauth=auto \ token_expire=94670856
# Calculate the number of seconds using expr. salt-run auth.mk_token username=saltdev password=saltdev eauth=auto \ token_expire=$(expr \( 365 \* 24 \* 60 \* 60 \) \* 3)
salt.runners.bgp BGP Finder New in version 2017.7.0.
Runner to search BGP neighbors details.
Configuration • Minion (proxy) config The bgp.neighbors function must be appened in the list of mine_functions:
mine_functions: bgp.neighbors: []
Which instructs Salt to cache the data returned by the neighbors function from the NAPALM BGP module.
How often the mines are refreshed, can be specified using:
mine_interval: <X minutes>
• Master config By default the following options can be configured on the master. They are not mandatory, but available in case the user has different requirements.
tgt: * From what minions will collect the mine data.  Default: * (collect mine data from all minions)
tgt_type: glob Minion matching expression form. Default: glob.
return_fields What fields to return in the output.  It can display all the fields from the neighbors function from the NAPALM BGP module.
Some fields cannot be removed:
• as_number: the AS number of the neighbor
• device: the minion ID
• neighbor_address: the neighbor remote IP address
By default, the following extra fields are returned (displayed):
• connection_stats: connection stats, as described below
• import_policy: the name of the import policy
• export_policy: the name of the export policy
Special fields:
• vrf: return the name of the VRF.
• connection_stats: returning an output of the form <State> <Active>/<Received>/<Accepted>/<Damped>, e.g.  Established 398/399/399/0 similar to the usual output from network devices.
• interface_description: matches the neighbor details with the corresponding interface and returns its description. This will reuse functionality from the net runner, so the user needs to enable the mines as specified in the documentation.
• interface_name: matches the neighbor details with the corresponding interface and returns the name.  Similar to interface_description, this will reuse functionality from the net runner, so the user needs to enable the mines as specified in the documentation.
display: True Display on the screen or return structured object? Default: True (return on the CLI).
outputter: table Specify the outputter name when displaying on the CLI. Default: table.
runners: bgp: tgt: 'edge*' tgt_type: 'glob' return_fields: - up - connection_state - previous_connection_state - suppress_4byte_as - holdtime - flap_count outputter: yaml
salt.runners.bgp.neighbors(*asns, **kwargs) Search for BGP neighbors details in the mines of the bgp.neighbors function.
asns   A list of AS numbers to search for.  The runner will return only the neighbors of these AS numbers.
device Filter by device name (minion ID).
ip     Search BGP neighbor using the IP address.  In multi-VRF environments, the same IP address could be used by more than one neighbors, in different routing tables.
network Search neighbors within a certain IP network.
title  Custom title.
In addition, any field from the output of the neighbors function from the NAPALM BGP module can be used as a filter.
salt-run bgp.neighbors 13335 15169 salt-run bgp.neighbors 13335 ip=172.17.19.1 salt-run bgp.neighbors multipath=True salt-run bgp.neighbors up=False export_policy=my-export-policy multihop=False salt-run bgp.neighbors network=192.168.0.0/16
BGP Neighbors for 13335, 15169 ________________________________________________________________________________________________________________________________________________________________ |    Device    | AS Number |         Neighbor Address        | State|#Active/Received/Accepted/Damped |         Policy IN         |         Policy OUT         | ________________________________________________________________________________________________________________________________________________________________ | edge01.bjm01 |   13335   |          172.17.109.11          |        Established 0/398/398/0         |       import-policy       |        export-policy       | ________________________________________________________________________________________________________________________________________________________________ | edge01.bjm01 |   13335   |          172.17.109.12          |       Established 397/398/398/0        |       import-policy       |        export-policy       | ________________________________________________________________________________________________________________________________________________________________ | edge01.flw01 |   13335   |          192.168.172.11         |        Established 1/398/398/0         |       import-policy       |        export-policy       | ________________________________________________________________________________________________________________________________________________________________ | edge01.oua01 |   13335   |          172.17.109.17          |          Established 0/0/0/0           |       import-policy       |        export-policy       | ________________________________________________________________________________________________________________________________________________________________ | edge01.bjm01 |   15169   |             2001::1             |       Established 102/102/102/0        |       import-policy       |        export-policy       | ________________________________________________________________________________________________________________________________________________________________ | edge01.bjm01 |   15169   |             2001::2             |       Established 102/102/102/0        |       import-policy       |        export-policy       | ________________________________________________________________________________________________________________________________________________________________ | edge01.tbg01 |   13335   |          192.168.172.17         |          Established 0/1/1/0           |       import-policy       |        export-policy       | ________________________________________________________________________________________________________________________________________________________________
salt.runners.cache Return cached data from minions
salt.runners.cache.clear_all(tgt=None, tgt_type='glob') Changed in version 2017.7.0: The expr_form argument has been renamed to tgt_type, earlier releases must use expr_form.
Clear the cached pillar, grains, and mine data of the targeted minions
salt-run cache.clear_all
salt.runners.cache.clear_git_lock(role, remote=None, **kwargs) New in version 2015.8.2.
Remove the update locks for Salt components (gitfs, git_pillar, winrepo) which use gitfs backend code from salt.utils.gitfs.
NOTE: Running cache.clear_all will not include this function as it does for pillar, grains, and mine.
Additionally, executing this function with a role of gitfs is equivalent to running salt-run fileserver.clear_lock backend=git.
role   Which type of lock to remove (gitfs, git_pillar, or winrepo)