neulab/tldr huggingface dataset:
salt.modules.trafficserver.restart_cluster() Restart the traffic_manager process and the traffic_server process on all the nodes in a cluster.
salt '*' trafficserver.restart_cluster
salt.modules.trafficserver.restart_local(drain=False) Restart the traffic_manager and traffic_server processes on the local node.
salt '*' trafficserver.restart_local salt '*' trafficserver.restart_local drain=True
salt.modules.trafficserver.set_config(variable, value) Set the value of a Traffic Server configuration variable.
variable Name of a Traffic Server configuration variable.
value  The new value to set.
salt '*' trafficserver.set_config proxy.config.http.keep_alive_post_out 0
salt.modules.trafficserver.shutdown() Shut down Traffic Server on the local node.
salt '*' trafficserver.shutdown
salt.modules.trafficserver.startup() Start Traffic Server on the local node.
salt '*' trafficserver.start
salt.modules.trafficserver.status() Show the current proxy server status, indicating if we’re running or not.
salt '*' trafficserver.status
salt.modules.trafficserver.zero_cluster() Reset performance statistics to zero across the cluster.
salt '*' trafficserver.zero_cluster
salt.modules.trafficserver.zero_node() Reset performance statistics to zero on the local node.
salt.modules.transactional_update module Transactional update New in version 3004.
A transactional system, like MicroOS, can present some challenges when the user decided to manage it via Salt.
MicroOS provide a read-only rootfs and a tool, transactional-update, that takes care of the management of the system (updating, upgrading, installation or reboot, among others) in an atomic way.
Atomicity is the main feature of MicroOS, and to guarantee this property, this model leverages snapper, zypper, btrfs and overlayfs to create snapshots that will be updated independently of the currently running system, and that are activated after the reboot.  This implies, for example, that some changes made on the system are not visible until the next reboot, as those changes are living in a different snapshot of the file system.
This model presents a lot of problems with the traditional Salt model, where the inspections (like 'is this package installed?') are executed in order to determine if a subsequent action is required (like 'install this package').
Lets consider this use case, to see how it works on a traditional system, and in a transactional system:
1. Check if apache is installed
2. If it is not installed, install it
3. Check that a vhost is configured for apache
4. Make sure that apache2.service is enabled
5. If the configuration changes, restart apache2.service
In the traditional system everything will work as expected.  The system can see if the package is present or not, install it if it isn't, and a re-check will shows that is already present.  The same will happen to the configuration file in /etc/apache2, that will be available as soon the package gets installed.  Salt can inspect the current form of this file, and add the missing bits if required.  Salt can annotate that a change is present, and restart the service.
In a transactional system we will have multiple issues.  The first one is that Salt can only see the content of the snapshot where the system booted from.  Later snapshots may contain different content, including the presence of apache.  If Salt decides to install apache calling zypper, it will fail, as this will try to write into the read-only rootfs.  Even if Salt would call transactional-update pkg install, the package would only be present in the new transaction (snapshot), and will not be found in the currently running system when later Salt tries to validate the presence of the package in the current one.
Any change in /etc alone will have also problems, as the changes will be alive in a different overlay, only visible after the reboot.  And, finally, the service can only be enabled and restarted if the service file is already present in the current /etc.
General strategy transactional-update is the reference tool used for the administration of transactional systems.  Newer versions of this tool support the execution of random commands in the new transaction, the continuation of a transaction, the automatic detection of changes in new transactions and the merge of /etc overlays.
Continue a transaction One prerequisite already present is the support for branching from a different snapshot than the current one in snapper.
With this feature we can represent in transactional-update the action of creating a transaction snapshot based on one that is planned to be the active one after the reboot.  This feature removes a lot of user complains (like, for example, losing changes that are stored in a transaction not yet activated), but also provide a more simple model to work with.
So, for example, if the user have this scenario:
+-----+  *=====*  +--V--+ --| T.1 |--| T.2 |--| T.3 | +-----+  *=====*  +--A--+
where T.2 is the current active one, and T.3 is an snapshot generated from T.2 with a new package (apache2), and is marked to be the active after the reboot.
Previously, if the user (that is still on T.2) created a new transaction, maybe for adding a new package (tomcat, for example), the new T.4 will be based on the content of T.2 again, and not T.3, so the new T.4 will have lost the changes of T.3 (i.e. apache2 will not be present in T.4).
With the --continue parameter, transactional-update will create T.4 based on T.3, and nothing will be lost.
Command execution inside a new transaction With transactional-update run we will create a new transaction based on the current one (T.2), where we can send interactive commands that can modify the new transaction, and as commented, with transactional-update --continue run, we will create a new transaction based on the last created (T.3)
The run command can execute any application inside the new transaction namespace.  This module uses this feature to execute the different Salt execution modules, via call(). Or even the full salt-thin or salt-call via sls(), apply(), single() or highstate.
transactional-update will drop empty snapshots The option --drop-if-no-change is used to detect whether there is any change in the file system on the read-only subvolume of the new transaction will be added.  If a change is present, the new transaction will remain, if not it will be discarded.
transactional-update --continue --drop-if-no-change run zypper in apache2"
If we are in the scenario described before, apache2 is already present in T.3.  In this case a new transaction, T.4, will be created based on T.3, zypper will detect that the package is already present and no change will be produced on T.4.  At the end of the execution, transactional-update will validate that T.3 and T.4 are equivalent and T.4 will be discarded.
If the command is:
transactional-update --continue --drop-if-no-change run zypper in tomcat
the new T.4 will be indeed different from T.3, and will remain after the transaction is closed.
With this feature, every time that we call any function of this execution module, we will minimize the amount of transaction, while maintaining the idempotence so some operations.
Report for pending transaction A change in the system will create a new transaction, that needs to be activated via a reboot.  With pending_transaction() we can check if a reboot is needed.  We can execute the reboot using the reboot() function, that will follow the plan established by the functions of the rebootmgr execution module.
/etc overlay merge when no new transaction is created In a transactional model, /etc is an overlay file system.  Changes done during the update are only present in the new transaction, and so will only be available after the reboot.  Or worse, if the transaction gets dropped, because there is no change in the rootfs, the changes in /etc will be dropped too!.  This is designed like that in order to make the configuration files for the new package available only when new package is also available to the user.  So, after the reboot.
This makes sense for the case when, for example, apache2 is not present in the current transaction, but we installed it.  The new snapshot contains the apache2 service, and the configuration files in /etc will be accessible only after the reboot.
But this model presents an issue.  If we use transactional-update --continue --drop-if-no-change run <command>, where <command> does not make any change in the read-only subvolume, but only in /etc (which is also read-write in the running system), the new overlay with the changes in /etc will be dropped together with the transaction.
To fix this, transactional-update will detect that when no change has been made on the read-only subvolume, but done in the overlay, the transaction will be dropped and the changes in the overlay will be merged back into /etc overlay of the current transaction.
Using the execution module With this module we can create states that leverage Salt into this kind of systems:
# Install apache (low-level API) salt-call transactional_update.pkg_install apache2
# We can call any execution module salt-call transactional_update.call pkg.install apache2
# Or via a state salt-call transactional_update.single pkg.installed name=apache2
# We can also execute a zypper directly salt-call transactional_update run "zypper in apache2" snapshot="continue"
# We can reuse SLS states salt-call transactional_update.apply install_and_configure_apache
# Or apply the full highstate salt-call transactional_update.highstate
# Is there any change done in the system? salt-call transactional_update pending_transaction
# If so, reboot via rebootmgr salt-call transactional_update reboot
# We can enable the service salt-call service.enable apache2
# If apache2 is available, this will work too salt-call service.restart apache2
Fixing some expectations This module alone is an improvement over the current state, but is easy to see some limitations and problems:
Is not a fully transparent approach The user needs to know if the system is transactional or not, as not everything can be expressed inside a transaction (for example, restarting a service inside transaction is not allowed).
Two step for service restart In the apache2` example from the beginning we can observe the biggest drawback.  If the package ``apache2 is missing, the new module will create a new transaction, will execute pkg.install inside the transaction (creating the salt-thin, moving it inside and delegating the execution to transactional-update CLI as part of the full state).  Inside the transaction we can do too the required changes in /etc for adding the new vhost, and we can enable the service via systemctl inside the same transaction.
At this point we will not merge the /etc overlay into the current one, and we expect from the user call the reboot function inside this module, in order to activate the new transaction and start the apache2 service.
In the case that the package is already there, but the configuration for the vhost is required, the new transaction will be dropped and the /etc overlay will be visible in the live system.  Then from outside the transaction, via a different call to Salt, we can command a restart of the apache2 service.
We can see that in both cases we break the user expectation, where a change on the configuration will trigger automatically the restart of the associated service.  In a transactional scenario we need two different steps: or a reboot, or a restart from outside of the transaction.
maintainer Alberto Planas <aplanas@suse.com>
class salt.modules.transactional_update.TransactionalUpdateHighstate(opts, pillar=None, wrapper=None, fsclient=None)
salt.modules.transactional_update.apply_(mods=None, **kwargs) Apply an state inside a transaction.
This function will call transactional_update.highstate or transactional_update.sls based on the arguments passed to this function. It exists as a more intuitive way of applying states.
activate_transaction If at the end of the transaction there is a pending activation (i.e there is a new snaphot in the system), a new reboot will be scheduled (default False)
salt microos transactional_update.apply salt microos transactional_update.apply stuff salt microos transactional_update.apply stuff pillar='{"foo": "bar"}' salt microos transactional_update.apply stuff activate_transaction=True
salt.modules.transactional_update.bootloader(self_update=False, snapshot=None) Reinstall the bootloader
Same as grub.cfg, but will also rewrite the bootloader itself.
self_update Check for newer transactional-update versions.
snapshot Use the given snapshot or, if no number is given, the current default snapshot as a base for the next snapshot. Use "continue" to indicate the last snapshot done.
salt microos transactional_update bootloader snapshot="continue"
salt.modules.transactional_update.call(function, *args, **kwargs) Executes a Salt function inside a transaction.
salt microos transactional_update.call test.ping salt microos transactional_update.call ssh.set_auth_key user key=mykey salt microos transactional_update.call pkg.install emacs activate_transaction=True
salt.modules.transactional_update.cleanup(self_update=False) Run both cleanup-snapshots and cleanup-overlays.
Identical to calling both cleanup-snapshots and cleanup-overlays.
salt microos transactional_update cleanup
salt.modules.transactional_update.cleanup_overlays(self_update=False) Remove unused overlay layers.
Removes all unreferenced (and thus unused) /etc overlay directories in /var/lib/overlay.
salt microos transactional_update cleanup_overlays
salt.modules.transactional_update.cleanup_snapshots(self_update=False) Mark unused snapshots for snapper removal.
If the current root filesystem is identical to the active root filesystem (means after a reboot, before transactional-update creates a new snapshot with updates), all old snapshots without a cleanup algorithm get a cleanup algorithm set. This is to make sure, that old snapshots will be deleted by snapper. See the section about cleanup algorithms in snapper(8).
salt microos transactional_update cleanup_snapshots
salt.modules.transactional_update.dup(self_update=False, snapshot=None) Call 'zypper dup'
If new updates are available, a new snapshot is created and zypper dup --no-allow-vendor-change is used to update the snapshot. Afterwards, the snapshot is activated and will be used as the new root filesystem during next boot.
salt microos transactional_update dup snapshot="continue"
salt.modules.transactional_update.grub_cfg(self_update=False, snapshot=None) Regenerate grub.cfg
grub2-mkconfig(8) is called to create a new /boot/grub2/grub.cfg configuration file for the bootloader.
salt microos transactional_update grub_cfg snapshot="continue"
salt.modules.transactional_update.highstate(activate_transaction=False, queue=False, **kwargs) Retrieve the state data from the salt master for this minion and execute it inside a transaction.
queue  Instead of failing immediately when another state run is in progress, queue the new state run to begin running once the other has finished.
This option starts a new thread for each queued state run, so use this option sparingly. (Default: False)
salt microos transactional_update.highstate salt microos transactional_update.highstate pillar='{"foo": "bar"}' salt microos transactional_update.highstate activate_transaction=True
salt.modules.transactional_update.in_transaction() Check if Salt is executing while in a transaction
salt microos transactional_update in_transaction
salt.modules.transactional_update.initrd(self_update=False, snapshot=None) Regenerate initrd
A new initrd is created in a snapshot.
salt microos transactional_update initrd snapshot="continue"
salt.modules.transactional_update.kdump(self_update=False, snapshot=None) Regenerate kdump initrd
A new initrd for kdump is created in a snapshot.
salt microos transactional_update kdump snapshot="continue"
salt.modules.transactional_update.migration(self_update=False, snapshot=None) Updates systems registered via SCC / SMT
On systems which are registered against the SUSE Customer Center (SCC) or SMT, a migration to a new version of the installed products can be made with this option.
salt microos transactional_update migration snapshot="continue"
salt.modules.transactional_update.patch(self_update=False, snapshot=None) Call 'zypper patch'
If new updates are available, a new snapshot is created and zypper patch is used to update the snapshot. Afterwards, the snapshot is activated and will be used as the new root filesystem during next boot.
salt microos transactional_update patch snapshot="continue"
salt.modules.transactional_update.pending_transaction() Check if there is a pending transaction
salt microos transactional_update pending_transaction
salt.modules.transactional_update.pkg_install(pkg=None, pkgs=None, args=None, self_update=False, snapshot=None) Install individual packages
Installs additional software. See the install description in the "Package Management Commands" section of zypper's man page for all available arguments.
pkg    Package name to install
pkgs   List of packages names to install
args   String or list of extra parameters for zypper
salt microos transactional_update pkg_install pkg=emacs snapshot="continue"
salt.modules.transactional_update.pkg_remove(pkg=None, pkgs=None, args=None, self_update=False, snapshot=None) Remove individual packages
Removes installed software. See the remove description in the "Package Management Commands" section of zypper's man page for all available arguments.
salt microos transactional_update pkg_remove pkg=vim snapshot="continue"
salt.modules.transactional_update.pkg_update(pkg=None, pkgs=None, args=None, self_update=False, snapshot=None) Updates individual packages
Update selected software. See the update description in the "Update Management Commands" section of zypper's man page for all available arguments.
salt microos transactional_update pkg_update pkg=emacs snapshot="continue"
salt.modules.transactional_update.reboot(self_update=False) Reboot after update
Trigger a reboot after updating the system.
Several different reboot methods are supported, configurable via the REBOOT_METHOD configuration option in transactional-update.conf(5). By default rebootmgrd(8) will be used to reboot the system according to the configured policies if the service is running, otherwise systemctl reboot will be called.
salt microos transactional_update reboot
salt.modules.transactional_update.rollback(snapshot=None) Set the current, given or last working snapshot as default snapshot
Sets the default root file system. On a read-only system the root file system is set directly using btrfs. On read-write systems snapper(8) rollback is called.
If no snapshot number is given, the current root file system is set as the new default root file system. Otherwise number can either be a snapshot number (as displayed by snapper list) or the word last. last will try to reset to the latest working snapshot.
snapshot Use the given snapshot or, if no number is given, the current default snapshot as a base for the next snapshot. Use "last" to indicate the last working snapshot done.
salt microos transactional_update rollback
salt.modules.transactional_update.run(command, self_update=False, snapshot=None) Run a command in a new snapshot
Execute the command inside a new snapshot. By default this snaphot will remain, but if --drop-if-no-chage is set, the new snapshot will be dropped if there is no change in the file system.
command Command with parameters that will be executed (as string or array)
salt microos transactional_update run "mkdir /tmp/dir" snapshot="continue"
salt.modules.transactional_update.single(fun, name, test=None, activate_transaction=False, queue=False, **kwargs) Execute a single state function with the named kwargs, returns False if insufficient data is sent to the command
salt microos transactional_update.single pkg.installed name=emacs salt microos transactional_update.single pkg.installed name=emacs activate_transaction=True
salt.modules.transactional_update.sls(mods, saltenv='base', test=None, exclude=None, activate_transaction=False, queue=False, **kwargs) Execute the states in one or more SLS files inside a transaction.
salt microos transactional_update.sls stuff pillar='{"foo": "bar"}' salt microos transactional_update.sls stuff activate_transaction=True
salt.modules.transactional_update.transactional() Check if the system is a transactional system
salt microos transactional_update transactional
salt.modules.transactional_update.up(self_update=False, snapshot=None) Call 'zypper up'
If new updates are available, a new snapshot is created and zypper up is used to update the snapshot. Afterwards, the snapshot is activated and will be used as the new root filesystem during next boot.
salt microos transactional_update up snapshot="continue"
salt.modules.travisci Commands for working with travisci.
depends pyOpenSSL >= 16.0.0
salt.modules.travisci.verify_webhook(signature, body) Verify the webhook signature from travisci
signature The signature header from the webhook header
body   The full payload body from the webhook post
NOTE: The body needs to be the urlencoded version of the body.
salt '*' travisci.verify_webhook 'M6NucCX5722bxisQs7e...' 'payload=%7B%22id%22%3A183791261%2C%22repository...'
salt.modules.tuned Interface to Red Hat tuned-adm module
maintainer Syed Ali <alicsyed@gmail.com>
depends tuned-adm
salt.modules.tuned.active() Return current active profile
salt '*' tuned.active
salt.modules.tuned.list_() List the profiles available
salt '*' tuned.list
salt.modules.tuned.off() Turn off all profiles
salt '*' tuned.off
salt.modules.tuned.profile(profile_name) Activate specified profile
salt '*' tuned.profile virtual-guest
salt.modules.twilio_notify Module for notifications via Twilio
• twilio python module
configuration Configure this module by specifying the name of a configuration profile in the minion config, minion pillar, or master config (with pillar_opts set to True).
my-twilio-account: twilio.account_sid: AC32a3c83990934481addd5ce1659f04d2 twilio.auth_token: mytoken
salt.modules.twilio_notify.send_sms(profile, body, to, from_) Send an sms
CLI Example: twilio.send_sms my-twilio-account 'Test sms' '+18019999999' '+18011111111'
salt.modules.udev Manage and query udev info
salt.modules.udev.env(dev) Return all environment variables udev has for dev
salt '*' udev.env /dev/sda salt '*' udev.env /sys/class/net/eth0
salt.modules.udev.exportdb() Return all the udev database
salt '*' udev.exportdb
salt.modules.udev.info(dev) Extract all info delivered by udevadm
salt '*' udev.info /dev/sda salt '*' udev.info /sys/class/net/eth0
salt.modules.udev.links(dev) Return all udev-created device symlinks
salt '*' udev.links /dev/sda salt '*' udev.links /sys/class/net/eth0
salt.modules.udev.name(dev) Return the actual dev name(s?) according to udev for dev
salt '*' udev.dev /dev/sda salt '*' udev.dev /sys/class/net/eth0
salt.modules.udev.path(dev) Return the physical device path(s?) according to udev for dev
salt '*' udev.path /dev/sda salt '*' udev.path /sys/class/net/eth0
salt.modules.upstart_service Module for the management of upstart systems. The Upstart system only supports service starting, stopping and restarting.
Currently (as of Ubuntu 12.04) there is no tool available to disable Upstart services (like update-rc.d). This[1] is the recommended way to disable an Upstart service. So we assume that all Upstart services that have not been disabled in this manner are enabled.
But this is broken because we do not check to see that the dependent services are enabled. Otherwise we would have to do something like parse the output of "initctl show-config" to determine if all service dependencies are enabled to start on boot. For example, see the "start on" condition for the lightdm service below[2]. And this would be too hard. So we wait until the upstart developers have solved this problem. :) This is to say that an Upstart service that is enabled may not really be enabled.
Also, when an Upstart service is enabled, should the dependent services be enabled too? Probably not. But there should be a notice about this, at least.
[1] http://upstart.ubuntu.com/cookbook/#disabling-a-job-from-automatically-starting
[2] example upstart configuration file:
lightdm emits login-session-start emits desktop-session-start emits desktop-shutdown start on ((((filesystem and runlevel [!06]) and started dbus) and (drm-device-added card0 PRIMARY_DEVICE_FOR_DISPLAY=1 or stopped udev-fallback-graphics)) or runlevel PREVLEVEL=S) stop on runlevel [016]
WARNING: This module should not be used on Red Hat systems. For these, the rh_service module should be used, as it supports the hybrid upstart/sysvinit system used in RHEL/CentOS 6.
salt.modules.upstart_service.available(name) Returns True if the specified service is available, otherwise returns False.
salt.modules.upstart_service.disable(name, **kwargs) Disable the named service from starting on boot
salt.modules.upstart_service.disabled(name) Check to see if the named service is disabled to start on boot
salt.modules.upstart_service.enable(name, **kwargs) Enable the named service to start at boot
salt.modules.upstart_service.enabled(name, **kwargs) Check to see if the named service is enabled to start on boot
salt.modules.upstart_service.force_reload(name) Force-reload the named service
salt.modules.upstart_service.full_restart(name) Do a full restart (stop/start) of the named service
salt '*' service.full_restart <service name>
salt.modules.upstart_service.get_all() Return all installed services
salt.modules.upstart_service.get_disabled() Return the disabled services
salt.modules.upstart_service.get_enabled() Return the enabled services
salt.modules.upstart_service.missing(name) The inverse of service.available.  Returns True if the specified service is not available, otherwise returns False.
salt.modules.upstart_service.reload_(name) Reload the named service
salt.modules.upstart_service.restart(name) Restart the named service
salt.modules.upstart_service.start(name) Start the specified service
salt.modules.upstart_service.status(name, sig=None) Return the status for a service.  If the name contains globbing, a dict mapping service name to True/False values is returned.
salt.modules.upstart_service.stop(name) Stop the specified service
salt.modules.uptime Wrapper around uptime API salt.modules.uptime.check_exists(name) Check if a given URL is in being monitored by uptime
salt '*' uptime.check_exists http://example.org
salt.modules.uptime.checks_list() List URL checked by uptime
salt '*' uptime.checks_list
salt.modules.uptime.create(name, **params) Create a check on a given URL.
Additional parameters can be used and are passed to API (for example interval, maxTime, etc). See the documentation https://github.com/fzaninotto/uptime for a full list of the parameters.
salt '*' uptime.create http://example.org
salt.modules.uptime.delete(name) Delete a check on a given URL
salt '*' uptime.delete http://example.org
salt.modules.useradd Manage users with the useradd command
salt.modules.useradd.add(name, uid=None, gid=None, groups=None, home=None, shell=None, unique=True, system=False, fullname='', roomnumber='', workphone='', homephone='', other='', createhome=True, loginclass=None, nologinit=False, root=None, usergroup=None) Add a user to the minion
name   Username LOGIN to add
uid    User ID of the new account
gid    Name or ID of the primary group of the new account
groups List of supplementary groups of the new account
home   Home directory of the new account
shell  Login shell of the new account
unique If not True, the user account can have a non-unique UID
fullname GECOS field for the full name
roomnumber GECOS field for the room number
workphone GECOS field for the work phone
homephone GECOS field for the home phone
other  GECOS field for other information
createhome Create the user's home directory
loginclass Login class for the new account (OpenBSD)
nologinit Do not add the user to the lastlog and faillog databases
usergroup Create and add the user to a new primary group of the same name
salt.modules.useradd.chfullname(name, fullname, root=None) Change the user's Full Name
salt.modules.useradd.chgid(name, gid, root=None) Change the default group of the user
gid    Force use GID as new primary group
salt.modules.useradd.chgroups(name, groups, append=False, root=None) Change the groups to which this user belongs
groups Groups to set for the user
append False If True, append the specified group(s). Otherwise, this function will replace the user's groups with the specified group(s).
salt '*' user.chgroups foo wheel,root salt '*' user.chgroups foo wheel,root append=True
salt.modules.useradd.chhome(name, home, persist=False, root=None) Change the home directory of the user, pass True for persist to move files to the new home directory if the old home directory exist.
home   New home directory for the user account
persist Move contents of the home directory to the new location
salt.modules.useradd.chhomephone(name, homephone, root=None) Change the user's Home Phone
salt '*' user.chhomephone foo 7735551234
salt.modules.useradd.chloginclass(name, loginclass, root=None) Change the default login class of the user
loginclass Login class for the new account
NOTE: This function only applies to OpenBSD systems.
salt.modules.useradd.chother(name, other, root=None) Change the user's other GECOS attribute
salt '*' user.chother foobar
salt.modules.useradd.chroomnumber(name, roomnumber, root=None) Change the user's Room Number
salt.modules.useradd.chshell(name, shell, root=None) Change the default shell of the user
shell  New login shell for the user account
salt.modules.useradd.chuid(name, uid, root=None) Change the uid for a named user
uid    New UID for the user account
salt.modules.useradd.chworkphone(name, workphone, root=None) Change the user's Work Phone
salt '*' user.chworkphone foo 7735550123
salt.modules.useradd.delete(name, remove=False, force=False, root=None) Remove a user from the minion
name   Username to delete
remove Remove home directory and mail spool
force  Force some actions that would fail otherwise
salt.modules.useradd.get_loginclass(name) Get the login class of the user
name   User to get the information
salt.modules.useradd.getent(refresh=False, root=None) Return the list of all info for all users
refresh Force a refresh of user information
salt.modules.useradd.info(name, root=None) Return user information
salt.modules.useradd.list_groups(name) Return a list of groups the named user belongs to
salt.modules.useradd.list_users(root=None) Return a list of all users
salt.modules.useradd.primary_group(name) Return the primary group of the named user
salt.modules.useradd.rename(name, new_name, root=None) Change the username for a named user
new_name New value of the login name
salt.modules.uwsgi uWSGI stats server https://uwsgi-docs.readthedocs.io/en/latest/StatsServer.html
maintainer Peter Baumgartner <pete@lincolnloop.com>
salt.modules.uwsgi.stats(socket) Return the data from uwsgi --connect-and-read as a dictionary.
socket The socket the uWSGI stats server is listening on
salt '*' uwsgi.stats /var/run/mystatsserver.sock
salt '*' uwsgi.stats 127.0.0.1:5050
salt.modules.vagrant Work with virtual machines managed by Vagrant.
Mapping between a Salt node id and the Vagrant machine name (and the path to the Vagrantfile where it is defined) is stored in a Salt sdb database on the Vagrant host (minion) machine.  In order to use this module, sdb must be configured. An SQLite database is the recommended storage method. The URI used for the sdb lookup is "sdb://vagrant_sdb_data".
requirements:
• the VM host machine must have salt-minion, Vagrant and a vm provider installed.
• the VM host must have a valid definition for sdb://vagrant_sdb_data Configuration example:
# file /etc/salt/minion.d/vagrant_sdb.conf vagrant_sdb_data: driver: sqlite3 database: /var/cache/salt/vagrant.sqlite table: sdb create_table: True
salt.modules.vagrant.destroy(name) Destroy and delete a virtual machine. (vagrant destroy -f)
This also removes the salt_id name defined by vagrant.init.
salt <host> vagrant.destroy <salt_id>
salt.modules.vagrant.get_machine_id(machine, cwd) returns the salt_id name of the Vagrant VM
• machine -- the Vagrant machine name
• cwd -- the path to Vagrantfile
Returns salt_id name
salt.modules.vagrant.get_ssh_config(name, network_mask='', get_private_key=False) Retrieve hints of how you might connect to a Vagrant VM.
• name -- the salt_id of the machine
• network_mask -- a CIDR mask to search for the VM's address
• get_private_key -- (default: False) return the key used for ssh login
Returns a dict of ssh login information for the VM
salt <host> vagrant.get_ssh_config <salt_id> salt my_laptop vagrant.get_ssh_config quail1 network_mask=10.0.0.0/8 get_private_key=True
The returned dictionary contains:
• key_filename:  the name of the private key file on the VM host computer
• ssh_username:  the username to be used to log in to the VM
• ssh_host:  the IP address used to log in to the VM.  (This will usually be 127.0.0.1)
• ssh_port:  the TCP port used to log in to the VM.  (This will often be 2222)
• [ip_address:]  (if network_mask is defined. see below)
• [private_key:]  (if get_private_key is True) the private key for ssh_username
About network_mask:
Vagrant usually uses a redirected TCP port on its host computer to log in to a VM using ssh.  This redirected port and its IP address are "ssh_port" and "ssh_host".  The ssh_host is usually the localhost (127.0.0.1).  This makes it impossible for a third machine (such as a salt-cloud master) to contact the VM unless the VM has another network interface defined.  You will usually want a bridged network defined by having a config.vm.network "public_network" statement in your Vagrantfile.
The IP address of the bridged adapter will typically be assigned by DHCP and unknown to you, but you should be able to determine what IP network the address will be chosen from.  If you enter a CIDR network mask, Salt will attempt to find the VM's address for you.  The host machine will send an "ifconfig" command to the VM (using ssh to ssh_host:ssh_port) and return the IP address of the first interface it can find which matches your mask.
salt.modules.vagrant.get_vm_info(name) get the information for a VM.
Parameters name -- salt_id name
Returns dictionary of {'machine': x, 'cwd': y, ...}.
salt.modules.vagrant.init(name, cwd=None, machine='', runas=None, start=False, vagrant_provider='', vm=None) Initialize a new Vagrant VM.
This inputs all the information needed to start a Vagrant VM. These settings are stored in a Salt sdb database on the Vagrant host minion and used to start, control, and query the guest VMs. The salt_id assigned here is the key field for that database and must be unique.
• name -- The salt_id name you will use to control this VM
• cwd -- The path to the directory where the Vagrantfile is located
• machine -- The machine name in the Vagrantfile. If blank, the primary machine will be used.
• runas -- The username on the host who owns the Vagrant work files.
• start -- (default: False) Start the virtual machine now.
• vagrant_provider -- The name of a Vagrant VM provider (if not the default).
• vm -- Optionally, all the above information may be supplied in this dictionary.
Returns A string indicating success, or False.
salt <host> vagrant.init <salt_id> /path/to/Vagrantfile salt my_laptop vagrant.init x1 /projects/bevy_master machine=quail1
salt.modules.vagrant.list_active_vms(cwd=None) Return a list of machine names for active virtual machine on the host, which are defined in the Vagrantfile at the indicated path.
salt '*' vagrant.list_active_vms  cwd=/projects/project_1
salt.modules.vagrant.list_domains() Return a list of the salt_id names of all available Vagrant VMs on this host without regard to the path where they are defined.
salt '*' vagrant.list_domains --log-level=info
The log shows information about all known Vagrant environments on this machine. This data is cached and may not be completely up-to-date.
salt.modules.vagrant.list_inactive_vms(cwd=None) Return a list of machine names for inactive virtual machine on the host, which are defined in the Vagrantfile at the indicated path.
salt '*' virt.list_inactive_vms cwd=/projects/project_1
salt.modules.vagrant.pause(name) Pause (vagrant suspend) the named VM.
salt <host> vagrant.pause <salt_id>
salt.modules.vagrant.reboot(name, provision=False) Reboot a VM. (vagrant reload)
salt <host> vagrant.reboot <salt_id> provision=True
• provision -- (False) also re-run the Vagrant provisioning scripts.
salt.modules.vagrant.shutdown(name) Send a soft shutdown (vagrant halt) signal to the named vm.
This does the same thing as vagrant.stop. Other-VM control modules use "stop" and "shutdown" to differentiate between hard and soft shutdowns.
salt <host> vagrant.shutdown <salt_id>
salt.modules.vagrant.start(name) Start (vagrant up) a virtual machine defined by salt_id name.  The machine must have been previously defined using "vagrant.init".
salt <host> vagrant.start <salt_id>
salt.modules.vagrant.stop(name) Hard shutdown the virtual machine. (vagrant halt)
salt <host> vagrant.stop <salt_id>
salt.modules.vagrant.version() Return the version of Vagrant on the minion
salt '*' vagrant.version
salt.modules.vagrant.vm_state(name='', cwd=None) Return list of information for all the vms indicating their state.
If you pass a VM name in as an argument then it will return info for just the named VM, otherwise it will return all VMs defined by the Vagrantfile in the cwd directory.
salt '*' vagrant.vm_state <name>  cwd=/projects/project_1
returns a list of dictionaries with machine name, state, provider, and salt_id name.
datum = {'machine': _, # Vagrant machine name, 'state': _, # string indicating machine state, like 'running' 'provider': _, # the Vagrant VM provider 'name': _} # salt_id name
Known bug: if there are multiple machines in your Vagrantfile, and you request the status of the primary machine, which you defined by leaving the machine parameter blank, then you may receive the status of all of them.  Please specify the actual machine name for each VM if there are more than one.
salt.modules.varnish Support for Varnish
NOTE: These functions are designed to work with all implementations of Varnish from 3.x onwards
salt.modules.varnish.ban(ban_expression) Add ban to the varnish cache
salt '*' varnish.ban ban_expression
salt.modules.varnish.ban_list() List varnish cache current bans
salt '*' varnish.ban_list
salt.modules.varnish.param_set(param, value) Set a param in varnish cache
salt '*' varnish.param_set param value
salt.modules.varnish.param_show(param=None) Show params of varnish cache
salt '*' varnish.param_show param
salt.modules.varnish.purge() Purge the varnish cache
salt '*' varnish.purge
salt.modules.varnish.version() Return server version from varnishd -V
salt '*' varnish.version
salt.modules.vault Functions to interact with Hashicorp Vault.
maintainer SaltStack
note   If you see the following error, you'll need to upgrade requests to at least 2.4.2
<timestamp> [salt.pillar][CRITICAL][14337] Pillar render error: Failed to load ext_pillar vault: {'error': "request() got an unexpected keyword argument 'json'"}
configuration The salt-master must be configured to allow peer-runner configuration, as well as configuration for the module.
Add this segment to the master configuration file, or /etc/salt/master.d/vault.conf:
vault: url: https://vault.service.domain:8200 verify: /etc/ssl/certs/ca-certificates.crt role_name: minion_role namespace:  vault_enterprice_namespace auth: method: approle role_id: 11111111-2222-3333-4444-1111111111111 secret_id: 11111111-1111-1111-1111-1111111111111 policies: - saltstack/minions - saltstack/minion/{minion} .. more policies keys: - n63/TbrQuL3xaIW7ZZpuXj/tIfnK1/MbVxO4vT3wYD2A - S9OwCvMRhErEA4NVVELYBs6w/Me6+urgUr24xGK44Uy3 - F1j4b7JKq850NS6Kboiy5laJ0xY8dWJvB3fcwA+SraYl - 1cYtvjKJNDVam9c7HNqJUfINk4PYyAXIpjkpN/sIuzPv - 3pPK5X6vGtwLhNOFv1U2elahECz3HpRUfNXJFYLw6lid
url    Url to your Vault installation. Required.
verify For details please see https://requests.readthedocs.io/en/master/user/advanced/#ssl-cert-verification
namespaces Optional Vault Namespace. Used with Vault enterprice
For detail please see: https://www.vaultproject.io/docs/enterprise/namespaces
role_name Role name for minion tokens created. If omitted, minion tokens will be created without any role, thus being able to inherit any master token policy (including token creation capabilities). Optional.
For details please see: https://www.vaultproject.io/api/auth/token/index.html#create-token
Example configuration: https://www.nomadproject.io/docs/vault-integration/index.html#vault-token-role-configuration
auth   Currently only token and approle auth types are supported. Required.
Approle is the preferred way to authenticate with Vault as it provide some advanced options to control authentication process.  Please visit Vault documentation for more info: https://www.vaultproject.io/docs/auth/approle.html
The token must be able to create tokens with the policies that should be assigned to minions.  You can still use the token auth via a OS environment variable via this config example:
vault: url: https://vault.service.domain:8200 auth: method: token token: sdb://osenv/VAULT_TOKEN osenv: driver: env
And then export the VAULT_TOKEN variable in your OS:
export VAULT_TOKEN=11111111-1111-1111-1111-1111111111111
Configuration keys uses or ttl may also be specified under auth to configure the tokens generated on behalf of minions to be reused for the defined number of uses or length of time in seconds. These settings may also be configured on the minion when allow_minion_override is set to True in the master config.
Defining uses will cause the salt master to generate a token with that number of uses rather than a single use token. This multi-use token will be cached on the minion. The type of minion cache can be specified with token_backend: session or token_backend: disk. The value of session is the default, and will store the vault information in memory only for that session.  The value of disk will write to an on disk file, and persist between state runs (most helpful for multi-use tokens).
vault: auth: method: token token: xxxxxx uses: 10 ttl: 43200 allow_minion_override: True token_backend: disk
.. versionchanged:: 3001
policies Policies that are assigned to minions when requesting a token. These can either be static, eg saltstack/minions, or templated with grain values, eg my-policies/{grains[os]}. {minion} is shorthand for grains[id], eg saltstack/minion/{minion}.
IMPORTANT: See Is Targeting using Grain Data Secure? for important security information. In short, everything except grains[id] is minion-controlled.
If a template contains a grain which evaluates to a list, it will be expanded into multiple policies. For example, given the template saltstack/by-role/{grains[roles]}, and a minion having these grains:
grains: roles: - web - database
The minion will have the policies saltstack/by-role/web and saltstack/by-role/database.
NOTE: List members which do not have simple string representations, such as dictionaries or objects, do not work and will throw an exception. Strings and numbers are examples of types which work well.
Optional. If policies is not configured, saltstack/minions and saltstack/{minion} are used as defaults.
keys   List of keys to use to unseal vault server with the vault.unseal runner.
Add this segment to the master configuration file, or /etc/salt/master.d/peer_run.conf:
peer_run: .*: - vault.generate_token
salt.modules.vault.clear_token_cache() Changed in version 3001.
Delete minion Vault token cache file
salt '*' vault.clear_token_cache
salt.modules.vault.delete_secret(path) Delete secret at the path in vault. The vault policy used must allow this.
salt '*' vault.delete_secret "secret/my/secret"
salt.modules.vault.destroy_secret(path, *args) New in version 3001.
Destroy specified secret version at the path in vault. The vault policy used must allow this. Only supported on Vault KV version 2
salt '*' vault.destroy_secret "secret/my/secret" 1 2
salt.modules.vault.list_secrets(path, default=<class 'salt.exceptions.CommandExecutionError'>) Changed in version 3001: The default argument has been added. When the path or path/key combination is not found, an exception will be raised, unless a default is provided.
List secret keys at the path in vault. The vault policy used must allow this.  The path should end with a trailing slash.
salt '*' vault.list_secrets "secret/my/"
salt.modules.vault.read_secret(path, key=None, metadata=False, default=<class 'salt.exceptions.CommandExecutionError'>) Changed in version 3001: The default argument has been added. When the path or path/key combination is not found, an exception will be raised, unless a default is provided.
Return the value of key at path in vault, or entire secret
Parameters metadata --
Optional - If using KV v2 backend, display full results, including metadata
my-secret: {{ salt['vault'].read_secret('secret/my/secret', 'some-key') }}
{{ salt['vault'].read_secret('/secret/my/secret', 'some-key', metadata=True)['data'] }}
{% set supersecret = salt['vault'].read_secret('secret/my/secret') %} secrets: first: {{ supersecret.first }} second: {{ supersecret.second }}
salt.modules.vault.write_raw(path, raw) Set raw data at the path in vault. The vault policy used must allow this.
salt '*' vault.write_raw "secret/my/secret" '{"user":"foo","password": "bar"}'
salt.modules.vault.write_secret(path, **kwargs) Set secret at the path in vault. The vault policy used must allow this.
salt '*' vault.write_secret "secret/my/secret" user="foo" password="bar"
salt.modules.vbox_guest VirtualBox Guest Additions installer
salt.modules.vbox_guest.additions_install(**kwargs) Install VirtualBox Guest Additions. Uses the CD, connected by VirtualBox.
To connect VirtualBox Guest Additions via VirtualBox graphical interface press 'Host+D' ('Host' is usually 'Right Ctrl').
See https://www.virtualbox.org/manual/ch04.html#idp52733088 for more details.
salt '*' vbox_guest.additions_install salt '*' vbox_guest.additions_install reboot=True salt '*' vbox_guest.additions_install upgrade_os=True
• reboot (bool) -- reboot computer to complete installation
• upgrade_os (bool) -- upgrade OS (to ensure the latests version of kernel and developer tools are installed)
Returns version of VirtualBox Guest Additions or string with error
salt.modules.vbox_guest.additions_mount() Mount VirtualBox Guest Additions CD to the temp directory.
salt '*' vbox_guest.additions_mount
Returns True or OSError exception
salt.modules.vbox_guest.additions_remove(**kwargs) Remove VirtualBox Guest Additions.
Firstly it tries to uninstall itself by executing '/opt/VBoxGuestAdditions-VERSION/uninstall.run uninstall'.  It uses the CD, connected by VirtualBox if it failes.
salt '*' vbox_guest.additions_remove salt '*' vbox_guest.additions_remove force=True
Parameters force (bool) -- force VirtualBox Guest Additions removing
Returns True if VirtualBox Guest Additions were removed successfully else False
salt.modules.vbox_guest.additions_umount(mount_point) Unmount VirtualBox Guest Additions CD from the temp directory.
salt '*' vbox_guest.additions_umount
Parameters mount_point -- directory VirtualBox Guest Additions is mounted to
Returns True or an string with error
salt.modules.vbox_guest.additions_version() Check VirtualBox Guest Additions version.
salt '*' vbox_guest.additions_version
Returns version of VirtualBox Guest Additions or False if they are not installed
salt.modules.vbox_guest.grant_access_to_shared_folders_to(name, users=None) Grant access to auto-mounted shared folders to the users.
User is specified by its name. To grant access for several users use argument users.  Access will be denied to the users not listed in users argument.
See https://www.virtualbox.org/manual/ch04.html#sf_mount_auto for more details.
salt '*' vbox_guest.grant_access_to_shared_folders_to fred salt '*' vbox_guest.grant_access_to_shared_folders_to users ['fred', 'roman']
• name (str) -- name of the user to grant access to auto-mounted shared folders to
• users (list of str) -- list of names of users to grant access to auto-mounted shared folders to (if specified, name will not be taken into account)
Returns list of users who have access to auto-mounted shared folders
salt.modules.vbox_guest.list_shared_folders_users() List users who have access to auto-mounted shared folders.
salt '*' vbox_guest.list_shared_folders_users
salt.modules.vboxmanage Support for VirtualBox using the VBoxManage command