neulab/tldr huggingface dataset:
-r REJECT, --reject=REJECT Reject the specified public key (use --include-all to match accepted keys in addition to pending keys). Globs are supported.
-R, --reject-all Rejects all pending keys.
--include-all Include non-pending keys when accepting/rejecting.
-p PRINT, --print=PRINT Print the specified public key.
-P, --print-all Print all public keys
-d DELETE, --delete=DELETE Delete the specified key. Globs are supported.
-D, --delete-all Delete all keys.
-f FINGER, --finger=FINGER Print the specified key's fingerprint.
-F, --finger-all Print all keys' fingerprints.
Key Generation Options --gen-keys=GEN_KEYS Set a name to generate a keypair for use with salt
--gen-keys-dir=GEN_KEYS_DIR Set the directory to save the generated keypair.  Only works with 'gen_keys_dir' option; default is the current directory.
--keysize=KEYSIZE Set the keysize for the generated key, only works with the '--gen-keys' option, the key size must be 2048 or higher, otherwise it will be rounded up to 2048. The default is 2048.
--gen-signature Create a signature file of the master's public-key named master_pubkey_signature. The signature can be sent to a minion in the master's auth-reply and enables the minion to verify the master's public-key cryptographically. This requires a new signing-key-pair which can be auto-created with the --auto-create parameter.
--priv=PRIV The private-key file to create a signature with
--signature-path=SIGNATURE_PATH The path where the signature file should be written
--pub=PUB The public-key file to create a signature for
--auto-create Auto-create a signing key-pair if it does not yet exist
salt-master salt-master The Salt master daemon, used to control the Salt minions
Synopsis salt-master [ options ]
Description The master daemon controls the Salt minions
-u USER, --user=USER Specify user to run salt-master
-d, --daemon Run salt-master as a daemon
--pid-file PIDFILE Specify the location of the pidfile. Default: /var/run/salt-master.pid
See also salt(1) salt(7) salt-minion(1)
salt-minion salt-minion The Salt minion daemon, receives commands from a remote Salt master.
Synopsis salt-minion [ options ]
Description The Salt minion receives commands from the central Salt master and replies with the results of said commands.
-u USER, --user=USER Specify user to run salt-minion
-d, --daemon Run salt-minion as a daemon
--pid-file PIDFILE Specify the location of the pidfile. Default: /var/run/salt-minion.pid
See also salt(1) salt(7) salt-master(1)
salt-proxy salt-proxy Receives commands from a Salt master and proxies these commands to devices that are unable to run a full minion.
Synopsis salt-proxy [ options ]
Description The Salt proxy minion receives commands from a Salt master, transmits appropriate commands to devices that are unable to run a minion, and replies with the results of said commands.
Options --proxyid The minion id that this proxy will assume.  This is required.
--version Print the version of Salt that is running.
-c CONFIG_DIR, --config-dir=CONFIG_dir The location of the Salt configuration directory. This directory contains  the  configuration  files for Salt master and minions. The default location on most systems is /etc/salt.
-u USER, --user=USER Specify user to run salt-proxy
-d, --daemon Run salt-proxy as a daemon
--pid-file PIDFILE Specify the location of the pidfile. Default: /var/run/salt-proxy-<id>.pid
See also salt(1) salt(7) salt-master(1) salt-minion(1)
salt-run salt-run Execute a Salt runner
Synopsis salt-run RUNNER
Description salt-run is the frontend command for executing Salt Runners.  Salt runners are simple modules used to execute convenience functions on the master
-t TIMEOUT, --timeout=TIMEOUT The timeout in seconds to wait for replies from the Salt minions. The timeout number specifies how long the command line client will wait to query the minions and check on running jobs. Default: 1
-d, --doc, --documentation Display documentation for runners, pass a module or a runner to see documentation on only that module/runner.
salt-ssh salt-ssh Synopsis salt-ssh '*' [ options ] sys.doc
salt-ssh -E '.*' [ options ] sys.doc cmd
Description Salt SSH allows for salt routines to be executed using only SSH for transport
--hard-crash Raise any original exception rather than exiting gracefully. Default: False.
-r, --raw, --raw-shell Execute a raw shell command.
--roster Define which roster system to use, this defines if a database backend, scanner, or custom roster system is used. Default is the flat file roster.
--roster-file Define an alternative location for the default roster file location. The default roster file is called roster and is found in the same directory as the master config file.
--refresh, --refresh-cache Force a refresh of the master side data cache of the target's data. This is needed if a target's grains have been changed and the auto refresh timeframe has not been reached.
--max-procs Set the number of concurrent minions to communicate with. This value defines how many processes are opened up at a time to manage connections, the more running process the faster communication should be, default is 25.
--extra-filerefs=EXTRA_FILEREFS Pass in extra files to include in the state tarball.
--min-extra-modules=MIN_EXTRA_MODS One or comma-separated list of extra Python modulesto be included into Minimal Salt.
--thin-extra-modules=THIN_EXTRA_MODS One or comma-separated list of extra Python modulesto  be included into Thin Salt.
-v, --verbose Turn on command verbosity, display jid.
-s, --static Return the data from minions as a group after they all return.
-w, --wipe Remove the deployment of the salt files when done executing.
-W, --rand-thin-dir Select a random temp dir to deploy on the remote system. The dir will be cleaned after the execution.
-t, --regen-thin, --thin Trigger a thin tarball regeneration. This is needed if  custom grains/modules/states have been added or updated.
--python2-bin=PYTHON2_BIN Path to a python2 binary which has salt installed.
--python3-bin=PYTHON3_BIN Path to a python3 binary which has salt installed.
--jid=JID Pass a JID to be used instead of generating one.
--pre-flight Run the ssh_pre_flight script defined in the roster.  By default this script will only run if the thin dir does not exist on the target minion. This option will force the script to run regardless of the thin dir existing or not.
Authentication Options --priv=SSH_PRIV Specify the SSH private key file to be used for authentication.
--priv-passwd=SSH_PRIV_PASSWD Specify the SSH private key file's passphrase if need be.
-i, --ignore-host-keys By default ssh host keys are honored and connections  will ask for approval. Use this option to disable StrictHostKeyChecking.
--no-host-keys Fully ignores ssh host keys which by default are honored and connections would ask for approval. Useful if the host key of a remote server has changed and would still error with --ignore-host-keys.
--user=SSH_USER Set the default user to attempt to use when authenticating.
--passwd Set the default password to attempt to use when authenticating.
--askpass Interactively ask for the SSH password with no echo - avoids password in process args and stored in history.
--key-deploy Set this flag to attempt to deploy the authorized ssh key with all minions. This combined with --passwd can make initial deployment of keys very fast and easy.
--identities-only Use the only authentication identity files configured in the ssh_config files. See IdentitiesOnly flag in man ssh_config.
--sudo Run command via sudo.
Scan Roster Options --scan-ports=SSH_SCAN_PORTS Comma-separated list of ports to scan in the scan roster.
--scan-timeout=SSH_SCAN_TIMEOUT Scanning socket timeout for the scan roster.
--log-file=LOG_FILE Log file path. Default: /var/log/salt/ssh.
salt-syndic salt-syndic The Salt syndic daemon, a special minion that passes through commands from a higher master
Synopsis salt-syndic [ options ]
Description The Salt syndic daemon, a special minion that passes through commands from a higher master.
-u USER, --user=USER Specify user to run salt-syndic
-d, --daemon Run salt-syndic as a daemon
--pid-file PIDFILE Specify the location of the pidfile. Default: /var/run/salt-syndic.pid
salt-unity salt-unity A unified invocation wrapper around other Salt CLI scripts.
Synopsis salt-unity salt '*' test.version
Description This script takes an argument which is one of the other Salt CLI scripts and invokes that script.
Options See also salt-api(1) salt-call(1) salt-cloud(1) salt-cp(1) salt-key(1) salt-main(1) salt-master(1) salt-minion(1) salt-run(1) salt-ssh(1) salt-syndic(1)
spm spm Salt Package Manager
Synopsis spm <command> [<argument>]
Description spm is the frontend command for managing Salt packages. Packages normally only include formulas, meaning a group of SLS files that install into the file_roots on the Salt Master, but Salt modules can also be installed.
Options -y, --assume-yes Assume yes instead of prompting the other whether or not to proceed with a particular command. Default is False.
-f, --force When presented with a course of action that spm would normally refuse to perform, that action will be performed anyway. This is often destructive, and should be used with caution.
--log-file=LOG_FILE Log file path. Default: /var/log/salt/spm.
Commands update_repo Connect to remote repositories locally configured on the system and download their metadata.
install Install a package from a configured SPM repository. Requires a package name.
remove Remove an installed package from the system. Requires a package name.
info   List information about an installed package. Requires a package name.
files  List files belonging to an installed package. Requires a package name.
local  Perform one of the above options (except for remove) on a package file, instead of on a package in a repository, or an installed package. Requires a valid path to a local file on the system.
build  Build a package from a directory containing a FORMULA file. Requires a valid path to a local directory on the system.
create_repo Scan a directory for valid SPM package files and build an SPM-METADATA file in that directory which describes them.
Salt includes a number of built-in external pillars, listed at all-salt.pillars.
The below links contain documentation for the configuration options
• master-side configuration
• minion-side configuration
Note that some of same the configuration options from the master are present in the minion configuration file, these are used in masterless mode.
The source for the built-in Salt pillars can be found here: https://github.com/saltstack/salt/blob/master/salt/pillar
Salt includes a number of built-in subsystems to generate top file data, they are listed at all-salt.tops.
The source for the built-in Salt master tops can be found here: https://github.com/saltstack/salt/blob/master/salt/tops
This section contains a list of the Python modules that are used to extend the various subsystems within Salt.
auth modules ┌─────────────┬─────────────────────────────┐ │auto         │ An "Always Approved" eauth  │ │             │ interface to test against,  │ │             │ not intended for production │ │             │ use                         │ ├─────────────┼─────────────────────────────┤ │django       │ Provide authentication      │ │             │ using Django Web Framework  │ ├─────────────┼─────────────────────────────┤ │file         │ Provide authentication      │ │             │ using local files           │ ├─────────────┼─────────────────────────────┤ │keystone     │ Provide authentication      │ │             │ using OpenStack Keystone    │ ├─────────────┼─────────────────────────────┤ │ldap         │ Provide authentication      │ │             │ using simple LDAP binds     │ ├─────────────┼─────────────────────────────┤ │mysql        │ Provide authentication      │ │             │ using MySQL.                │ ├─────────────┼─────────────────────────────┤ │pam          │ Authenticate against PAM    │ ├─────────────┼─────────────────────────────┤ │pki          │ Authenticate via a PKI      │ │             │ certificate.                │ ├─────────────┼─────────────────────────────┤ │rest         │ Provide authentication      │ │             │ using a REST call           │ ├─────────────┼─────────────────────────────┤ │sharedsecret │ Provide authentication      │ │             │ using configured shared     │ │             │ secret                      │ ├─────────────┼─────────────────────────────┤ │yubico       │ Provide authentication      │ │             │ using YubiKey.              │ └─────────────┴─────────────────────────────┘
salt.auth.auto An "Always Approved" eauth interface to test against, not intended for production use
salt.auth.auto.auth(username, password) Authenticate!
salt.auth.django Provide authentication using Django Web Framework
• Django Web Framework
Django authentication depends on the presence of the django framework in the PYTHONPATH, the Django project's settings.py file being in the PYTHONPATH and accessible via the DJANGO_SETTINGS_MODULE environment variable.
Django auth can be defined like any other eauth module:
external_auth: django: fred: - .* - '@runner'
This will authenticate Fred via Django and allow him to run any execution module and all runners.
The authorization details can optionally be located inside the Django database.  The relevant entry in the models.py file would look like this:
class SaltExternalAuthModel(models.Model): user_fk = models.ForeignKey(User, on_delete=models.CASCADE) minion_or_fn_matcher = models.CharField(max_length=255) minion_fn = models.CharField(max_length=255)
The external_auth clause in the master config would then look like this:
external_auth: django: ^model: <fully-qualified reference to model class>
When a user attempts to authenticate via Django, Salt will import the package indicated via the keyword ^model.  That model must have the fields indicated above, though the model DOES NOT have to be named 'SaltExternalAuthModel'.
salt.auth.django.acl(username)
Parameters username -- Username to filter for
Returns Dictionary that can be slotted into the __opts__ structure for eauth that designates the user associated ACL
Database records such as:
┌───────────┬──────────────────────┬────────────────────┐ │username   │ minion_or_fn_matcher │ minion_fn          │ ├───────────┼──────────────────────┼────────────────────┤ │fred       │                      │ test.ping          │ ├───────────┼──────────────────────┼────────────────────┤ │fred       │ server1              │ network.interfaces │ ├───────────┼──────────────────────┼────────────────────┤ │fred       │ server1              │ raid.list          │ ├───────────┼──────────────────────┼────────────────────┤ │fred       │ server2              │ .*                 │ ├───────────┼──────────────────────┼────────────────────┤ │guru       │ .*                   │                    │ ├───────────┼──────────────────────┼────────────────────┤ │smartadmin │ server1              │ .*                 │ └───────────┴──────────────────────┴────────────────────┘
Should result in an eauth config such as:
fred: - test.ping - server1: - network.interfaces - raid.list - server2: - .* guru: - .* smartadmin: - server1: - .*
salt.auth.django.auth(username, password) Simple Django auth
salt.auth.django.is_connection_usable()
salt.auth.file Provide authentication using local files
New in version 2018.3.0.
The file auth module allows simple authentication via local files. Different filetypes are supported, including:
1. Text files, with passwords in plaintext or hashed
2. Apache-style htpasswd files
3. Apache-style htdigest files
NOTE: The python-passlib library is required when using a ^filetype of htpasswd or htdigest.
The simplest example is a plaintext file with usernames and passwords:
external_auth: file: ^filename: /etc/insecure-user-list.txt gene: - .* dean: - test.*
In this example the /etc/insecure-user-list.txt file would be formatted as so:
dean:goneFishing gene:OceanMan
^filename is the only required parameter. Any parameter that begins with a ^ is passed directly to the underlying file authentication function via kwargs, with the leading ^ being stripped.
The text file option is configurable to work with legacy formats:
external_auth: file: ^filename: /etc/legacy_users.txt ^filetype: text ^hashtype: md5 ^username_field: 2 ^password_field: 3 ^field_separator: '|' trey: - .*
This would authenticate users against a file of the following format:
46|trey|16a0034f90b06bf3c5982ed8ac41aab4 555|mike|b6e02a4d2cb2a6ef0669e79be6fd02e4 2001|page|14fce21db306a43d3b680da1a527847a 8888|jon|c4e94ba906578ccf494d71f45795c6cb
NOTE: The hashutil.digest execution function is used for comparing hashed passwords, so any algorithm supported by that function will work.
There is also support for Apache-style htpasswd and htdigest files:
external_auth: file: ^filename: /var/www/html/.htusers ^filetype: htpasswd cory: - .*
When using htdigest the ^realm must be set:
external_auth: file: ^filename: /var/www/html/.htdigest ^filetype: htdigest ^realm: MySecureRealm cory: - .*
salt.auth.file.auth(username, password) File based authentication
^filename The path to the file to use for authentication.
^filetype The type of file: text, htpasswd, htdigest.
Default: text
^realm The realm required by htdigest authentication.
NOTE: The following parameters are only used with the text filetype.
^hashtype The digest format of the password. Can be plaintext or any digest available via hashutil.digest.
Default: plaintext
^field_separator The character to use as a delimiter between fields in a text file.
^username_field The numbered field in the text file that contains the username, with numbering beginning at 1 (one).
^password_field The numbered field in the text file that contains the password, with numbering beginning at 1 (one).
Default: 2
salt.auth.keystone Provide authentication using OpenStack Keystone
• keystoneclient Python module
salt.auth.keystone.auth(username, password) Try and authenticate
salt.auth.keystone.get_auth_url() Try and get the URL from the config, else return localhost
salt.auth.ldap Provide authentication using simple LDAP binds
• ldap Python module
salt.auth.ldap.auth(username, password) Simple LDAP auth
salt.auth.ldap.groups(username, **kwargs) Authenticate against an LDAP group
Behavior is highly dependent on if Active Directory is in use.
AD handles group membership very differently than OpenLDAP.  See the External Authentication documentation for a thorough discussion of available parameters for customizing the search.
OpenLDAP allows you to search for all groups in the directory and returns members of those groups.  Then we check against the username entered.
salt.auth.ldap.process_acl(auth_list, opts=None) Query LDAP, retrieve list of minion_ids from an OU or other search.  For each minion_id returned from the LDAP search, copy the perms matchers into the auth dictionary :param auth_list: :param opts: __opts__ for when __opts__ is not injected :return: Modified auth list.
salt.auth.mysql Provide authentication using MySQL.
When using MySQL as an authentication backend, you will need to create or use an existing table that has a username and a password column.
To get started, create a simple table that holds just a username and a password. The password field will hold a SHA256 checksum.
CREATE TABLE `users` ( `id` int(11) NOT NULL AUTO_INCREMENT, `username` varchar(25) DEFAULT NULL, `password` varchar(70) DEFAULT NULL, PRIMARY KEY (`id`) ) ENGINE=InnoDB AUTO_INCREMENT=2 DEFAULT CHARSET=latin1;
To create a user within MySQL, execute the following statement.
INSERT INTO users VALUES (NULL, 'diana', SHA2('secret', 256))
mysql_auth: hostname: localhost database: SaltStack username: root password: letmein auth_sql: 'SELECT username FROM users WHERE username = "{0}" AND password = SHA2("{1}", 256)'
The auth_sql contains the SQL that will validate a user to ensure they are correctly authenticated. This is where you can specify other SQL queries to authenticate users.
Enable MySQL authentication.
external_auth: mysql: damian: - test.*
• MySQL-python Python module
salt.auth.mysql.auth(username, password) Authenticate using a MySQL user table
salt.auth.pam Authenticate against PAM
Provides an authenticate function that will allow the caller to authenticate a user against the Pluggable Authentication Modules (PAM) on the system.
Implemented using ctypes, so no compilation is necessary.
There is one extra configuration option for pam.  The pam_service that is authenticated against.  This defaults to login
auth.pam.service: login
NOTE: Solaris-like (SmartOS, OmniOS, ...) systems may need auth.pam.service set to other.
NOTE: PAM authentication will not work for the root user.
The Python interface to PAM does not support authenticating as root.
NOTE: Using PAM groups with SSSD groups on python2.
To use sssd with the PAM eauth module and groups the pysss module is needed.  On RedHat/CentOS this is python-sss.
This should not be needed with python >= 3.3, because the os modules has the getgrouplist function.
class salt.auth.pam.PamConv Wrapper class for pam_conv structure
appdata_ptr Structure/Union member
conv   Structure/Union member
class salt.auth.pam.PamHandle Wrapper class for pam_handle_t
handle Structure/Union member
class salt.auth.pam.PamMessage Wrapper class for pam_message structure
msg    Structure/Union member
msg_style Structure/Union member
class salt.auth.pam.PamResponse Wrapper class for pam_response structure
resp   Structure/Union member
resp_retcode Structure/Union member
salt.auth.pam.auth(username, password, **kwargs) Authenticate via pam
salt.auth.pam.authenticate(username, password) Returns True if the given username and password authenticate for the given service.  Returns False otherwise
username: the username to authenticate
password: the password in plain text
salt.auth.pam.groups(username, *args, **kwargs) Retrieve groups for a given user for this auth provider
Uses system groups
salt.auth.pki Authenticate via a PKI certificate.
NOTE: This module is Experimental and should be used with caution
Provides an authenticate function that will allow the caller to authenticate a user via their public cert against a pre-defined Certificate Authority.
TODO: Add a 'ca_dir' option to configure a directory of CA files, a la Apache.
• pyOpenSSL module
salt.auth.pki.auth(username, password, **kwargs) Returns True if the given user cert (password is the cert contents) was issued by the CA and if cert's Common Name is equal to username.
Returns False otherwise.
username: we need it to run the auth function from CLI/API; it should be in master config auth/acl
password: contents of user certificate (pem-encoded user public key); why "password"? For CLI, it's the only available name
Configure the CA cert in the master config file:
external_auth: pki: ca_file: /etc/pki/tls/ca_certs/trusted-ca.crt your_user: - .*
salt.auth.rest Provide authentication using a REST call
REST auth can be defined like any other eauth module:
external_auth: rest: ^url: https://url/for/rest/call fred: - .* - '@runner'
If there are entries underneath the ^url entry then they are merged with any responses from the REST call.  In the above example, assuming the REST call does not return any additional ACLs, this will authenticate Fred via a REST call and allow him to run any execution module and all runners.
The REST call should return a JSON object that maps to a regular eauth YAML structure as above.
salt.auth.rest.auth(username, password) REST authentication
salt.auth.rest.rest_auth_setup()
salt.auth.sharedsecret Provide authentication using configured shared secret
external_auth: sharedsecret: fred: - .* - '@jobs'
The shared secret should be added to the master configuration, for example in /etc/salt/master.d/sharedsecret.conf (make sure that file is only readable by the user running the master):
sharedsecret: OIUHF_CHANGE_THIS_12h88
This auth module should be used with caution. It was initially designed to work with a frontal that takes care of authentication (for example kerberos) and places the shared secret in the HTTP headers to the salt-api call. This salt-api call should really be done on localhost to avoid someone eavesdropping on the shared secret.
See the documentation for cherrypy to setup the headers in your frontal.
salt.auth.sharedsecret.auth(username, password) Shared secret authentication
salt.auth.yubico Provide authentication using YubiKey.
depends yubico-client Python module
To get your YubiKey API key you will need to visit the website below.
https://upgrade.yubico.com/getapikey/
The resulting page will show the generated Client ID (aka AuthID or API ID) and the generated API key (Secret Key). Make a note of both and use these two values in your /etc/salt/master configuration. /etc/salt/master
yubico_users: damian: id: 12345 key: ABCDEFGHIJKLMNOPQRSTUVWXYZ
external_auth: yubico: damian: - test.*
Please wait five to ten minutes after generating the key before testing so that the API key will be updated on all the YubiCloud servers.
salt.auth.yubico.auth(username, password) Authenticate against yubico server
salt.auth.yubico.groups(username, *args, **kwargs)
beacon modules ┌─────────────────┬─────────────────────────────┐ │adb              │ Beacon to emit adb device   │ │                 │ state changes for Android   │ │                 │ devices                     │ ├─────────────────┼─────────────────────────────┤ │aix_account      │ Beacon to fire event when   │ │                 │ we notice a AIX user is     │ │                 │ locked due to many failed   │ │                 │ login attempts.             │ ├─────────────────┼─────────────────────────────┤ │avahi_announce   │ Beacon to announce via      │ │                 │ avahi (zeroconf)            │ ├─────────────────┼─────────────────────────────┤ │bonjour_announce │ Beacon to announce via      │ │                 │ Bonjour (zeroconf)          │ ├─────────────────┼─────────────────────────────┤ │btmp             │ Beacon to fire events at    │ │                 │ failed login of users       │ ├─────────────────┼─────────────────────────────┤ │cert_info        │ Beacon to monitor           │ │                 │ certificate expiration      │ │                 │ dates from files on the     │ │                 │ filesystem.                 │ ├─────────────────┼─────────────────────────────┤ │diskusage        │ Beacon to monitor disk      │ │                 │ usage.                      │ ├─────────────────┼─────────────────────────────┤ │glxinfo          │ Beacon to emit when a       │ │                 │ display is available to a   │ │                 │ linux machine               │ ├─────────────────┼─────────────────────────────┤ │haproxy          │ Watch current connections   │ │                 │ of haproxy server backends. │ ├─────────────────┼─────────────────────────────┤ │inotify          │ Watch files and translate   │ │                 │ the changes into salt       │ │                 │ events                      │ └─────────────────┴─────────────────────────────┘
salt.beacons.adb Beacon to emit adb device state changes for Android devices
salt.beacons.adb.beacon(config) Emit the status of all devices returned by adb
Specify the device states that should emit an event, there will be an event for each device with the event type and device specified.
beacons: adb: - states: - offline - unauthorized - missing - no_devices_event: True - battery_low: 25
salt.beacons.adb.validate(config) Validate the beacon configuration
salt.beacons.aix_account Beacon to fire event when we notice a AIX user is locked due to many failed login attempts.
depends none
salt.beacons.aix_account.beacon(config) Checks for locked accounts due to too many invalid login attempts, 3 or higher.
beacons: aix_account: user: ALL interval: 120
salt.beacons.aix_account.validate(config) Validate the beacon configuration
salt.beacons.avahi_announce Beacon to announce via avahi (zeroconf)
Dependencies • python-avahi
• dbus-python
salt.beacons.avahi_announce.beacon(config) Broadcast values via zeroconf
If the announced values are static, it is advised to set run_once: True (do not poll) on the beacon configuration.
The following are required configuration settings:
• servicetype - The service type to announce
• port - The port of the service to announce
• txt - The TXT record of the service being announced as a dict. Grains can be used to define TXT values using one of following two formats:
• grains.<grain_name>
• grains.<grain_name>[i] where i is an integer representing the index of the grain to use. If the grain is not a list, the index is ignored.
The following are optional configuration settings:
• servicename - Set the name of the service. Will use the hostname from the minion's host grain if this value is not set.
• reset_on_change - If True and there is a change in TXT records detected, it will stop announcing the service and then restart announcing the service. This interruption in service announcement may be desirable if the client relies on changes in the browse records to update its cache of TXT records. Defaults to False.
• reset_wait - The number of seconds to wait after announcement stops announcing and before it restarts announcing in the case where there is a change in TXT records detected and reset_on_change is True.  Defaults to 0.
• copy_grains - If True, Salt will copy the grains passed into the beacon when it backs them up to check for changes on the next iteration.  Normally, instead of copy, it would use straight value assignment. This will allow detection of changes to grains where the grains are modified in-place instead of completely replaced.  In-place grains changes are not currently done in the main Salt code but may be done due to a custom plug-in. Defaults to False.
beacons: avahi_announce: - run_once: True - servicetype: _demo._tcp - port: 1234 - txt: ProdName: grains.productname SerialNo: grains.serialnumber Comments: 'this is a test'
salt.beacons.avahi_announce.validate(config) Validate the beacon configuration
salt.beacons.bonjour_announce Beacon to announce via Bonjour (zeroconf)
salt.beacons.bonjour_announce.beacon(config) Broadcast values via zeroconf
beacons: bonjour_announce: - run_once: True - servicetype: _demo._tcp - port: 1234 - txt: ProdName: grains.productname SerialNo: grains.serialnumber Comments: 'this is a test'
salt.beacons.bonjour_announce.validate(config) Validate the beacon configuration
salt.beacons.btmp Beacon to fire events at failed login of users
Example Configuration # Fire events on all failed logins beacons: btmp: []
# Matching on user name, using a default time range beacons: btmp: - users: gareth: - defaults: time_range: start: '8am' end: '4pm'
# Matching on user name, overriding the default time range beacons: btmp: - users: gareth: time_range: start: '8am' end: '4pm' - defaults: time_range: start: '8am' end: '4pm'
# Matching on group name, overriding the default time range beacons: btmp: - groups: users: time_range: start: '8am' end: '4pm' - defaults: time_range: start: '8am' end: '4pm'
Use Case: Posting Failed Login Events to Slack This can be done using the following reactor SLS:
report-wtmp: runner.salt.cmd: - args: - fun: slack.post_message - channel: mychannel      # Slack channel - from_name: someuser     # Slack user - message: "Failed login from `{{ data.get('user', '') or 'unknown user' }}` on `{{ data['id'] }}`"
Match the event like so in the master config file:
reactor:
- 'salt/beacon/*/btmp/': - salt://reactor/btmp.sls
NOTE: This approach uses the slack execution module directly on the master, and therefore requires that the master has a slack API key in its configuration:
slack: api_key: xoxb-XXXXXXXXXXXX-XXXXXXXXXXXX-XXXXXXXXXXXXXXXXXXXXXXXX
See the slack execution module documentation for more information. While you can use an individual user's API key to post to Slack, a bot user is likely better suited for this. The slack engine documentation has information on how to set up a bot user.
salt.beacons.btmp.beacon(config) Read the last btmp file and return information on the failed logins
salt.beacons.btmp.validate(config) Validate the beacon configuration
salt.beacons.cert_info Beacon to monitor certificate expiration dates from files on the filesystem.
maintainer <devops@eitr.tech>
depends OpenSSL
salt.beacons.cert_info.beacon(config) Monitor the certificate files on the minion.
Specify a notification threshold in days and only emit a beacon if any certificates are expiring within that timeframe or if notify_days equals -1 (always report information).  The default notification threshold is 45 days and can be overridden at the beacon level and at an individual certificate level.
beacons: cert_info: - files: - /etc/pki/tls/certs/mycert.pem - /etc/pki/tls/certs/yourcert.pem: notify_days: 15 - /etc/pki/tls/certs/ourcert.pem - notify_days: 45 - interval: 86400
salt.beacons.cert_info.validate(config) Validate the beacon configuration
salt.beacons.diskusage Beacon to monitor disk usage.
depends python-psutil
salt.beacons.diskusage.beacon(config) Monitor the disk usage of the minion
Specify thresholds for each disk and only emit a beacon if any of them are exceeded.
beacons: diskusage: - /: 63% - /mnt/nfs: 50%
Windows drives must be quoted to avoid yaml syntax errors
beacons: diskusage: -  interval: 120 - 'c:\\': 90% - 'd:\\': 50%
Regular expressions can be used as mount points.
beacons: diskusage: - '^\/(?!home).*$': 90% - '^[a-zA-Z]:\\$': 50%
The first one will match all mounted disks beginning with "/", except /home The second one will match disks from A:to Z:on a Windows system
Note that if a regular expression are evaluated after static mount points, which means that if a regular expression matches another defined mount point, it will override the previously defined threshold.
salt.beacons.diskusage.validate(config) Validate the beacon configuration
salt.beacons.glxinfo Beacon to emit when a display is available to a linux machine
salt.beacons.glxinfo.beacon(config) Emit the status of a connected display to the minion
Mainly this is used to detect when the display fails to connect for whatever reason.
beacons: glxinfo: - user: frank - screen_event: True
salt.beacons.glxinfo.validate(config) Validate the beacon configuration
salt.beacons.haproxy Watch current connections of haproxy server backends.  Fire an event when over a specified threshold.
salt.beacons.haproxy.beacon(config) Check if current number of sessions of a server for a specific haproxy backend is over a defined threshold.
beacons: haproxy: - backends: www-backend: threshold: 45 servers: - web1 - web2 - interval: 120
salt.beacons.haproxy.validate(config) Validate the beacon configuration
salt.beacons.inotify Watch files and translate the changes into salt events
• pyinotify Python module >= 0.9.5
Caution Using generic mask options like open, access, ignored, and closed_nowrite with reactors can easily cause the reactor to loop on itself. To mitigate this behavior, consider setting the disable_during_state_run flag to True in the beacon configuration.
note   The inotify beacon only works on OSes that have inotify kernel support.
salt.beacons.inotify.beacon(config) Watch the configured files
beacons: inotify: - files: /path/to/file/or/dir: mask: - open - create - close_write recurse: True auto_add: True exclude: - /path/to/file/or/dir/exclude1 - /path/to/file/or/dir/exclude2 - /path/to/file/or/dir/regex[a-m]*$: regex: True - coalesce: True
The mask list can contain the following events (the default mask is create, delete, and modify):
• access            - File accessed
• attrib            - File metadata changed
• close_nowrite     - Unwritable file closed
• close_write       - Writable file closed
• create            - File created in watched directory
• delete            - File deleted from watched directory
• delete_self       - Watched file or directory deleted
• modify            - File modified
• moved_from        - File moved out of watched directory
• moved_to          - File moved into watched directory
• move_self         - Watched file moved
• open              - File opened
The mask can also contain the following options:
• dont_follow       - Don't dereference symbolic links
• excl_unlink       - Omit events for children after they have been unlinked
• oneshot           - Remove watch after one event
• onlydir           - Operate only if name is directory
recurse: Recursively watch files in the directory
auto_add: Automatically start watching files that are created in the watched directory
exclude: Exclude directories or files from triggering events in the watched directory.  Can use regex if regex is set to True
coalesce: If this coalescing option is enabled, events are filtered based on their unicity, only unique events are enqueued, doublons are discarded.  An event is unique when the combination of its fields (wd, mask, cookie, name) is unique among events of a same batch. After a batch of events is processed any events are accepted again.  This option is top-level (at the same level as the path) and therefore affects all paths that are being watched. This is due to this option being at the Notifier level in pyinotify.
salt.beacons.inotify.close(config)
salt.beacons.inotify.validate(config) Validate the beacon configuration
salt.beacons.journald A simple beacon to watch journald for specific entries
salt.beacons.journald.beacon(config) The journald beacon allows for the systemd journal to be parsed and linked objects to be turned into events.
This beacons config will return all sshd jornal entries
beacons: journald: - services: sshd: SYSLOG_IDENTIFIER: sshd PRIORITY: 6
salt.beacons.journald.validate(config) Validate the beacon configuration
salt.beacons.junos_rre_keys Junos redundant routing engine beacon.
NOTE: This beacon only works on the Juniper native minion.
Copies salt-minion keys to the backup RE when present
Configure with
beacon: beacons: junos_rre_keys: - interval: 43200
interval above is in seconds, 43200 is recommended (every 12 hours)
salt.beacons.junos_rre_keys.beacon(config)
salt.beacons.load Beacon to emit system load averages
salt.beacons.load.beacon(config) Emit the load averages of this host.
Specify thresholds for each load average and only emit a beacon if any of them are exceeded.
onchangeonly: when onchangeonly is True the beacon will fire events only when the load average pass one threshold.  Otherwise, it will fire an event at each beacon interval.  The default is False.
emitatstartup: when emitatstartup is False the beacon will not fire event when the minion is reload. Applicable only when onchangeonly is True.  The default is True.
beacons: load: - averages: 1m: - 0.0 - 2.0 5m: - 0.0 - 1.5 15m: - 0.1 - 1.0 - emitatstartup: True - onchangeonly: False
salt.beacons.load.validate(config) Validate the beacon configuration
salt.beacons.log_beacon Beacon to fire events at specific log messages.
salt.beacons.log_beacon.beacon(config) Read the log file and return match whole string
beacons: log: - file: <path> - tags: <tag>: regex: <pattern>
NOTE: regex matching is based on the re module
The defined tag is added to the beacon event tag.  This is not the tag in the log.
beacons: log: - file: /var/log/messages #path to log. - tags: goodbye/world: # tag added to beacon event tag. regex: .*good-bye.* # match good-bye string anywhere in the log entry.
salt.beacons.log_beacon.validate(config) Validate the beacon configuration
salt.beacons.memusage Beacon to monitor memory usage.
salt.beacons.memusage.beacon(config) Monitor the memory usage of the minion
Specify thresholds for percent used and only emit a beacon if it is exceeded.
beacons: memusage: - percent: 63%
salt.beacons.memusage.validate(config) Validate the beacon configuration
salt.beacons.napalm_beacon Watch NAPALM functions and fire events on specific triggers New in version 2018.3.0.
NOTE: The NAPALM beacon only works only when running under a regular Minion or a Proxy Minion, managed via NAPALM.  Check the documentation for the NAPALM proxy module.
The configuration accepts a list of Salt functions to be invoked, and the corresponding output hierarchy that should be matched against. To invoke a function with certain arguments, they can be specified using the _args key, or _kwargs for more specific key-value arguments.
The match structure follows the output hierarchy of the NAPALM functions, under the out key.
For example, the following is normal structure returned by the ntp.stats execution function:
{ "comment": "", "result": true, "out": [ { "referenceid": ".GPSs.", "remote": "172.17.17.1", "synchronized": true, "reachability": 377, "offset": 0.461, "when": "860", "delay": 143.606, "hostpoll": 1024, "stratum": 1, "jitter": 0.027, "type": "-" }, { "referenceid": ".INIT.", "remote": "172.17.17.2", "synchronized": false, "reachability": 0, "offset": 0.0, "when": "-", "delay": 0.0, "hostpoll": 1024, "stratum": 16, "jitter": 4000.0, "type": "-" } ] }
In order to fire events when the synchronization is lost with one of the NTP peers, e.g., 172.17.17.2, we can match it explicitly as:
ntp.stats: remote: 172.17.17.2 synchronized: false
There is one single nesting level, as the output of ntp.stats is just a list of dictionaries, and this beacon will compare each dictionary from the list with the structure examplified above.
NOTE: When we want to match on any element at a certain level, we can configure * to match anything.
Considering a more complex structure consisting on multiple nested levels, e.g., the output of the bgp.neighbors execution function, to check when any neighbor from the global routing table is down, the match structure would have the format:
bgp.neighbors: global: '*': up: false
The match structure above will match any BGP neighbor, with any network (* matches any AS number), under the global VRF.  In other words, this beacon will push an event on the Salt bus when there's a BGP neighbor down.
The right operand can also accept mathematical operations (i.e., <, <=, !=, >, >= etc.) when comparing numerical values.
Configuration Example:
beacons: napalm: - net.interfaces: # fire events when any interfaces is down '*': is_up: false - net.interfaces: # fire events only when the xe-0/0/0 interface is down 'xe-0/0/0': is_up: false - ntp.stats: # fire when there's any NTP peer unsynchornized synchronized: false - ntp.stats: # fire only when the synchronization # with with the 172.17.17.2 NTP server is lost _args: - 172.17.17.2 synchronized: false - ntp.stats: # fire only when there's a NTP peer with # synchronization stratum > 5 stratum: '> 5'
Event structure example:
{ "_stamp": "2017-09-05T09:51:09.377202", "args": [], "data": { "comment": "", "out": [ { "delay": 0.0, "hostpoll": 1024, "jitter": 4000.0, "offset": 0.0, "reachability": 0, "referenceid": ".INIT.", "remote": "172.17.17.1", "stratum": 16, "synchronized": false, "type": "-", "when": "-" } ], "result": true }, "fun": "ntp.stats", "id": "edge01.bjm01", "kwargs": {}, "match": { "stratum": "> 5" } }
The event examplified above has been fired when the device identified by the Minion id edge01.bjm01 has been synchronized with a NTP server at a stratum level greater than 5.
salt.beacons.napalm_beacon.beacon(config) Watch napalm function and fire events.
salt.beacons.napalm_beacon.validate(config) Validate the beacon configuration.
salt.beacons.network_info Beacon to monitor statistics from ethernet adapters
salt.beacons.network_info.beacon(config) Emit the network statistics of this host.
Specify thresholds for each network stat and only emit a beacon if any of them are exceeded.
Emit beacon when any values are equal to configured values.
beacons: network_info: - interfaces: eth0: type: equal bytes_sent: 100000 bytes_recv: 100000 packets_sent: 100000 packets_recv: 100000 errin: 100 errout: 100 dropin: 100 dropout: 100
Emit beacon when any values are greater than configured values.
beacons: network_info: - interfaces: eth0: type: greater bytes_sent: 100000 bytes_recv: 100000 packets_sent: 100000 packets_recv: 100000 errin: 100 errout: 100 dropin: 100 dropout: 100
salt.beacons.network_info.validate(config) Validate the beacon configuration
salt.beacons.network_settings Beacon to monitor network adapter setting changes on Linux
class salt.beacons.network_settings.Hashabledict Helper class that implements a hash function for a dictionary
salt.beacons.network_settings.beacon(config) Watch for changes on network settings
By default, the beacon will emit when there is a value change on one of the settings on watch. The config also support the onvalue parameter for each setting, which instruct the beacon to only emit if the setting changed to the value defined.
beacons: network_settings: - interfaces: eth0: ipaddr: promiscuity: onvalue: 1 eth1: linkmode:
The config above will check for value changes on eth0 ipaddr and eth1 linkmode. It will also emit if the promiscuity value changes to 1.
Beacon items can use the * wildcard to make a definition apply to several interfaces. For example an eth* would apply to all ethernet interfaces.
Setting the argument coalesce = True will combine all the beacon results on a single event.  The example below shows how to trigger coalesced results:
beacons: network_settings: - coalesce: True - interfaces: eth0: ipaddr: promiscuity:
salt.beacons.network_settings.validate(config) Validate the beacon configuration
salt.beacons.pkg Watch for pkgs that have upgrades, then fire an event.
salt.beacons.pkg.beacon(config) Check if installed packages are the latest versions and fire an event for those that have upgrades.
beacons: pkg: - pkgs: - zsh - apache2 - refresh: True
salt.beacons.pkg.validate(config) Validate the beacon configuration
salt.beacons.proxy_example Example beacon to use with salt-proxy
beacons: proxy_example: endpoint: beacon
salt.beacons.proxy_example.beacon(config) Called several times each second https://docs.saltproject.io/en/latest/topics/beacons/#the-beacon-function
beacons: proxy_example: - endpoint: beacon
salt.beacons.proxy_example.validate(config) Validate the beacon configuration
salt.beacons.ps Send events covering process status
salt.beacons.ps.beacon(config) Scan for processes and fire events
beacons: ps: - processes: salt-master: running mysql: stopped
The config above sets up beacons to check that processes are running or stopped.
salt.beacons.ps.validate(config) Validate the beacon configuration
salt.beacons.salt_monitor A beacon to execute salt execution module functions. This beacon will fire only if the return data is "truthy".  The function return, funtion name and args and/or kwargs, will be passed as data in the event.
The configuration can accept a list of salt functions to execute every interval.  Make sure to allot enough time via 'interval' key to allow all salt functions to execute.  The salt functions will be executed sequentially.
The elements in list of functions can be either a simple string (with no arguments) or a dictionary with a single key being the salt execution module and sub keys indicating args and / or kwargs.
See example config below.
beacons: salt_monitor: - salt_fun: - slsutil.renderer: args: - salt://states/apache.sls kwargs: - default_renderer: jinja - test.ping - interval: 3600 # seconds
salt.beacons.salt_monitor.beacon(config)
salt.beacons.salt_monitor.validate(config)
salt.beacons.salt_proxy Beacon to manage and report the status of one or more salt proxy processes
New in version 2015.8.3.
salt.beacons.salt_proxy.beacon(config) Handle configured proxies
salt.beacons.salt_proxy.validate(config) Validate the beacon configuration
salt.beacons.sensehat module Monitor temperature, humidity and pressure using the SenseHat of a Raspberry Pi New in version 2017.7.0.
maintainer Benedikt Werner <1benediktwerner@gmail.com>
depends sense_hat Python module
salt.beacons.sensehat.beacon(config) Monitor the temperature, humidity and pressure using the SenseHat sensors.
You can either specify a threshold for each value and only emit a beacon if it is exceeded or define a range and emit a beacon when the value is out of range.
Units: * humidity:                     percent * temperature: degrees Celsius * temperature_from_pressure:    degrees Celsius * pressure:                     Millibars
beacons: sensehat: - sensors: humidity: 70% temperature: [20, 40] temperature_from_pressure: 40 pressure: 1500
salt.beacons.sensehat.validate(config) Validate the beacon configuration
salt.beacons.service Send events covering service status
salt.beacons.service.beacon(config) Scan for the configured services and fire events
beacons: service: - services: salt-master: {} mysql: {}
The config above sets up beacons to check for the salt-master and mysql services.
The config also supports two other parameters for each service: