.TH "SALT" "7" "March 19, 2012" "0.9.8" "Salt" .SH NAME salt \- Salt Documentation . .nr rst2man-indent-level 0 . .de1 rstReportMargin \\$1 \\n[an-margin] level \\n[rst2man-indent-level] level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] - \\n[rst2man-indent0] \\n[rst2man-indent1] \\n[rst2man-indent2] .. .de1 INDENT .\" .rstReportMargin pre: . RS \\$1 . nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin] . nr rst2man-indent-level +1 .\" .rstReportMargin post: .. .de UNINDENT . RE .\" indent \\n[an-margin] .\" old: \\n[rst2man-indent\\n[rst2man-indent-level]] .nr rst2man-indent-level -1 .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. .\" Man page generated from reStructeredText. . .SH INTRODUCTION TO SALT We’re not just talking about NaCl..SS Distributed remote execution .sp Salt is a distributed remote execution system used to execute commands and query data. It was developed in order to bring the best solutions found in the world of remote execution together and make them better, faster and more malleable. Salt accomplishes this via its ability to handle larger loads of information, and not just dozens, but hundreds or even thousands of individual servers, handle them quickly and through a simple and manageable interface. .SS Simplicity .sp Versatility between massive scale deployments and smaller systems may seem daunting, but Salt is very simple to set up and maintain, regardless of the size of the project. The architecture of Salt is designed to work with any number of servers, from a handful of local network systems to international deployments across disparate datacenters. The topology is a simple server/client model with the needed functionality built into a single set of daemons. While the default configuration will work with little to no modification, Salt can be fine tuned to meet specific needs. .SS Parallel execution .sp The core function of Salt is to enable remote commands to be called in parallel rather than in serial, to use a secure and encrypted protocol, the smallest and fastest network payloads possible, and with a simple programmer interface. Salt also introduces more granular controls to the realm of remote execution, allowing for commands to be executed in parallel and for systems to be targeted based on more than just hostname, but by system properties. .SS Building on proven technology .sp Salt takes advantage of a number of technologies and techniques. The networking layer is built with the excellent \fI\%ZeroMQ\fP networking library, so Salt itself contains a viable, and transparent, AMQ broker inside the daemon. Salt uses public keys for authentication with the master daemon, then uses faster AES encryption for payload communication, this means that authentication and encryption are also built into Salt. Salt takes advantage of communication via \fI\%msgpack\fP, enabling fast and light network traffic. .SS Python client interface .sp In order to allow for simple expansion, Salt execution routines can be written as plain Python modules and the data collected from Salt executions can be sent back to the master server, or to any arbitrary program. Salt can be called from a simple Python API, or from the command line, so that Salt can be used to execute one\-off commands as well as operate as an integral part of a larger application. .SS Fast, flexible, scalable .sp The result is a system that can execute commands across groups of varying size, from very few to very many servers at considerably high speed. A system that is very fast, easy to set up and amazingly malleable, able to suit the needs of any number of servers working within the same system. Salt’s unique architecture brings together the best of the remote execution world, amplifies its capabilities and expands its range, resulting in this system that is as versatile as it is practical, able to suit any network. .SS Open .sp Salt is developed under the \fI\%Apache 2.0 licence\fP, and can be used for open and proprietary projects. Please submit your expansions back to the Salt project so that we can all benefit together as Salt grows. So, please feel free to sprinkle some of this around your systems and let the deliciousness come forth. .SH INSTALLATION .sp The Salt system setup is amazingly simple, as this is one of the central design goals of Salt. .SS Dependencies .sp Salt should run on any Unix\-like platform so long as the dependencies are met. .INDENT 0.0 .IP \(bu 2 \fI\%Python 2.6\fP .IP \(bu 2 \fI\%ZeroMQ\fP >= 2.1.9 .IP \(bu 2 \fI\%pyzmq\fP >= 2.1.9 \- ZeroMQ Python bindings .IP \(bu 2 \fI\%M2Crypto\fP \- Python OpenSSL wrapper .IP \(bu 2 \fI\%PyCrypto\fP \- The Python cryptography toolkit .IP \(bu 2 \fI\%msgpack-python\fP \- High\-performance message interchange format .IP \(bu 2 \fI\%YAML\fP \- Python YAML bindings .UNINDENT .SS Optional Dependencies .INDENT 0.0 .IP \(bu 2 \fI\%Jinja2\fP \- parsing Salt States (configurable in the master settings) .IP \(bu 2 gcc \- dynamic \fI\%Cython\fP module compiling .UNINDENT .SS Platform\-specific installation instructions .SS Arch Linux .sp Salt has primarily been developed on Arch Linux, meaning it is known to work very well on that distribution. The lead developer, Thomas S. Hatch (thatch45) has been a TU (Trusted User) for the Arch Linux distribution, and has written a number of Arch\-specific tools in the past. .sp Salt, while not Arch\-specific, is packaged for and works well on Arch Linux. .SS Installation .sp Salt is currently available via the Arch User Repository (AUR). There are currently stable and \-git packages available. .SS Stable Release .sp To install Salt stable releases from the Arch Linux AUR, use the commands: .sp .nf .ft C wget https://aur.archlinux.org/packages/sa/salt/salt.tar.gz tar xf salt.tar.gz cd salt/ makepkg \-is .ft P .fi .sp A few of Salt\(aqs dependencies are currently only found within the AUR, so you\(aqll need to download and run \fBmakepkg \-is\fP on these as well. As a reference, Salt currently relies on the following packages only available via the AUR: .INDENT 0.0 .IP \(bu 2 \fI\%https://aur.archlinux.org/packages/py/python2-msgpack/python2-msgpack.tar.gz\fP .IP \(bu 2 \fI\%https://aur.archlinux.org/packages/py/python2-psutil/python2-psutil.tar.gz\fP .UNINDENT .IP Note yaourt .sp If you chose to use a tool such as \fI\%Yaourt\fP the dependencies will be gathered and built for you automatically. .sp The command to install salt using the yaourt tool is: .sp .nf .ft C yaourt salt .ft P .fi .RE .SS Tracking develop .sp To install the bleeding edge version of Salt (\fBmay include bugs!\fP), you can use the \-git package. Installing the \-git package can be done using the commands: .sp .nf .ft C wget https://aur.archlinux.org/packages/sa/salt\-git/salt\-git.tar.gz tar xf salt\-git.tar.gz cd salt\-git/ makepkg \-is .ft P .fi .sp A few of Salt\(aqs dependencies are currently only found within the AUR, so you\(aqll need to download and run \fBmakepkg \-is\fP on these as well. As a reference, Salt currently relies on the following packages only available via the AUR: .INDENT 0.0 .IP \(bu 2 \fI\%https://aur.archlinux.org/packages/py/python2-msgpack/python2-msgpack.tar.gz\fP .IP \(bu 2 \fI\%https://aur.archlinux.org/packages/py/python2-psutil/python2-psutil.tar.gz\fP .UNINDENT .IP Note yaourt .sp If you chose to use a tool such as \fI\%Yaourt\fP the dependencies will be gathered and built for you automatically. .sp The command to install salt using the yaourt tool is: .sp .nf .ft C yaourt salt\-git .ft P .fi .RE .SS Configuration .sp In the sections below I\(aqll outline configuration options for both the Salt Master and Salt Minions. .sp The Salt package installs two template configuration files, \fB/etc/salt/master.template\fP and \fB/etc/salt/minion.template\fP. You\(aqll need to copy these .template files into place and make a few edits. First, copy them into place as seen here: .sp .nf .ft C cp /etc/salt/master.template /etc/salt/master cp /etc/salt/minion.template /etc/salt/minion .ft P .fi .sp Note: You\(aqll only need to copy the config for the service you\(aqre going to run. .sp Once you\(aqve copied the config into place you\(aqll need to make changes specific to your setup. Below I\(aqll outline suggested configuration changes to the Master, after which I\(aqll outline configuring the Minion. .SS Master Configuration .sp This section outlines configuration of a Salt Master, which is used to control other machines known as "minions" (see "Minion Configuration" for instructions on configuring a minion). This will outline IP configuration, and a few key configuration paths. .sp \fBInterface\fP .sp By default the Salt master listens on ports 4505 and 4506 on all interfaces (0.0.0.0). If you have a need to bind Salt to a specific IP, redefine the "interface" directive as seen here: .sp .nf .ft C \- #interface: 0.0.0.0 + interface: 10.0.0.1 .ft P .fi .sp \fBrc.conf\fP .sp You\(aqll need to activate the Salt Master in your rc.conf file. Using your favorite editor, open \fB/etc/rc.conf\fP and add the salt\-master. .sp .nf .ft C \-DAEMONS=(syslog\-ng network crond) +DAEMONS=(syslog\-ng network crond @salt\-master) .ft P .fi .sp \fBStart the Master\fP .sp Once you\(aqve completed all of these steps you\(aqre ready to start your Salt Master. You should be able to start your Salt Master now using the command seen here: .sp .nf .ft C rc.d start salt\-master .ft P .fi .sp If your Salt Master doesn\(aqt start successfully, go back through each step and see if anything was missed. Salt doesn\(aqt take much configuration (part of its beauty!), and errors are usually simple mistakes. .SS Minion Configuration .sp Configuring a Salt Minion is surprisingly simple. Unless you have a real need for customizing your minion configuration (which there are plenty of options if you are so inclined!), there is one simple directive that needs to be updated. That option is the location of the master. .sp By default a Salt Minion will try to connect to the dns name "salt". If you have the ability to update DNS records for your domain you might create an A or CNAME record for "salt" that points to your Salt Master. If you are able to do this you likely can do without any minion configuration at all. .sp If you are not able to update DNS, you\(aqll simply need to update one entry in the configuration file. Using your favorite editor, open the minion configuration file and update the "master" entry as seen here. .sp .nf .ft C \- #master: salt + master: 10.0.0.1 .ft P .fi .sp Simply update the master directive to the IP or hostname of your Salt Master. Save your changes and you\(aqre ready to start your Salt Minion. Advanced configuration options are covered in another chapter. .sp \fBrc.conf\fP .sp Before you\(aqre able to start the Salt Minion you\(aqll need to update your rc.conf file. Using your favorite editor open \fB/etc/rc.conf\fP and add this line: .sp .nf .ft C \-DAEMONS=(syslog\-ng network crond) +DAEMONS=(syslog\-ng network crond @salt\-minion) .ft P .fi .sp \fBStart the Minion\fP .sp Once you\(aqve completed all of these steps you\(aqre ready to start your Salt Minion. You should be able to start your Salt Minion now using the command seen here: .sp .nf .ft C rc.d start salt\-minion .ft P .fi .sp If your Salt Minion doesn\(aqt start successfully, go back through each step and see if anything was missed. Salt doesn\(aqt take much configuration (part of its beauty!), and errors are usually simple mistakes. .SS Tying It All Together .sp If you\(aqve successfully completed each of the steps above you should have a running Salt Master and a running Salt Minion. The Minion should be configured to point to the Master. To verify that there is communication flowing between the Minion and Master we\(aqll run a few initial \fBsalt\fP commands. These commands will validate the Minions RSA encryption key, and then send a test command to the Minion to ensure that commands and responses are flowing as expected. .sp \fBKey Management\fP .sp Salt uses AES encryption for all communication between the Master and the Minion. This ensures that the commands you send to your Minions (your cloud) can not be tampered with, and that communication between Master and Minion is only done through trusted, accepted keys. .sp Before you\(aqll be able to do any remote execution or configuration management you\(aqll need to accept any pending keys on the Master. Run the \fBsalt\-key\fP command to list the keys known to the Salt Master. .sp .nf .ft C [root@master ~]# salt\-key \-L Unaccepted Keys: alpha bravo charlie delta Accepted Keys: .ft P .fi .sp This example shows that the Salt Master is aware of four Minions, but none of the keys have been accepted. To accept the keys and allow the Minions to be controlled by the Master, again use the \fBsalt\-key\fP command: .sp .nf .ft C [root@master ~]# salt\-key \-A [root@master ~]# salt\-key \-L Unaccepted Keys: Accepted Keys: alpha bravo charlie delta .ft P .fi .sp The \fBsalt\-key\fP command allows for signing keys individually or in bulk. The example above, using \fB\-A\fP bulk\-accepts all pending keys. To accept keys individually use the lowercase of the same option, \fB\-a keyname\fP. .SS Sending Commands .sp Everything should be set for you to begin remote management of your Minions. Whether you have a few or a few\-dozen, Salt can help you manage them easily! .sp For final verification, send a test function from your Salt Master to your minions. If all of your minions are properly communicating with your Master, you should "True" responses from each of them. See the example below to send the \fBtest.ping\fP remote command: .sp .nf .ft C [root@master ~]# salt \(aq*\(aq test.ping {\(aqalpha\(aq: True} .ft P .fi .SS Where Do I Go From Here .sp Congratulations! You\(aqve successfully configured your first Salt Minions and are able to send remote commands. I\(aqm sure you\(aqre eager to learn more about what Salt can do. Depending on the primary way you want to manage your machines you may either want to visit the section regarding Salt States, or the section on Modules. .SS Debian & Ubuntu .SS Ubuntu .sp We are working to get Salt into apt. In the meantime we have a PPA available for Lucid: .sp .nf .ft C aptitude \-y install python\-software\-properties add\-apt\-repository ppa:saltstack/salt aptitude update aptitude install salt\-master # on the master aptitude install salt\-minion # on the minion aptitude install salt\-syndic # instead of a slaved master .ft P .fi .SS Debian .sp \fI\%A deb package is currently in testing\fP for inclusion in apt. Until that is accepted you can install Salt by downloading the latest \fB.deb\fP in the \fI\%downloads section on GitHub\fP and installing that manually using \fBdpkg \-i\fP. .IP "Installing ZeroMQ on Squeeze (Debian 6)" .sp There is a \fI\%python-zmq\fP package available in Debian "wheezy (testing)". If you don\(aqt have that repo enabled the best way to install Salt and pyzmq is by using \fBpip\fP (or \fBeasy_install\fP): .sp .nf .ft C pip install pyzmq salt .ft P .fi .RE .SS Fedora & CentOS / Enterprise Linux .sp Beginning with version 0.9.4, Salt has been available in the primary Fedora repositories and is available for installation using yum. Fedora will have more up to date versions of Salt than other members of the Red Hat family, which makes it a great place to help improve Salt! .IP "CentOS/EL 5" .sp We are still working to get msgpack packaged for Python 2.6 so Salt is not yet (but nearly) in EPEL 5. In the meantime you can install Salt via our Fedora People repository: .sp .nf .ft C wget \-O /etc/yum.repos.d/epel\-salt.repo \e\e http://repos.fedorapeople.org/repos/herlo/salt/epel\-salt.repo .ft P .fi .RE .SS Installation .sp Salt can be installed using \fByum\fP and is available in the standard Fedora repositories. .SS Stable Release .sp Salt is packaged separately for the minion and the master. You\(aqll only need to install the appropriate package for the role you need the machine to play. This means you\(aqre going to want one master and a whole bunch of minions! .sp .nf .ft C yum install salt\-master yum install salt\-minion .ft P .fi .SS Configuration .sp In the sections below I\(aqll outline configuration options for both the Salt Master and Salt Minions. .SS Master Configuration .sp This section outlines configuration of a Salt Master, which is used to control other machines known as "minions" (see "Minion Configuration" for instructions on configuring a minion). This will outline IP configuration, and a few key configuration paths. .sp \fBInterface\fP .sp By default the Salt master listens on ports 4505 and 4506 on all interfaces (0.0.0.0). If you have a need to bind Salt to a specific IP, redefine the "interface" directive as seen here: .sp .nf .ft C \- #interface: 0.0.0.0 + interface: 10.0.0.1 .ft P .fi .sp \fBEnable the Master\fP .sp You\(aqll also likely want to activate the Salt Master in systemd, configuring the Salt Master to start automatically at boot. .sp .nf .ft C systemctl enable salt\-master.service .ft P .fi .sp \fBStart the Master\fP .sp Once you\(aqve completed all of these steps you\(aqre ready to start your Salt Master. You should be able to start your Salt Master now using the command seen here: .sp .nf .ft C systemctl start salt\-master.service .ft P .fi .sp If your Salt Master doesn\(aqt start successfully, go back through each step and see if anything was missed. Salt doesn\(aqt take much configuration (part of its beauty!), and errors are usually simple mistakes. .SS Minion Configuration .sp Configuring a Salt Minion is surprisingly simple. Unless you have a real need for customizing your minion configuration (which there are plenty of options if you are so inclined!), there is one simple directive that needs to be updated. That option is the location of the master. .sp By default a Salt Minion will try to connect to the dns name "salt". If you have the ability to update DNS records for your domain you might create an A or CNAME record for "salt" that points to your Salt Master. If you are able to do this you likely can do without any minion configuration at all. .sp If you are not able to update DNS, you\(aqll simply need to update one entry in the configuration file. Using your favorite editor, open the minion configuration file and update the "master" entry as seen here: .sp .nf .ft C \- #master: salt + master: 10.0.0.1 .ft P .fi .sp Simply update the master directive to the IP or hostname of your Salt Master. Save your changes and you\(aqre ready to start your Salt Minion. Advanced configuration options are covered in another chapter. .sp \fBEnable the Minion\fP .sp You\(aqll need to configure the minion to auto\-start at boot. You can toggle that option through systemd. .sp .nf .ft C systemctl enable salt\-minion.service .ft P .fi .sp \fBStart the Minion\fP .sp Once you\(aqve completed all of these steps you\(aqre ready to start your Salt Minion. You should be able to start your Salt Minion now using the command here: .sp .nf .ft C systemctl start salt\-minion.service .ft P .fi .sp If your Salt Minion doesn\(aqt start successfully, go back through each step and see if anything was missed. Salt doesn\(aqt take much configuration (part of its beauty!), and errors are usually simple mistakes. .SS Tying It All Together .sp If you\(aqve successfully completed each of the steps above you should have a running Salt Master and a running Salt Minion. The Minion should be configured to point to the Master. To verify that there is communication flowing between the Minion and Master we\(aqll run a few initial \fBsalt\fP commands. These commands will validate the Minions RSA encryption key, and then send a test command to the Minion to ensure that commands and responses are flowing as expected. .sp \fBKey Management\fP .sp Salt uses AES encryption for all communication between the Master and the Minion. This ensures that the commands you send to your Minions (your cloud) can not be tampered with, and that communication between Master and Minion is only done through trusted, accepted keys. .sp Before you\(aqll be able to do any remote execution or configuration management you\(aqll need to accept any pending keys on the Master. Run the \fBsalt\-key\fP command to list the keys known to the Salt Master: .sp .nf .ft C [root@master ~]# salt\-key \-L Unaccepted Keys: alpha bravo charlie delta Accepted Keys: .ft P .fi .sp This example shows that the Salt Master is aware of four Minions, but none of the keys have been accepted. To accept the keys and allow the Minions to be controlled by the Master, again use the \fBsalt\-key\fP command: .sp .nf .ft C [root@master ~]# salt\-key \-A [root@master ~]# salt\-key \-L Unaccepted Keys: Accepted Keys: alpha bravo charlie delta .ft P .fi .sp The \fBsalt\-key\fP command allows for signing keys individually or in bulk. The example above, using \fB\-A\fP bulk\-accepts all pending keys. To accept keys individually use the lowercase of the same option, \fB\-a keyname\fP. .SS Sending Commands .sp Everything should be set for you to begin remote management of your Minions. Whether you have a few or a few\-dozen, Salt can help you manage them easily! .sp For final verification, send a test function from your Salt Master to your minions. If all of your minions are properly communicating with your Master, you should "True" responses from each of them. See the example below to send the \fBtest.ping\fP remote command: .sp .nf .ft C [root@master ~]# salt \(aq*\(aq test.ping {\(aqalpha\(aq: True} .ft P .fi .SS Where Do I Go From Here .sp Congratulations! You\(aqve successfully configured your first Salt Minions and are able to send remote commands. I\(aqm sure you\(aqre eager to learn more about what Salt can do. Depending on the primary way you want to manage your machines you may either want to visit the section regarding Salt States, or the section on Modules. .SS FreeBSD .sp Salt was added to the FreeBSD ports tree Dec 26th, 2011 by Christer Edwards <\fI\%christer.edwards@gmail.com\fP>. It has been tested on FreeBSD 7.4, 8.2 and 9.0 releases. .sp Salt is dependent on the following additional ports. These will be installed as dependencies of the \fBsysutils/salt\fP port. .sp .nf .ft C /devel/py\-yaml /devel/py\-pyzmq /devel/py\-Jinja2 /devel/py\-msgpack /security/py\-pycrypto /security/py\-m2crypto .ft P .fi .SS Installation .sp To install Salt from the FreeBSD ports tree, use the command: .sp .nf .ft C cd /usr/ports/sysutils/salt && make install clean .ft P .fi .sp Once the port is installed you\(aqll need to make a few configuration changes. These include defining the IP to bind to (optional), and some configuration path changes to make salt fit more natively into the FreeBSD filesystem tree. .SS Configuration .sp In the sections below I\(aqll outline configuration options for both the Salt Master and Salt Minions. .sp The Salt port installs two sample configuration files, \fBsalt/master.sample\fP and \fBsalt/minion.sample\fP (these should be installed in \fB/usr/local/etc/\fP, unless you use a different \fB%%PREFIX%%\fP). You\(aqll need to copy these .sample files into place and make a few edits. First, copy them into place as seen here: .sp .nf .ft C cp /usr/local/etc/salt/master.sample /usr/local/etc/salt/master cp /usr/local/etc/salt/minion.sample /usr/local/etc/salt/minion .ft P .fi .sp Note: You\(aqll only need to copy the config for the service you\(aqre going to run. .sp Once you\(aqve copied the config into place you\(aqll need to make changes specific to your setup. Below I\(aqll outline suggested configuration changes to the Master, after which I\(aqll outline configuring the Minion. .SS Master Configuration .sp This section outlines configuration of a Salt Master, which is used to control other machines known as "minions" (see "Minion Configuration" for instructions on configuring a minion). This will outline IP configuration, and a few key configuration paths. .sp \fBInterface\fP .sp By default the Salt master listens on ports 4505 and 4506 on all interfaces (0.0.0.0). If you have a need to bind Salt to a specific IP, redefine the "interface" directive as seen here. .sp .nf .ft C \- #interface: 0.0.0.0 + interface: 10.0.0.1 .ft P .fi .sp \fBrc.conf\fP .sp Last but not least you\(aqll need to activate the Salt Master in your rc.conf file. Using your favorite editor, open \fB/etc/rc.conf\fP or \fB/etc/rc.conf.local\fP and add this line. .sp .nf .ft C + salt_master_enable="YES" .ft P .fi .sp \fBStart the Master\fP .sp Once you\(aqve completed all of these steps you\(aqre ready to start your Salt Master. The Salt port installs an rc script which should be used to manage your Salt Master. You should be able to start your Salt Master now using the command seen here: .sp .nf .ft C service salt_master start .ft P .fi .sp If your Salt Master doesn\(aqt start successfully, go back through each step and see if anything was missed. Salt doesn\(aqt take much configuration (part of its beauty!), and errors are usually simple mistakes. .SS Minion Configuration .sp Configuring a Salt Minion is surprisingly simple. Unless you have a real need for customizing your minion configuration (which there are plenty of options if you are so inclined!), there is one simple directive that needs to be updated. That option is the location of the master. .sp By default a Salt Minion will try to connect to the dns name "salt". If you have the ability to update DNS records for your domain you might create an A or CNAME record for "salt" that points to your Salt Master. If you are able to do this you likely can do without any minion configuration at all. .sp If you are not able to update DNS, you\(aqll simply need to update one entry in the configuration file. Using your favorite editor, open the minion configuration file and update the "master" entry as seen here. .sp .nf .ft C \- #master: salt + master: 10.0.0.1 .ft P .fi .sp Simply update the master directive to the IP or hostname of your Salt Master. Save your changes and you\(aqre ready to start your Salt Minion. Advanced configuration options are covered in another chapter. .sp \fBrc.conf\fP .sp Before you\(aqre able to start the Salt Minion you\(aqll need to update your rc.conf file. Using your favorite editor open \fB/etc/rc.conf\fP or \fB/etc/rc.conf.local\fP and add this line. .sp .nf .ft C + salt_minion_enable="YES" .ft P .fi .sp Once you\(aqve completed all of these steps you\(aqre ready to start your Salt Minion. The Salt port installs an rc script which should be used to manage your Salt Minion. You should be able to start your Salt Minion now using the command seen here. .sp .nf .ft C service salt_minion start .ft P .fi .sp If your Salt Minion doesn\(aqt start successfully, go back through each step and see if anything was missed. Salt doesn\(aqt take much configuration (part of its beauty!), and errors are usually simple mistakes. .SS Tying It All Together .sp If you\(aqve successfully completed each of the steps above you should have a running Salt Master and a running Salt Minion. The Minion should be configured to point to the Master. To verify that there is communication flowing between the Minion and Master we\(aqll run a few initial \fBsalt\fP commands. These commands will validate the Minions RSA encryption key, and then send a test command to the Minion to ensure that commands and responses are flowing as expected. .sp \fBKey Management\fP .sp Salt uses AES encryption for all communication between the Master and the Minion. This ensures that the commands you send to your Minions (your cloud) can not be tampered with, and that communication between Master and Minion is only done through trusted, accepted keys. .sp Before you\(aqll be able to do any remote execution or state management you\(aqll need to accept any pending keys on the Master. Run the \fBsalt\-key\fP command to list the keys known to the Salt Master: .sp .nf .ft C [root@master ~]# salt\-key \-L Unaccepted Keys: alpha bravo charlie delta Accepted Keys: .ft P .fi .sp This example shows that the Salt Master is aware of four Minions, but none of the keys have been accepted. To accept the keys and allow the Minions to be controlled by the Master, again use the \fBsalt\-key\fP command: .sp .nf .ft C [root@master ~]# salt\-key \-A [root@master ~]# salt\-key \-L Unaccepted Keys: Accepted Keys: alpha bravo charlie delta .ft P .fi .sp The \fBsalt\-key\fP command allows for signing keys individually or in bulk. The example above, using \fB\-A\fP bulk\-accepts all pending keys. To accept keys individually use the lowercase of the same option, \fB\-a keyname\fP. .SS Sending Commands .sp Everything should be set for you to begin remote management of your Minions. Whether you have a few or a few\-dozen, Salt can help you manage them easily! .sp For final verification, send a test function from your Salt Master to your minions. If all of your minions are properly communicating with your Master, you should "True" responses from each of them. See the example below to send the \fBtest.ping\fP remote command. .sp .nf .ft C [root@master ~]# salt \(aqalpha\(aq test.ping {\(aqalpha\(aq: True} .ft P .fi .SS Where Do I Go From Here .sp Congratulations! You\(aqve successfully configured your first Salt Minions and are able to send remote commands. I\(aqm sure you\(aqre eager to learn more about what Salt can do. Depending on the primary way you want to manage your machines you may either want to visit the section regarding Salt States, or the section on Modules. .SS Gentoo .sp Salt can be easily installed on Gentoo: .sp .nf .ft C emerge pyyaml m2crypto pycrypto jinja pyzmq .ft P .fi .sp Then download and install from source: .INDENT 0.0 .IP 1. 3 Download the latest source tarball from the \fI\%GitHub downloads\fP directory for the Salt project. .IP 2. 3 Untar the tarball and run the \fBsetup.py\fP as root: .UNINDENT .sp .nf .ft C tar xf salt\-.tar.gz cd salt\- python setup.py install .ft P .fi .SH CONFIGURING SALT .sp Salt configuration is very simple. The default configuration for the \fImaster\fP will work for most installations and the only requirement for setting up a \fIminion\fP is to set the location of the master in the minion configuration file. .INDENT 0.0 .TP .B master The Salt master is the central server that all minions connect to. You run commands on the minions through the master and minions send data back to the master (unless otherwise redirected with a \fBreturner\fP). It is started with the \fBsalt\-master\fP program. .TP .B minion Salt minions are the potentially hundreds or thousands of servers that you query and control from the master. .UNINDENT .sp The configuration files will be installed to \fB/etc/salt\fP and are named after the respective components, \fB/etc/salt/master\fP and \fB/etc/salt/minion\fP. .sp To make a minion check into the correct master simply edit the \fBmaster\fP variable in the minion configuration file to reference the master DNS name or IPv4 address. .SS Running Salt .INDENT 0.0 .IP 1. 3 Start the master in the foreground (to daemonize the process, pass the \fI\-d flag\fP): .sp .nf .ft C # salt\-master .ft P .fi .IP 2. 3 Start the minion in the foreground (to daemonize the process, pass the \fI\-d flag\fP): .sp .nf .ft C # salt\-minion .ft P .fi .UNINDENT .IP "Having trouble?" .sp The simplest way to troubleshoot Salt is to run the master and minion in the foreground with \fIlog level\fP set to \fBdebug\fP: .sp .nf .ft C salt\-master \-\-log\-level=debug .ft P .fi .RE .IP "Run as an unprivileged (non\-root) user?" .sp To run Salt as another user, specify \fB\-\-user\fP in the command line or assign \fBuser\fP in the \fBconfiguration file\fP. .RE .sp There is also a full \fBtroubleshooting guide\fP available. .SS Manage Salt public keys .sp Salt manages authentication with RSA public keys. The keys are managed on the \fImaster\fP via the \fBsalt\-key\fP command. Once a \fIminion\fP checks into the master the master will save a copy of the minion key. Before the master can send commands to the minion the key needs to be "accepted". .INDENT 0.0 .IP 1. 3 List the accepted and unaccepted salt keys: .sp .nf .ft C salt\-key \-L .ft P .fi .IP 2. 3 Accept a minion key: .sp .nf .ft C salt\-key \-a .ft P .fi .sp or accept all unaccepted minion keys: .sp .nf .ft C salt\-key \-A .ft P .fi .UNINDENT .IP "See also" .sp \fBsalt\-key manpage\fP .RE .SH TARGETING .INDENT 0.0 .TP .B Targeting Specifying which minions should run a command or execute a state by matching against hostnames, or system information, or defined groups, or even combinations thereof. .UNINDENT .sp For example the command \fBsalt web1 apache.signal restart\fP to restart the Apache httpd server specifies the machine \fBweb1\fP as the target and the command will only be run on that one minion. .sp Similarly when using states, the following \fItop file\fP specifies that only the \fBweb1\fP minion should execute the contents of \fBwebserver.sls\fP: .sp .nf .ft C base: \(aqweb1\(aq: \- webserver .ft P .fi .sp There are many ways to target individual minions or groups of minions in Salt: .SS Matching the \fBminion id\fP .INDENT 0.0 .TP .B minion id A unique identifier for a given minion. By default the minion id is the FQDN of that host but this can be overridden. .UNINDENT .sp Each minion needs a unique identifier. By default when a minion starts for the first time it chooses its FQDN as that identifier. The minion id can be overridden via the minion\(aqs \fBid\fP configuration setting. .IP Tip minion id and minion keys .sp The \fIminion id\fP is used to generate the minion\(aqs public/private keys and if it ever changes the master must then accept the new key as though the minion was a new host. .RE .SS Globbing .sp The default matching that Salt utilizes is shell\-style globbing around the \fIminion id\fP. This also works for states in the \fItop file\fP. .IP Note You must wrap \fBsalt\fP calls that use globbing in single\-quotes to prevent the shell from expanding the globs before Salt is invoked. .RE .sp Match all minions: .sp .nf .ft C salt \(aq*\(aq test.ping .ft P .fi .sp Match all minions in the example.net domain or any of the example domains: .sp .nf .ft C salt \(aq*.example.net\(aq test.ping salt \(aq*.example.*\(aq test.ping .ft P .fi .sp Match all the \fBwebN\fP minions in the example.net domain (\fBweb1.example.net\fP, \fBweb2.example.net\fP … \fBwebN.example.net\fP): .sp .nf .ft C salt \(aqweb?.example.net test.ping .ft P .fi .sp Match the \fBweb1\fP through \fBweb5\fP minions: .sp .nf .ft C salt \(aqweb[1\-5]\(aq test.ping .ft P .fi .sp Match the \fBweb\-x\fP, \fBweb\-y\fP, and \fBweb\-z\fP minions: .sp .nf .ft C salt \(aqweb\-[x\-z]\(aq test.ping .ft P .fi .SS Regex .sp Minions can be matched using Perl\-compatible regular expressions (which is globbing on steroids and a ton of caffeine). .sp Match both \fBweb1\-prod\fP and \fBweb1\-devel\fP minions: .sp .nf .ft C salt \-E \(aqweb1\-(prod|devel)\(aq test.ping .ft P .fi .sp When using regex in a states \fItop file\fP you must specify the matcher as the first option. The following example executes the contents of \fBwebserver.sls\fP on the above\-mentioned minions. .sp .nf .ft C base: \(aqweb1\-(prod|devel)\(aq: \- match: pcre \- webserver .ft P .fi .SS Lists .sp At the most basic you can specify a flat list of minion ids: .sp .nf .ft C salt \-L \(aqweb1,web2,web3\(aq test.ping .ft P .fi .SS Grains .sp Salt comes with an interface to derive information about the underlying system. This is called the grains interface, because it presents salt with grains of information. .sp The grains interface is made available to Salt modules and components so that the right salt minion commands are automatically available on the right systems. .sp It is important to remember that grains are bits of information loaded when the salt minion starts, so this information is static. This means that the information in grains is unchanging, therefore the nature of the data is static. So grains information are things like the running kernel, or the operating system. .SS Grains in the Minion Config .sp Grains can also be statically assigned within the minion configuration file. Just add the option \fBgrains\fP and pass options to it: .sp .nf .ft C grains: roles: \- webserver \- memcache deployment: datacenter4 cabinet: 13 cab_u: 14\-15 .ft P .fi .sp Then status data specific to your servers can be retrieved via Salt, or used inside of the state system for matching. It also makes targeting, in the case of the example above, simply based on specific data about your deployment. .SS Writing Grains .sp Grains are easy to write. The grains interface is derived by executing all of the "public" functions found in the modules located in the grains package or the custom grains directory. The functions in the modules of the grains must return a python dict, where the keys in the dict are the names of the grains and the values are the values. .sp Custom grains should be placed in a \fB_grains\fP directory located under your \fBfile_roots\fP. Before adding a grain to salt, consider what the grain is and remember that grains need to be static data. .SS Examples of Grains .sp The core module in the grains package is where the main grains are loaded by the salt minion and the principal example of how to write grains: .sp \fI\%https://github.com/saltstack/salt/blob/v0.9.8/salt/grains/core.py\fP .SS Syncing Grains .sp Syncing grains can be done a number of ways, they are automatically synced when state.highstate is called, or the grains can be synced and reloaded by calling the saltutil.sync_grains or saltutil.sync_all functions. .SS Node groups .INDENT 0.0 .TP .B Node group A predefined group of minions declared in the master configuration file \fBnodegroups\fP setting as a \fIcompound target\fP. .UNINDENT .sp For example, in the master config file \fBnodegroups\fP setting: .sp .nf .ft C nodegroups: group1: \(aqL@foo.domain.com,bar.domain.com,baz.domain.com and bl*.domain.com\(aq group2: \(aqG@os:Debian and foo.domain.com\(aq .ft P .fi .sp Specify a nodegroup via the \fB\-N\fP option at the command\-line: .sp .nf .ft C salt \-N group1 test.ping .ft P .fi .sp Specify a nodegroup with \fB\- match: nodegroup\fP in a \fItop file\fP: .sp .nf .ft C base: group1: \- match: nodegroup \- webserver .ft P .fi .SS Compound matchers .INDENT 0.0 .TP .B Compound matcher A combination of many target definitions that can be combined with boolean operators. .UNINDENT .sp Compound matchers allow very granular minion targeting using any of the previously discussed matchers. The default matcher is a glob, as usual. If something other than a glob is used preface it with the letter denoting the type. Matchers can be joined using boolean \fBand\fP, \fBor\fP, and \fBnot\fP operators. .sp For example, the following command matches all minions that have a hostname that begins with "webserv" and that are running Debian or it matches any minions that have a hostname that matches the regular expression \fBweb\-dc1\-srv.*\fP: .sp .nf .ft C salt \-C \(aqwebserv* and G@os:Debian or E@web\-dc1\-srv.*\(aq test.ping .ft P .fi .sp That same example expressed in a \fItop file\fP looks like the following: .sp .nf .ft C base: \(aqwebserv* and G@os:Debian or E@web\-dc1\-srv.*\(aq: \- match: compound \- webserver .ft P .fi .SH REMOTE EXECUTION TUTORIAL .sp \fBBefore continuing\fP make sure you have a working Salt installation by following the \fI\%installation\fP and the \fBconfiguration\fP instructions. .IP "Stuck?" .sp If you get stuck at any point, there are many ways to \fBget help from the Salt community\fP including our mailing list and our IRC channel. .RE .SS Order your minions around .sp Now that you have a \fImaster\fP and at least one \fIminion\fP communicating with each other you can perform commands on the minion via the \fBsalt\fP command. Salt calls are comprised of three main components: .sp .nf .ft C salt \(aq\(aq [arguments] .ft P .fi .IP "See also" .sp \fBsalt manpage\fP .RE .SS target .sp The target component allows you to filter which minions should run the following function. The default filter is a glob on the minion id. E.g.: .sp .nf .ft C salt \(aq*\(aq test.ping salt \(aq*.example.org\(aq test.ping .ft P .fi .sp Targets can be based on minion system information using the grains system: .sp .nf .ft C salt \-G \(aqos:Ubuntu\(aq test.ping .ft P .fi .IP "See also" .sp \fBGrains system\fP .RE .sp Targets can be filtered by regular expression: .sp .nf .ft C salt \-E \(aqvirtmach[0\-9]\(aq test.ping .ft P .fi .sp Finally, targets can be explicitly specified in a list: .sp .nf .ft C salt \-L foo,bar,baz,quo test.ping .ft P .fi .SS function .sp A function is some functionality provided by a module. Salt ships with a large collection of available functions. List all available functions on your minions: .sp .nf .ft C salt \(aq*\(aq sys.doc .ft P .fi .sp Here are some examples: .sp Show all currently available minions: .sp .nf .ft C salt \(aq*\(aq test.ping .ft P .fi .sp Run an arbitrary shell command: .sp .nf .ft C salt \(aq*\(aq cmd.run \(aquname \-a\(aq .ft P .fi .IP "See also" .sp \fBthe full list of modules\fP .RE .SS arguments .sp Space\-delimited arguments to the function: .sp .nf .ft C salt \(aq*\(aq cmd.exec_code python \(aqimport sys; print sys.version\(aq .ft P .fi .SH HOW DO I USE SALT STATES? .sp Simplicity, Simplicity, Simplicity .sp Many of the most powerful and useful engineering solutions are founded on simple principals, the Salt SLS system strives to do just that. K.I.S.S. .sp The core of the Salt State system is the SLS, or the SaLt State file. The SLS is a representation of the state in which a system should be in, and is set up to contain this data simply. This is often called configuration management. .SS It is All Just Data .sp Before delving into the particulars, it will help to understand that the SLS is just a data structure under the hood. While understanding that the SLS is just a data structure is not at all critical to understand to make use Salt States, it should help bolster the understanding of where the real power is. .sp SLS files are therefore, in reality, just dictionaries, lists, strings and numbers. By using this approach Salt can be much more flexible. As someone writes more state files, it becomes clear exactly what is being written. The result is a system that is easy to understand, yet grows with the needs of the admin or developer. .sp In the section titled "State Data Structures" a reference exists, explaining in depth how the data is laid out. .SS Default Data \- YAML .sp By default Salt represents the SLS data in what is one of the simplest serialization formats available \- YAML. .sp A typical SLS file will often look like this in YAML: .sp .nf .ft C apache: pkg: \- installed service: \- running \- require: \- pkg: apache .ft P .fi .sp This SLS data will ensure that the package named apache is installed, and that the apache service is running. The components can be explained in a simple way. .sp The first like it the ID for a set of data, and it is called the ID Declaration. This ID sets the name of the thing that needs to be manipulated. .sp The second and fourth lines are the start of the State Declarations, so they are using the pkg and service states respectively. The pkg state manages a software package to get installed via the system\(aqs native package manager, and the service state manages a system daemon. Below the pkg and service lines are the function to run. This function defines what state the named package and service should be in. Here the package is to be installed, and the service should be running. .sp Finally, on line 6, is the word \fBrequire\fP. This is called a Requisite Statement, and it makes sure that the Apache service is only started after the successful installation of the apache package. .SS Adding Configs and Users .sp When setting up a service like an apache web server, many more components may need to be added. The apache configuration file will most likely be managed, and a user and group may need to be set up. .sp .nf .ft C apache: pkg: \- installed service: \- running \- watch: \- pkg: apache \- file: /etc/httpd/conf/httpd.conf \- user: apache user: \- present \- uid: 87 \- gid: 87 \- home: /var/www/html \- shell: /bin/nologin \- require: \- group: apache group: \- present \- gid: 87 \- require: \- pkg: apache /etc/httpd/conf/httpd.conf: file: \- managed \- source: salt://apache/httpd.conf \- user: root \- group: root \- mode: 644 .ft P .fi .sp This SLS data greatly extends the first example, and includes a config file, a user, a group and new requisite statement: \fBwatch\fP. .sp Adding more states is easy, since the new user and group states are under the apache ID, the user and group will be the apache user and group. The \fBrequire\fP statements will make sure that the user will only be made after the group, and that the group will be made only after the apache package is installed. .sp Next,the \fBrequire\fP statement under service was changed to watch, and is now watching 3 states instead of just one. The watch statement does the same thing as require, making sure that the other states run before running the state with a watch, but it adds an extra component. The \fBwatch\fP statement will run the state\(aqs watcher function if any of the watched states changed anything. So if the package was updated, the config file changed, or the user uid modified, then the service state\(aqs watcher will be run. The service state\(aqs watcher just restarts the service, so in this case, a change in the config file will also trigger a restart of the respective service. .SS Moving Beyond a Single SLS .sp When setting up Salt States, more than one SLS will need to be used. The above examples were just in a single SLS file, but more than one SLS file can be combined to build out a State Tree. The above example also references a file with a strange source \- \fBsalt://apache/httpd.conf\fP. That file will need to be available as well. .sp The SLS files are laid out in a directory on the salt master. Files are laid out as just files. A sls is just a file and files to download are just files. .sp The apache example would be laid out in the root of the salt file server like this: .sp .nf .ft C /apache/init.sls /apache/httpd.conf .ft P .fi .sp So the httpd.conf is just a file in the apache directory, and is referenced directly. .sp But with more than a single SLS file, more components can be added to the toolkit, consider this ssh example: .sp \fB/ssh/init.sls:\fP .sp .nf .ft C openssh\-client: pkg: \- installed /etc/ssh/ssh_config file: \- managed \- user: root \- group: root \- mode: 644 \- source: salt://ssh/ssh_config \- require: \- pkg: openssh\-client .ft P .fi .sp \fBssh/server.sls:\fP .sp .nf .ft C include: \- ssh openssh\-server: pkg: \- installed sshd: service: \- running \- require: \- pkg: openssh\-client \- pkg: openssh\-server \- file: /etc/ssh/banner \- file: /etc/ssh/sshd_config /etc/ssh/sshd_config: \- managed \- user: root \- group: root \- mode: 644 \- source: salt://ssh/sshd_config \- require: \- pkg: openssh\-server /etc/ssh/banner: file: \- managed \- user: root \- group: root \- mode: 644 \- source: salt://ssh/banner \- require: \- pkg: openssh\-server .ft P .fi .sp Now our State Tree looks like this: .sp .nf .ft C /apache/init.sls /apache/httpd.conf /ssh/init.sls /ssh/server.sls /ssh/banner /ssh/ssh_config /ssh/sshd_config .ft P .fi .sp This example now introduces the \fBinclude\fP statement. The include statement includes another SLS file so that components found in it can be required, watched or as will soon be demonstrated \- extended. .sp The include statement allows for states to be cross linked. When an SLS has an include statement it is literally extended to include the contents of the included SLS files. .SS Extending Included SLS Data .sp Sometimes SLS data needs to be extended. Perhaps the apache service needs to watch additional resources, or under certain circumstances a different file needs to be placed. .sp These examples will add more watchers to apache and change the ssh banner. .sp \fB/ssh/custom\-server.sls:\fP .sp .nf .ft C include: \- ssh.server extend: /etc/ssh/banner: file: \- source: salt://ssh/custom\-banner .ft P .fi .sp \fB/python/mod_python.sls:\fP .sp .nf .ft C include: \- apache extend: apache: service: \- watch: \- pkg: mod_python mod_python: pkg: \- installed .ft P .fi .sp The \fBcustom\-server.sls\fP file uses the extend statement to overwrite where the banner is being downloaded from, and therefore changing what file is being used to configure the banner. .sp In the new mod_python SLS the mod_python package is added, but more importantly the apache service was extended to also watch the mod_python package. .sp There is a bit of a trick here, in the extend statement Requisite Statements are extended, so the \fB\- pkg: mod_python\fP is appended to the watch list. But all other statements are overwritten. .SS Understanding the Render System .sp Since the SLS data is just plain old data, it does not need to be represented with YAML. Salt defaults to YAML because it is very straightforward and easy to learn and use. But the SLS files can be rendered from almost any imaginable medium, so long as a renderer module is provided. .sp The default rendering system is the \fByaml_jinja\fP renderer. The \fByaml_jinja\fP renderer will first pass the template through the jinja templating system, and then through the YAML parser. The benefit here is that full programming constructs are available when creating SLS files. .sp Other renderers available are \fByaml_mako\fP which uses the mako templating system rather than the jinja templating system, and more notably, the pure python or \fBpy\fP renderer. The \fBpy\fP renderer allows for SLS files to be written in pure python, allowing for the utmost level of flexibility and power when preparing SLS data. .SS Getting to Know the Default \- yaml_jinja .sp The default renderer \- \fByaml_jinja\fP, allows for the use of the jinja templating system. A guide to the jinja templating system can be found here: \fI\%http://jinja.pocoo.org/docs\fP .sp When working with renderers a few very useful bits of data are passed in. In the case of templating engine based renderers two critical components are available, \fBsalt\fP, \fBgrains\fP, and \fBpillar\fP. The salt object allows for any salt function to be called from within the template, and grains allows for the grains to be accessed from within the template. A few examples: .sp \fB/apache/init.sls:\fP .sp .nf .ft C apache: pkg: \- installed {% if grains[\(aqos\(aq] == \(aqRedHat\(aq%} \- name: httpd {% endif %} service: \- running {% if grains[\(aqos\(aq] == \(aqRedHat\(aq%} \- name: httpd {% endif %} \- watch: \- pkg: apache \- file: /etc/httpd/conf/httpd.conf \- user: apache user: \- present \- uid: 87 \- gid: 87 \- home: /var/www/html \- shell: /bin/nologin \- require: \- group: apache group: \- present \- gid: 87 \- require: \- pkg: apache /etc/httpd/conf/httpd.conf: file: \- managed \- source: salt://apache/httpd.conf \- user: root \- group: root \- mode: 644 .ft P .fi .sp This example is simple. If the \fBos\fP grain states that the operating system is Red Hat, then the name of the apache package and service needs to be httpd. .sp A more aggressive way to use Jinja can be found here, in a module to set up a MooseFS distributed filesystem chunkserver: .sp \fB/moosefs/chunk.sls:\fP .sp .nf .ft C include: \- moosefs {% for mnt in salt[\(aqcmd.run\(aq](\(aqls /dev/data/moose*\(aq).split() %} /mnt/moose{{ mnt[\-1] }}: mount: \- mounted \- device: {{ mnt }} \- fstype: xfs \- mkmnt: True file: \- directory \- user: mfs \- group: mfs \- require: \- user: mfs \- group: mfs {% endfor %} \(aq/etc/mfshdd.cfg\(aq: file: \- managed \- source: salt://moosefs/mfshdd.cfg \- user: root \- group: root \- mode: 644 \- template: jinja \- require: \- pkg: mfs\-chunkserver \(aq/etc/mfschunkserver.cfg\(aq: file: \- managed \- source: salt://moosefs/mfschunkserver.cfg \- user: root \- group: root \- mode: 644 \- template: jinja \- require: \- pkg: mfs\-chunkserver mfs\-chunkserver: pkg: \- installed mfschunkserver: service: \- running \- require: {% for mnt in salt[\(aqcmd.run\(aq](\(aqls /dev/data/moose*\(aq) %} \- mount: /mnt/moose{{ mnt[\-1] }} \- file: /mnt/moose{{ mnt[\-1] }} {% endfor %} \- file: /etc/mfschunkserver.cfg \- file: /etc/mfshdd.cfg \- file: /var/lib/mfs .ft P .fi .sp This example shows much more of the available power provided by Jinja. Multiple for loops are used to dynamically detect available hard drives and set them up to be mounted, and the \fBsalt\fP object is used multiple times to call shell commands to gather data. .SS Introducing the Python Renderer .sp Sometimes the chosen default renderer might not have enough logical power to accomplish the needed task. When this happens, the python renderer can be used. Normally a yaml renderer should be used for the majority of SLS files, but a SLS file set to use another renderer can be easily added to the tree. .sp This example shows a very basic python SLS file: .sp \fB/python/django.sls:\fP .sp .nf .ft C #!py def run(): \(aq\(aq\(aq Install the django package \(aq\(aq\(aq return {\(aqinclude\(aq: [\(aqpython\(aq], \(aqdjango\(aq: {\(aqpkg\(aq: [\(aqinstalled\(aq]}} .ft P .fi .sp This is a very simple example, the first line has a SLS shebang line that tells Salt to not use the default renderer, but to use the \fBpy\fP renderer. Then the run function is defined, the return value from the run function must be a Salt friendly data structure, or better known as a Salt \fBHighState data structure\fP. .sp This python example would look like this if it were written in YAML: .sp .nf .ft C include: \- python django: pkg: \- installed .ft P .fi .sp This clearly illustrates, that not only is using the YAML renderer a wise decision as the default, but that unbridled power can be obtained where needed by using a pure python SLS. .sp Now onto the \fBStates tutorial, part 1\fP. .SH STATES TUTORIAL, PART 1 .sp The purpose of this tutorial is to demonstrate how quickly you can configure a system to be managed by Salt States. For detailed information about the state system please refer to the full \fBstates reference\fP. .sp This tutorial will walk you through using Salt to configure a minion to run the Apache HTTP server and to ensure the server is running. .sp \fBBefore continuing\fP make sure you have a working Salt installation by following the \fI\%installation\fP and the \fBconfiguration\fP instructions. .IP "Stuck?" .sp If you get stuck at any point, there are many ways to \fBget help from the Salt community\fP including our mailing list and our IRC channel. .RE .SS Setting up the Salt State Tree .sp States are stored in text files on the master and transfered to the minions on demand via the master\(aqs File Server. The collection of state files make up the \fIState Tree\fP. .sp To start using a central state system in Salt you must first set up the Salt File Server. Edit your master config file (\fBfile_roots\fP) and uncomment the following lines: .sp .nf .ft C file_roots: base: \- /srv/salt .ft P .fi .IP Note If you are deploying on FreeBSD via ports, the \fBfile_roots\fP path defaults to \fB/usr/local/etc/salt/states\fP. .RE .sp Restart the Salt master in order to pick up this change: .sp .nf .ft C % pkill salt\-master % salt\-master \-d .ft P .fi .SS Preparing the Top File .sp On the master in the directory you specified in the previous step, create a new file called \fBtop.sls\fP and add the following: .sp .nf .ft C base: \(aq*\(aq: \- webserver .ft P .fi .sp The \fItop file\fP is separated into environments (discussed later). The default environment is \fBbase\fP. Under the \fBbase\fP environment a collection of minion matches is defined; for now simply specify all hosts (\fB*\fP). .IP "Targeting minions" .sp The expressions can use any of the targeting mechanisms used by Salt — minions can be matched by glob, pcre regular expression, or by \fBgrains\fP. For example: .sp .nf .ft C base: \(aqos:Fedora\(aq: \- match: grain \- webserver .ft P .fi .RE .SS Create an \fBsls\fP module .sp In the same directory as your \fItop file\fP, create an empty file, called an \fIsls module\fP, named \fBwebserver.sls\fP. Type the following and save the file: .sp .nf .ft C apache: # ID declaration pkg: # state declaration \- installed # function declaration .ft P .fi .sp The first line, called the \fIID declaration\fP, is an arbitrary identifier. In this case it defines the name of the package to be installed. \fBNOTE:\fP the package name for the Apache httpd web server may differ on your OS or distro — for example, on Fedora it is \fBhttpd\fP but on Debian/Ubuntu it is \fBapache2\fP. .sp Additionally, an ID declaration should not contain a dot, as this will produce unpredictable output in the summary returned from a call to \fBstate.highstate\fP. .sp The second line, called the \fIstate declaration\fP, defines which of the Salt States we are using. In this example, we are using the \fBpkg state\fP to ensure that a given package is installed. .sp The third line, called the \fIfunction declaration\fP, defines which function in the \fBpkg state\fP module to call. .IP "Renderers" .sp States \fIsls\fP files can be written in many formats. Salt requires only a simple data structure and is not concerned with how that data structure is built. Templating languages and \fI\%DSLs\fP are a dime\-a\-dozen and everyone has a favorite. .sp Building the expected data structure is the job of Salt \fBrenderers\fP and they are dead\-simple to write. .sp In this tutorial we will be using YAML in Jinja2 templates, which is the default format. You can change the default by changing \fBrenderer\fP in the master configuration file. .RE .SS Install the package .sp Next, let\(aqs run the state we created. Open a terminal on the master and run: .sp .nf .ft C % salt \(aq*\(aq state.highstate .ft P .fi .sp Our master is instructing all targeted minions to run \fBstate.highstate\fP. When a minion executes a highstate call it will download the \fItop file\fP and attempt to match the expressions. When it does match an expression the modules listed for it will be downloaded, compiled, and executed. .sp Once completed, the minion will report back with a summary of all actions taken and all changes made. .IP "Troubleshooting Salt" .sp In case you don\(aqt see the expected output, the following tips can help you narrow down the problem. .INDENT 0.0 .TP .B Turn up logging Salt can be quite chatty when you change the logging setting to \fBdebug\fP: .sp .nf .ft C salt\-minion \-l debug .ft P .fi .TP .B Run the minion in the foreground By not starting the minion in daemon mode (\fI\-d\fP) you can view any output from the minion as it works: .sp .nf .ft C salt\-minion & .ft P .fi .UNINDENT .sp Increase the default timeout value when running \fBsalt\fP. For example, to change the default timeout to 60 seconds: .sp .nf .ft C salt \-t 60 .ft P .fi .sp For best results, combine all three: .sp .nf .ft C salt\-minion \-l debug & # On the minion salt \(aq*\(aq state.highstate \-t 60 # On the master .ft P .fi .RE .SS Next steps .sp This tutorial focused on getting a simple Salt States configuration working. \fBPart 2\fP will build on this example to cover more advanced \fIsls\fP syntax and will explore more of the states that ship with Salt. .SH STATES TUTORIAL, PART 2 .sp This tutorial builds on the topic covered in \fBpart 1\fP. It is recommended that you begin there. .sp In the last Salt States tutorial we covered the basics of installing a package. In this tutorial we will modify our \fBwebserver.sls\fP file to be more complicated, have requirements, and use even more Salt States. .SS Call multiple States .sp You can specify multiple \fIstate declarations\fP under an \fIID declaration\fP. For example, a quick modification to our \fBwebserver.sls\fP to also start Apache if it is not running: .sp .nf .ft C apache: pkg: \- installed service: \- running .ft P .fi .sp Try stopping Apache before running \fBstate.highstate\fP once again and observe the output. .SS Expand the SLS module .sp As you have seen, sls modules are appended with the file extension \fB.sls\fP and are referenced by name starting at the root of the state tree. An SLS module can be also defined as a directory. Demonstrate that now by creating a directory named \fBwebserver\fP and moving and renaming \fBwebserver.sls\fP to \fBwebserver/init.sls\fP. Your state directory should now resemble: .sp .nf .ft C |\- top.sls \(ga\- webserver/ \(ga\- init.sls .ft P .fi .IP "Organizing SLS modules" .sp You can place additional \fB.sls\fP files in a state file directory. This affords much cleaner organization of your state tree on the filesystem. For example, if we created a \fBwebserver/django.sls\fP file that module would be referenced as \fBwebserver.django\fP. .sp In addition, States provide powerful includes and extending functionality which we will cover in \fBPart 3\fP. .RE .SS Require other states .sp We now have a working installation of Apache so let\(aqs add an HTML file to customize our website. It isn\(aqt exactly useful to have a website without a webserver so we don\(aqt want Salt to install our HTML file until Apache is installed and running. Include the following at the bottom of your \fBwebserver/init.sls\fP file: .sp .nf .ft C apache: pkg: \- installed service: \- running /var/www/index.html: # ID declaration file: # state declaration \- managed # function \- source: salt://webserver/index.html # function arg \- require: # requisite declaration \- pkg: apache # requisite reference .ft P .fi .sp \fBline 7\fP is the \fIID declaration\fP. In this example it is the location we want to install our custom HTML file. (\fBNote:\fP the default location that Apache serves may differ from the above on your OS or distro. \fB/srv/www\fP could also be a likely place to look.) .sp \fBLine 8\fP the \fIstate declaration\fP. This example uses the Salt \fBfile state\fP. .sp \fBLine 9\fP is the \fIfunction declaration\fP. The \fBmanaged function\fP will download a file from the master and install it in the location specified. .sp \fBLine 10\fP is a \fIfunction arg declaration\fP which, in this example, passes the \fBsource\fP argument to the \fBmanaged function\fP. .sp \fBLine 11\fP is a \fIrequisite declaration\fP. .sp \fBLine 12\fP is a \fIrequisite reference\fP which refers to a state and an ID. In this example, it is referring to the \fBID declaration\fP from our example in \fBpart 1\fP. This declaration tells Salt not to install the HTML file until Apache is installed. .sp Next, create the \fBindex.html\fP file and save it in the \fBwebserver\fP directory: .sp .nf .ft C Salt rocks

This file brought to you by Salt

.ft P .fi .sp Last, call \fBstate.highstate\fP again and the minion will fetch and execute the highstate as well as our HTML file from the master using Salt\(aqs File Server: .sp .nf .ft C salt \(aq*\(aq state.highstate .ft P .fi .sp Verify that Apache is now serving your custom HTML. .IP "\fBrequire\fP vs. \fBwatch\fP" .sp There are two \fIrequisite declarations\fP, “require” and “watch”. Not every state supports “watch”. The \fBservice state\fP does support “watch” and will restart a service based on the watch condition. .sp For example, if you use Salt to install an Apache virtual host configuration file and want to restart Apache whenever that file is changed you could modify our Apache example from earlier as follows: .sp .nf .ft C /etc/httpd/extra/httpd\-vhosts.conf: file: \- managed \- source: salt://webserver/httpd\-vhosts.conf apache: pkg: \- installed service: \- running \- watch: \- file: /etc/httpd/extra/httpd\-vhosts.conf .ft P .fi .sp If the pkg and service names differ on your OS or distro of choice you can specify each one separately using a \fIname declaration\fP which explained in \fBPart 3\fP. .RE .SS Next steps .sp In \fBpart 3\fP we will discuss how to use includes, extends and templating to make hugely complicated State Tree configurations dead\-simple. .SH STATES TUTORIAL, PART 3 .sp This tutorial builds on the topic covered in \fBpart 2\fP. It is recommended that you begin there. .sp This tutorial will cover more advanced templating and configuration techniques for \fBsls\fP files. .SS Templating SLS modules .sp SLS modules may require programming logic or inline executions. This is accomplished with module templating. The default module templating system used is \fI\%Jinja2\fP and may be configured by changing the \fBrenderer\fP value in the master config. .sp All states are passed through a templating system when they are initially read, so all that is required to make use of the templating system is to add some templating code. An example of an sls module with templating may look like this: .sp .nf .ft C {% for usr in \(aqmoe\(aq,\(aqlarry\(aq,\(aqcurly\(aq %} {{ usr }}: user: \- present {% endfor %} .ft P .fi .sp This templated sls file once generated will look like this: .sp .nf .ft C moe: user: \- present larry: user: \- present currly: user: \- present .ft P .fi .SS Using Grains in SLS modules .sp Often times a state will need to behave differently on different systems. \fBSalt grains\fP can be used from within sls modules. An object called \fBgrains\fP is made available in the template context: .sp .nf .ft C apache: pkg: {% if grains[\(aqos\(aq] == \(aqRedHat\(aq %} \- name: httpd {% elif grains[\(aqos\(aq] == \(aqUbuntu\(aq %} \- name: apache2 {% endif %} \- installed .ft P .fi .SS Calling Salt modules from templates .sp All of the Salt modules loaded by the minion are available within the templating system. This allows data to be gathered in real time on the target system. It also allows for shell commands to be run easily from within the sls modules. .sp The Salt module functions are also made available in the template context as \fBsalt\fP: .sp .nf .ft C {% for usr in \(aqmoe\(aq,\(aqlarry\(aq,\(aqcurly\(aq %} {{ usr }}: group: \- present user: \- present \- gid: {{ salt[\(aqfile.group_to_gid\(aq](usr) }} \- require: \- group: {{ usr }} {% endfor %} .ft P .fi .sp Below is an example that uses the \fBnetwork.hwaddr\fP function to retrieve the MAC address for eth0: .INDENT 0.0 .INDENT 3.5 salt[\(aqnetwork.hwaddr\(aq](\(aqeth0\(aq) .UNINDENT .UNINDENT .SS Advanced SLS module syntax .sp Last we will cover some incredibly useful techniques for more complex State trees. .SS \fIInclude declaration\fP .sp You have seen an example of how to spread a Salt tree across several files but in order to be able to have \fIrequisite references\fP span multiple files you must use an \fIinclude declaration\fP. For example: .sp \fBpython\-libs.sls\fP: .sp .nf .ft C python\-dateutil: pkg: \- installed .ft P .fi .sp \fBdjango.sls\fP: .sp .nf .ft C include: \- python\-libs django: pkg: \- installed \- require: \- pkg: python\-dateutil .ft P .fi .SS \fIExtend declaration\fP .sp You can modify previous declarations by using an \fIextend declaration\fP. For example the following modifies the Apache tree to also restart Apache when the vhosts file is changed: .sp \fBapache.sls\fP: .sp .nf .ft C apache: pkg: \- installed .ft P .fi .sp \fBmywebsite.sls\fP: .sp .nf .ft C include: \- apache extend: apache: service: \- watch: \- file: /etc/httpd/extra/httpd\-vhosts.conf /etc/httpd/extra/httpd\-vhosts.conf: file: \- managed \- source: salt://httpd\-vhosts.conf .ft P .fi .SS \fIName declaration\fP .sp You can override the \fIID declaration\fP by using a \fIname declaration\fP. For example, the previous example is a bit more maintainable if rewritten as follows: .sp \fBmywebsite.sls\fP: .sp .nf .ft C include: \- apache extend: apache service: \- watch: \- file: mywebsite mywebsite: file: \- managed \- name: /etc/httpd/extra/httpd\-vhosts.conf \- source: salt://httpd\-vhosts.conf .ft P .fi .SS \fINames declaration\fP .sp Even more powerful is using a \fInames declaration\fP to override the \fIID declaration\fP for multiple states at once. This often can remove the need for looping in a template. For example, the first example in this tutorial can be rewritten without the loop: .sp .nf .ft C stooges: user: \- present \- names: \- moe \- larry \- curly .ft P .fi .SS Continue learning .sp The best way to continue learning about Salt States is to read through the \fBreference documentation\fP and to look through examples of existing \fIstate trees\fP. You can find examples in the \fI\%salt-states repository\fP and please send a pull\-request on GitHub with any state trees that you build and want to share! .sp If you have any questions, suggestions, or just want to chat with other people who are using Salt we have an \fBactive community\fP. .SH OPENING THE FIREWALL UP FOR SALT .sp The Salt master communicates with the minions using an AES\-encrypted ZeroMQ connection. These communications are done over ports 4505 and 4506, which need to be accessible on the master only. This document outlines suggested firewall rules for allowing these incoming connections to the master. .IP Note \fBNo firewall configuration needs to be done on Salt minions. These changes refer to the master only.\fP .RE .SS iptables .sp Different Linux distributions store their iptables rules in different places, which makes it difficult to standardize firewall documentation. I\(aqve included some of the more common locations, but your mileage may vary. .sp \fBFedora / Red Hat / CentOS\fP .sp .nf .ft C /etc/sysconfig/iptables .ft P .fi .sp \fBArch Linux\fP .sp .nf .ft C /etc/iptables/iptables.rules .ft P .fi .sp \fBDebian\fP .sp Follow these instructions: \fI\%http://wiki.debian.org/iptables\fP .sp Once you\(aqve found your firewall rules, you\(aqll need to add the two lines below to allow traffic on \fBtcp/4505\fP and \fBtcp/4506\fP: .sp .nf .ft C + \-A INPUT \-m state \-\-state new \-m tcp \-p tcp \-\-dport 4505 \-j ACCEPT + \-A INPUT \-m state \-\-state new \-m tcp \-p tcp \-\-dport 4506 \-j ACCEPT .ft P .fi .sp \fBUbuntu\fP .sp Create a file named \fB/etc/ufw/applications.d/salt\-master\fP .sp .nf .ft C [Salt Master] title=Salt master description=Salt is a remote execution and configuration management tool. ports=4205,4206/tcp .ft P .fi .SS pf.conf .sp The BSD\-family of operating systems uses packet filter (pf). The following example describes the additions to \fBpf.conf\fP needed to access the Salt master. .sp .nf .ft C + pass in on $int_if proto tcp from any to $int_if port 4505 + pass in on $int_if proto tcp from any to $int_if port 4506 .ft P .fi .sp Once you\(aqve made these additions to your \fBpf.conf\fP you\(aqll need to reload the new rules with the new additions. This can be done using the \fBpfctl\fP command. .sp .nf .ft C pfctl \-vf /etc/pf.conf .ft P .fi .SH BOOSTRAPPING SALT ON LINUX EC2 WITH CLOUD-INIT .sp \fI\%Salt\fP is a great tool for remote execution and configuration management, however you will still need to bootstrap the daemon when spinning up a new node. One option is to create and save a custom AMI, but this creates another resource to maintain and document. .sp A better method for Linux machines uses Canonical\(aqs \fI\%CloudInit\fP to run a bootstrap script during an EC2 Instance initialization. Cloud\-init takes the \fBuser_data\fP string passed into a new AWS instance and runs it in a manner similar to rc.local. The bootstrap script needs to: .INDENT 0.0 .IP 1. 3 Install \fI\%Salt\fP with dependencies .IP 2. 3 Point the minion to the master .UNINDENT .sp Here is a sample script: .sp .nf .ft C #!/bin/bash # Install saltstack add\-apt\-repository ppa:saltstack/salt \-y apt\-get update \-y apt\-get install salt \-y apt\-get upgrade \-y # Set salt master location and start minion cp /etc/salt/minion.template /etc/salt/minion sed \-i \(aq\(aq \-e \(aqs/#master: salt/master: [salt_master_fqdn]\(aq /etc/salt/minion salt\-minion \-d .ft P .fi .sp First the script adds the saltstack ppa and installs the package. Then we copy over the minion config template and tell it where to find the master. You will have to replace \fB[salt_master_fqdn]\fP with something that resolves to your salt master. .SS Used With Boto .sp \fI\%Boto\fP will accept a string for user data which can be used to pass our bootstrap script. If the script is saved to a file, you can read it into a string: .sp .nf .ft C import boto user_data = open(\(aqsalt_bootstrap.sh\(aq) conn = boto.connect_ec2(, ) reservation = conn.run_instances(image_id=, key_name=, user_data=user_data.read()) .ft P .fi .SS Additional Notes .sp Sometime in the future the ppa will include and install an upstart file. In the meantime, you can use the bootstrap to \fI\%build one\fP. .sp It may also be useful to set the node\(aqs role during this phase. One option would be saving the node\(aqs role to a file and then using a custom grain to select it. .SH PILLAR OF SALT .sp Pillar is an interface for Salt designed to offer global values to be distributed to all minions. Pillar data is managed in a similar way to the salt state tree. .sp Pillar was added to Salt in version 0.9.8 as an experimental add on. .SS Declaring the Master Pillar .sp The Salt Master server maintains a pillar_roots setup that matches the structure of the file_roots used in the Salt file server. Like the Salt file server the \fBpillar_roots\fP option in the master config is based on environments mapping to directories. The pillar data is then mapped to minions based on matchers in a top file which is laid out in the same way as the state top file. .sp The configuration for the pillar_roots in the master config is identical in behavior and function as the file_roots configuration: .sp .nf .ft C pillar_roots: base: \- /srv/pillar .ft P .fi .sp This example configuration declares that the base environment will be located in the /srv/pillar directory. The top file used matches the name of the top file used for states, and has the same structure: .sp .nf .ft C base: \(aq*\(aq: \- packages .ft P .fi .sp This simple pillar top file declares that information for all minions can be found in the package\(aqs sls file: .sp .nf .ft C {% if grains[\(aqos\(aq] == \(aqRedHat\(aq %} apache: httpd git: git {% elif grains[\(aqos\(aq] == \(aqDebian\(aq %} apache: apache2 git: git\-core {% endif %} .ft P .fi .sp Now this data can be used from within modules, renderers, state sls files and more via the shared pillar dict: .sp .nf .ft C apache: pkg: \- installed \- name: {{ pillar[\(aqapache\(aq] }} .ft P .fi .sp .nf .ft C git: pkg: \- installed \- name: {{ pillar[\(aqgit\(aq] }} .ft P .fi .SH JOB MANAGEMENT .sp New in version 0.9.7. .sp Since Salt executes jobs running on many systems, Salt needs to be able to manage jobs running on many systems. As of Salt 0.9.7 the capability was added for more advanced job management. .SS The Minion proc System .sp The Salt Minions now maintain a proc directory in the salt cachedir, the proc directory maintains files named after the executed job id. These files contain the information about the current running jobs on the minion and allow for jobs to be looked up. This is located in the proc directory under the cachedir, with a default configuration it is under /var/cache/salt/proc. .SS Functions in the saltutil Module .sp Salt 0.9.7 introduced a few new functions to the \fBsaltutil\fP module for managing jobs. These functions are: .INDENT 0.0 .IP 1. 3 \fBrunning\fP Returns the data of all running jobs that are found in the proc directory. .IP 2. 3 \fBfind_job\fP Returns specific data about a certain job based on job id. .IP 3. 3 \fBsignal_job\fP Allows for a given jid to be sent a signal. .IP 4. 3 \fBterm_job\fP Sends a termination signal (SIGTERM, 15) to the process controlling the specified job. .IP 5. 3 \fBkill_job\fP Sends a kill signal (SIGKILL, 9) to the process controlling the specified job. .UNINDENT .sp These functions make up the core of the back end used to manage jobs at the minion level. .SS The jobs Runner .sp A convenience runner front end and reporting system has been added as well. The jobs runner contains functions to make viewing data easier and cleaner. .sp The jobs runner contains a number of functions... .SS active .sp The active function runs saltutil.running on all minions and formats the return data about all running jobs in a much more usable and compact format. The active function will also compare jobs that have returned and jobs that are still running, making it easier to see what systems have completed a job and what systems are still being waited on. .SS lookup_jid .sp When jobs are executed the return data is sent back to the master and cached. By default is is cached for 24 hours, but this can be configured via the \fBkeep_jobs\fP option in the master configuration. Using the lookup_jid runner will display the same return data that the initial job invocation with the salt command would display. .SS list_jobs .sp Before finding a historic job, it may be required to find the job id. list_jobs will parse the cached execution data and display all of the job data for jobs that have already, or partially returned. .SH TROUBLESHOOTING .sp The intent of the troubleshooting section is to introduce solutions to a number of common issues encountered by users and the tools that are available to aid in developing states and salt code. .SS Running in the Foreground .sp A great deal of information is available via the debug logging system, if you are having issues with minions connecting or not starting run the minion and/or master in the foreground: .sp .nf .ft C # salt\-master \-l debug # salt\-minion \-l debug .ft P .fi .SS What Ports do the Master and Minion Need Open? .sp No ports need to be opened up on each minion. For the master, tcp ports 4505 and 4506 need to be open. If you\(aqve put your salt master and minion both in debug mode and don\(aqt see an acknowledgement that your minion has connected, it could very well be a firewall. .sp You can check port connectivity from the minion with the nc command: .sp .nf .ft C # nc \-v \-z salt.master.ip 4505 # nc \-v \-z salt.master.ip 4506 .ft P .fi .sp There is also a \fBfirewall configuration\fP document that might help as well. .SS Using salt\-call .sp The \fBsalt\-call\fP command was originally developed for aiding in the development of new salt modules. Since then many applications have arisen for the salt\-call command that is bundled with the salt minion. These range from the original intent of the salt\-call, development assistance, to gathering large amounts of data from complex calls like \fBstate.highstate\fP. .sp When developing the state tree it is generally recommended to invoke state.highstate with salt\-call, this displays a great deal more information about the highstate execution than if it is called remotely. .SS Too many open files .sp The salt\-master needs at least 2 sockets per host that connects to it, one for the Publisher and one for response port. Thus, large installations may upon scaling up the number of minions accessing a given master, encounter: .sp .nf .ft C 12:45:29,289 [salt.master ][INFO ] Starting Salt worker process 38 Too many open files sock != \-1 (tcp_listener.cpp:335) .ft P .fi .sp The solution to this would be to check the number of files allowed to be opened by the user running salt\-master (root by default): .sp .nf .ft C [root@salt\-master ~]# ulimit \-n 1024 .ft P .fi .sp And modify that value to be at least equal to the number of minions x 2. This setting can be changed in limits.conf as the nofile value(s), and activated upon new a login of the specified user. .sp So, an environment with 1800 minions, would need 1800 x 2 = 3600 as a minimum. .SS Salt Master Stops Responding .sp There are known bugs with ZeroMQ less than 2.1.11 which can cause the salt master to not respond properly. If you\(aqre running ZeroMQ greater than or equal to 2.1.9, you can work around the bug by setting the sysctls \fBnet.core.rmem_max\fP and \fBnet.core.wmem_max\fP to 16777216. Next set the third field in \fBnet.ipv4.tcp_rmem\fP and \fBnet.ipv4.tcp_wmem\fP to at least 16777216. .sp You can do it manually with something like: .sp .nf .ft C # echo 16777216 > /proc/sys/net/core/rmem_max # echo 16777216 > /proc/sys/net/core/wmem_max # echo "4096 87380 16777216" > /proc/sys/net/ipv4/tcp_rmem # echo "4096 87380 16777216" > /proc/sys/net/ipv4/tcp_wmem .ft P .fi .sp Or with the following salt state: .sp .nf .ft C net.core.rmem_max: sysctl: \- present \- value: 16777216 net.core.wmem_max: sysctl: \- present \- value: 16777216 net.ipv4.tcp_rmem: sysctl: \- present \- value: 4096 87380 16777216 net.ipv4.tcp_wmem: sysctl: \- present \- value: 4096 87380 16777216 .ft P .fi .SS Common YAML Gotchas .sp An extensive list of \fByaml idiosyncrasies\fP has been compiled. .SH YAML IDIOSYNCRASIES .sp One of Salt\(aqs strengths, the use of existing serialization systems for representing sls data, can also backfire. YAML is a general purpose system and there are a number of things that would seem to make sense in an sls file that cause YAML issues. It is wise to be aware of these issues. While reports or running into them are generally rare they can still crop up at unexpected times. .SS Spaces vs Tabs .sp Yaml uses spaces, period. Do not use tabs in your sls files! If strange errors are coming up in rendering sls files, make sure to check that no tabs have crept in! In vi / vim, you can check with \fB:se spell\fP. .SS Indentation .sp The suggested syntax for YAML files is to use 2 spaces for indentation, but YAML will follow whatever indentation system that the individual file uses. Indentation of two spaces works very well for sls files given the fact that the data is uniform and not deeply nested. .SS Nested Dicts (key=value) .sp When dicts are more deeply nested they no longer follow the same indentation logic. This is rarely something that comes up in Salt, since deeply nested options like these are discouraged when making state modules, but some do exist. A good example is the context and default options in the \fBfile.managed\fP state: .sp .nf .ft C /etc/http/conf/http.conf: file: \- managed \- source: salt://apache/http.conf \- user: root \- group: root \- mode: 644 \- template: jinja \- context: custom_var: "override" \- defaults: custom_var: "default value" other_var: 123 .ft P .fi .sp Notice that the spacing used is 2 spaces, and that when defining the context and defaults options there is a 4 space indent. If only a 2 space indent is used then the information will not be loaded correctly. If using double spacing is not desirable, then a deeply nested dict can be declared with curly braces: .sp .nf .ft C /etc/http/conf/http.conf: file: \- managed \- source: salt://apache/http.conf \- user: root \- group: root \- mode: 644 \- template: jinja \- context: { custom_var: "override" } \- defaults: { custom_var: "default value" other_var: 123 } .ft P .fi .SS Integers are Parsed as Integers .sp When passing integers into an sls file, they are passed as integers. This means that if a state accepts a string value and an integer is passed, that an integer will be sent. The solution here is to send the integer as a string. .sp This is best explained when setting the mode for a file: .sp .nf .ft C /etc/vimrc: file: \- managed \- source: salt://edit/vimrc \- user: root \- group: root \- mode: 644 .ft P .fi .sp Salt manages this well, since the mode is passed as 644, but if the mode is zero padded as 0644, then it is read by YAML as an integer and evaluated as a hexadecimal value, 0644 becomes 420. Therefore, if the file mode is preceded by a 0 then it needs to be passed as a string: .sp .nf .ft C /etc/vimrc: file: \- managed \- source: salt://edit/vimrc \- user: root \- group: root \- mode: \(aq0644\(aq .ft P .fi .SH COMMUNITY .sp Join the Salt! .sp There are many ways to participate in and communicate with the Salt community. .sp Salt has an active IRC channel and a mailing list. .SS Mailing List .sp Join the \fI\%salt-users mailing list\fP. It is the best place to ask questions about Salt and see whats going on with Salt development! The Salt mailing list is hosted by Google Groups. It is open to new members. .sp \fI\%http://groups.google.com/group/salt-users\fP .SS IRC .sp The \fB#salt\fP IRC channel is hosted on the popular \fI\%Freenode\fP network. You can use the \fI\%Freenode webchat client\fP right from your browser. .sp \fI\%Logs of the IRC channel activity\fP are being collected courtesy of Moritz Lenz. .SS Follow on Github .sp The Salt code is developed via Github. Follow Salt for constant updates on what is happening in Salt development: .sp \fI\%https://github.com/saltstack/salt\fP .SS The Red45 Blog .sp News and thoughts on Salt and related projects is often posted on Thomas\(aq blog \fI\%The Red45\fP: .sp \fI\%http://red45.wordpress.com/\fP .SS Example Salt States .sp The official \fBsalt\-states\fP repository is: \fI\%https://github.com/saltstack/salt-states\fP .sp Another good example from one of our users is: \fI\%https://github.com/blast-hardcheese/blast-salt-states\fP .SS Follow on ohloh .sp \fI\%https://www.ohloh.net/p/salt\fP .SS Developing Salt .sp If you want to help develop Salt there is a great need and your patches are welcome! .sp To assist in Salt development, you can help in a number of ways. .SS Posting patches to the mailing list .sp If you have a patch for Salt, please format it via \fBgit format\-patch\fP and send it to the Salt users mailing list. This allows the patch to give you the contributor the credit for your patch, and gives the Salt community an archive of the patch and a place for discussion. .SS Setting a Github pull request .sp This is probably the preferred method for contributions, simply create a Github fork, commit your changes to the fork, and then open up a pull request. .SS Contributions Welcome! .sp The goal here it to make contributions clear, make sure there is a trail for where the code has come from, but most importantly, to give credit where credit is due! .SH INTRODUCTION TO EXTENDING SALT .sp Salt is made to be used, and made to be extended. The primary goal of Salt is to provide a foundation which can be used to solve problems. And the goal of Salt is to not assume what those problems might be. .sp One of the greatest benefit of developing Salt has been the vast array of ways in which people have wanted to use it, while the original intention was as a communication layer for a cloud controller Salt has been extended to facilitate so much more. .SS Client API .sp The primary interface used to extend salt, is to simply use it. Salt executions can be called via the Salt client api, making programming master side solutions with Salt is easy. .SS Adding Loadable Plugins .sp Salt is comprised of a core platform that loads many types of easy to write plugins. The idea is to enable all of the breaking points in the salt processes to have a point of pluggable interaction. This means that all of the main features of Salt can be extended, modified or used. .sp The breaking points and helping interfaces span from convenience master side executions to manipulating the flow of how data is handled by Salt. .SS Minion Execution Modules .sp The minion execution modules or just \fBmodules\fP are the core to what salt is and does. These modules are found in: .sp \fI\%https://github.com/saltstack/salt/blob/v0.9.8/salt/modules\fP .sp These modules are what is called by the salt command line and the salt client api. Adding modules is done by simply adding additional python modules to the modules directory and restarting the minion. .SS Grains .sp Salt grains, or "grains of truth" are bits of static information that are generated when the minion starts. This information is useful when determining what package manager to default to, or where certain configuration files are stored on the minion. .sp The Salt grains are the interface used for auto detection and dynamic assignment of execution modules and types to specific salt minions. .sp The code used to generate the Salt grains can be found here: .sp \fI\%https://github.com/saltstack/salt/blob/v0.9.8/salt/grains\fP .SS States .sp Salt supports state enforcement, this makes Salt a high speed and very efficient solution for system configuration management. .sp States can be easily added to Salt by dropping a new state module in: .sp \fI\%https://github.com/saltstack/salt/blob/v0.9.8/salt/states\fP .SS Renderers .sp Salt states are controlled by simple data structures, these structures can be abstracted in a number of ways. While the default is to be in a yaml file wrapped in a jinja template, any abstraction can be used. This means that any format that can be dreamed is possible, so long as a renderer is written for it. .sp The existing renderers can be found here: .sp \fI\%https://github.com/saltstack/salt/blob/v0.9.8/salt/renderers\fP .SS Returners .sp The salt commands all produce a return value, that return value is sent to the salt master by default, but it can be sent anywhere. The returner interface makes it programmatically possible for the information to be sent to anything from an SQL or NOSQL database, to a custom application made to use Salt. .sp The existing returners can be found here: .sp \fI\%https://github.com/saltstack/salt/blob/v0.9.8/salt/returners\fP .SS Runners .sp Sometimes a certain application can be made to execute and run from the existing salt command line. This is where the salt runners come into play. The Salt Runners what is called by the salt\-run command and are meant to act as a generic interface for encapsulating master side executions. .sp Existing Salt runners are located here: .sp \fI\%https://github.com/saltstack/salt/blob/v0.9.8/salt/runners\fP .SH MODULES .sp Salt modules are the functions called by the \fBsalt\fP command. .IP "See also" .sp \fIFull list of builtin modules\fP .sp Salt ships with many modules that cover a wide variety of tasks. .RE .SS Easy Modules to write .sp Salt modules are amazingly simple to write, just write a regular Python module or a regular Cython module and place it in the \fBsalt/modules\fP directory. You can also place them in a directory called \fB_modules/\fP in your state directory. .sp Since Salt modules are just Python/Cython modules there are no restraints as to what you can put inside of a salt module, and if a Salt module has errors and cannot import the Salt minion will continue to load without issue, the module with errors will simply be omitted. .sp If adding a Cython module the file must be named \fB.pyx\fP so that the loader knows that the module needs to be imported as a Cython module. The compilation of the Cython module is automatic and happens when the minion starts, so only the \fB*.pyx\fP file is required. .SS Cross Calling Modules .sp All of the salt modules are available to each other, and can be "cross called". This means that when creating a module functions in modules which already exist can be called. .sp The variable \fB__salt__\fP is packed into the modules after they are loaded into the salt minion. This variable is a python dictionary of all of the salt functions, laid out in the same way that they are made available to the salt command. .sp Salt modules can be cross called by accessing the value in the \fB__salt__\fP dict: .sp .nf .ft C def foo(bar): return __salt__[\(aqcmd.run\(aq](bar) .ft P .fi .sp This code will call the Salt cmd module\(aqs run function and pass the argument \fBbar\fP. .SS Preloaded Modules Data .sp When interacting with modules often it is nice to be able to read information dynamically about the minion, or load in configuration parameters for a module. Salt allows for different types of data to be loaded into the modules by the minion, as of this writing Salt loads information gathered from the Salt Grains system and from the minion configuration file. .SS Grains Data .sp The Salt minion detects information about the system when started. This allows for modules to be written dynamically with respect to the underlying hardware and OS. This information is referred to as Salt Grains, or "grains of salt". The Grains system was introduced to replace Facter, since relying on a Ruby application from a Python application was both slow and inefficient. Grains support replaces Facter in all releases after 0.8 .sp The values detected by the Salt Grains on the minion are available in a dict by the name of \fB__grains__\fP and can be accessed from within callable objects in the Python modules. .sp To see the contents of the grains dict for a given system in your deployment run the \fBgrains.items()\fP function: .sp .nf .ft C salt \(aqhostname\(aq grains.items .ft P .fi .sp To use the \fB__grains__\fP dict simply call it as a Python dict from within your code, an excellent example is available in the Grains module: \fBsalt.modules.grains\fP. .SS Module Configuration .sp Since parameters for configuring a module may be desired, Salt allows for configuration information stored in the main minion config file to be passed to the modules. .sp Since the minion configuration file is a yaml document, arbitrary configuration data can be passed in the minion config that is read by the modules. It is \fBstrongly\fP recommended that the values passed in the configuration file match the module. This means that a value intended for the \fBtest\fP module should be named \fBtest.\fP. .sp Configuration also requires that default configuration parameters need to be loaded as well. This can be done simply by adding the \fB__opts__\fP dict to the top level of the module. .sp The test module contains usage of the module configuration, and the default configuration file for the minion contains the information and format used to pass data to the modules. \fBsalt.modules.test\fP, \fBconf/minion\fP. .SS Printout Configuration .sp Since module functions can return different data, and the way the data is printed can greatly change the presentation, Salt has a printout configuration. .sp When writing a module the \fB__outputter__\fP dict can be declared in the module. The \fB__outputter__\fP dict contains a mapping of function name to Salt Outputter. .sp .nf .ft C __outputter__ = { \(aqrun\(aq: \(aqtxt\(aq } .ft P .fi .sp This will ensure that the text outputter is used. .SS Virtual Modules .sp Sometimes a module should be presented in a generic way. A good example of this can be found in the package manager modules. The package manager changes from one operating system to another, but the salt module that interfaces with the package manager can be presented in a generic way. .sp The salt modules for package managers all contain a \fB__virtual__\fP function which is called to define what systems the module should be loaded on. .sp The \fB__virtual__\fP function is used to return either a string or False. If False is returned then the module is not loaded, if a string is returned then the module is loaded with the name of the string. .sp This means that the package manager modules can be presented as the pkg module regardless of what the actual module is named. .sp The package manager modules are the best example of using the \fB__virtual__\fP function: \fI\%https://github.com/saltstack/salt/blob/v0.9.8/salt/modules/pacman.py\fP \fI\%https://github.com/saltstack/salt/blob/v0.9.8/salt/modules/yumpkg.py\fP \fI\%https://github.com/saltstack/salt/blob/v0.9.8/salt/modules/apt.py\fP .SS Documentation .sp Salt modules are self documenting, the \fBsys.doc()\fP function will return the documentation for all available Facter modules: .sp .nf .ft C salt \(aq*\(aq sys.doc .ft P .fi .sp This function simple prints out the docstrings found in the modules, when writing salt modules, please follow the formating conventions for docstrings as they appear in the other modules. .SS Adding Documentation to Salt Modules .sp Since life is much better with documentation, it is strongly suggested that all Salt modules have documentation added. Any Salt modules submitted for inclusion in the main distribution of Salt will be required to have documentation. .sp Documenting Salt modules is easy! Just add a python docstring to the function. .sp .nf .ft C def spam(eggs): \(aq\(aq\(aq A function to make some spam with eggs! CLI Example: salt \(aq*\(aq test.spam eggs \(aq\(aq\(aq return eggs .ft P .fi .sp Now when the sys.doc call is executed the docstring will be cleanly returned to the calling terminal. .SS How Functions are Read .sp In Salt Python callable objects contained within a module are made available to the Salt minion for use. The only exception to this rule is a callable object with a name starting with an underscore \fB_\fP. .SS Objects Loaded Into the Salt Minion .sp .nf .ft C def foo(bar): return bar class baz: def __init__(self, quo): return quo .ft P .fi .SS Objects NOT Loaded into the Salt Minion .sp .nf .ft C def _foobar(baz): # Preceded with an _ return baz cheese = {} # Not a callable python object .ft P .fi .SS Examples of Salt Modules .sp The existing Salt modules should be fairly easy to read and understand, the goal of the main distribution\(aqs Salt modules is not only to build a set of functions for salt, but to stand as examples for building out more Salt modules. .sp The existing modules can be found here: \fI\%https://github.com/saltstack/salt/blob/v0.9.8/salt/modules\fP .sp The most simple module is the test module, it contains the simplest salt function, test.ping: .sp .nf .ft C def ping(): \(aq\(aq\(aq Just used to make sure the minion is up and responding Return True CLI Example: salt \(aq*\(aq test.ping \(aq\(aq\(aq return True .ft P .fi .SH FULL LIST OF BUILTIN MODULES .IP "Virtual modules" .SS salt.modules.pkg .sp \fBpkg\fP is a virtual module that is fulfilled by one of the following modules: .INDENT 0.0 .IP \(bu 2 \fBsalt.modules.apt\fP .IP \(bu 2 \fBsalt.modules.ebuild\fP .IP \(bu 2 \fBsalt.modules.freebsdpkg\fP .IP \(bu 2 \fBsalt.modules.pacman\fP .IP \(bu 2 \fBsalt.modules.yumpkg\fP .IP \(bu 2 \fBsalt.modules.yumpkg5\fP .IP \(bu 2 \fBsalt.modules.zypper\fP .UNINDENT .SS salt.modules.sys .sp The regular salt modules execute in a separate context from the salt minion and manipulating the actual salt modules needs to happen in a higher level context within the minion process. This is where the sys pseudo module is used. .sp The sys pseudo module comes with a few functions that return data about the available functions on the minion or allows for the minion modules to be refreshed. These functions are as follows: .INDENT 0.0 .TP .B salt.modules.sys.doc([module[, module.function]]) Display the inline documentation for all available modules, or for the specified module or function. .UNINDENT .INDENT 0.0 .TP .B salt.modules.sys.reload_modules() Instruct the minion to reload all available modules in memory. This function can be called if the modules need to be re\-evaluated for availability or new modules have been made available to the minion. .UNINDENT .INDENT 0.0 .TP .B salt.modules.sys.list_modules() List all available (loaded) modules. .UNINDENT .INDENT 0.0 .TP .B salt.modules.sys.list_functions() List all known functions that are in available (loaded) modules. .UNINDENT .RE .TS center; |l|l|. _ T{ \fBapache\fP T} T{ Support for Apache T} _ T{ \fBapt\fP T} T{ Support for APT (Advanced Packaging Tool) T} _ T{ \fBarchive\fP T} T{ A module to wrap archive calls T} _ T{ \fBbutterkvm\fP T} T{ Specialized routines used by the butter cloud component T} _ T{ \fBcluster\fP T} T{ The cluster module is used to distribute and activate salt HA cluster T} _ T{ \fBcmdmod\fP T} T{ A module for shelling out T} _ T{ \fBcp\fP T} T{ Minion side functions for salt\-cp T} _ T{ \fBcron\fP T} T{ Work with cron T} _ T{ \fBdata\fP T} T{ Manage a local persistent data structure that can hold any arbitrairy data T} _ T{ \fBdebconfmod\fP T} T{ Support for Debconf T} _ T{ \fBdisk\fP T} T{ Module for gathering disk information T} _ T{ \fBebuild\fP T} T{ Support for Portage T} _ T{ \fBfile\fP T} T{ Manage information about files on the minion, set/read user, group, and mode T} _ T{ \fBfreebsdkmod\fP T} T{ Module to manage FreeBSD kernel modules T} _ T{ \fBfreebsdpkg\fP T} T{ Package support for FreeBSD T} _ T{ \fBfreebsdservice\fP T} T{ The service module for FreeBSD T} _ T{ \fBgem\fP T} T{ Manage ruby gems. T} _ T{ \fBgentoo_service\fP T} T{ Top level package command wrapper, used to translate the os detected by the T} _ T{ \fBgit\fP T} T{ Support for the Git SCM T} _ T{ \fBgrains\fP T} T{ Control aspects of the grains data T} _ T{ \fBgroupadd\fP T} T{ Manage groups on Linux T} _ T{ \fBhg\fP T} T{ Support for the Mercurial SCM T} _ T{ \fBhosts\fP T} T{ Manage the information in the hosts file T} _ T{ \fBkmod\fP T} T{ Module to manage Linux kernel modules T} _ T{ \fBkvm_hyper\fP T} T{ Provide the hyper module for kvm hypervisors. T} _ T{ \fBlinux_sysctl\fP T} T{ Module for viewing and modifying sysctl parameters T} _ T{ \fBmdadm\fP T} T{ Salt module to manage RAID arrays with mdadm T} _ T{ \fBmoosefs\fP T} T{ Module for gathering and managing information about MooseFS T} _ T{ \fBmount\fP T} T{ Salt module to manage unix mounts and the fstab file T} _ T{ \fBmysql\fP T} T{ Module to provide MySQL compatibility to salt. T} _ T{ \fBnetwork\fP T} T{ Module for gathering and managing network information T} _ T{ \fBnginx\fP T} T{ Support for nginx T} _ T{ \fBpacman\fP T} T{ A module to wrap pacman calls, since Arch is the best T} _ T{ \fBpillar\fP T} T{ Extract the pillar data for this minion T} _ T{ \fBpip\fP T} T{ Install Python packages with pip to either the system or a virtualenv T} _ T{ \fBps\fP T} T{ A salt interface to psutil, a system and process library. T} _ T{ \fBpublish\fP T} T{ Publish a command from a minion to a target T} _ T{ \fBpuppet\fP T} T{ Execute puppet routines T} _ T{ \fBpw_group\fP T} T{ Manage groups on Linux T} _ T{ \fBpw_user\fP T} T{ Manage users with the useradd command T} _ T{ \fBrh_service\fP T} T{ Service support for classic Red Hat type systems. This interface uses the T} _ T{ \fBrvm\fP T} T{ Manage ruby installations and gemsets with RVM, the Ruby Version Manager. T} _ T{ \fBsaltutil\fP T} T{ The Saltutil module is used to manage the state of the salt minion itself. It is T} _ T{ \fBselinux\fP T} T{ Execute calls on selinux T} _ T{ \fBservice\fP T} T{ The default service module, if not otherwise specified salt will fall back T} _ T{ \fBshadow\fP T} T{ Manage the shadow file T} _ T{ \fBsolr\fP T} T{ Apache Solr Salt Module T} _ T{ \fBssh\fP T} T{ Manage client ssh components T} _ T{ \fBstate\fP T} T{ Control the state system on the minion T} _ T{ \fBstatus\fP T} T{ Module for returning various status data about a minion. T} _ T{ \fBsystemd\fP T} T{ Provide the service module for systemd T} _ T{ \fBtest\fP T} T{ Module for running arbitrary tests T} _ T{ \fBtomcat\fP T} T{ Support for Tomcat T} _ T{ \fBupstart\fP T} T{ Module for the management of upstart systems. T} _ T{ \fBuseradd\fP T} T{ Manage users with the useradd command T} _ T{ \fBvirt\fP T} T{ Work with virtual machines managed by libvirt T} _ T{ \fBvirtualenv\fP T} T{ Create virtualenv environments T} _ T{ \fBwin_disk\fP T} T{ Module for gathering disk information on Windows T} _ T{ \fBwin_file\fP T} T{ Manage information about files on the minion, set/read user, group T} _ T{ \fBwin_network\fP T} T{ Module for gathering and managing network information T} _ T{ \fBwin_service\fP T} T{ Windows Service module. T} _ T{ \fBwin_shadow\fP T} T{ Manage the shadow file T} _ T{ \fBwin_useradd\fP T} T{ Manage Windows users with the net user command T} _ T{ \fByumpkg\fP T} T{ Support for YUM T} _ T{ \fByumpkg5\fP T} T{ Support for YUM T} _ T{ \fBzypper\fP T} T{ Package support for openSUSE via the zypper package manager T} _ .TE .SS salt.modules.apache .sp Support for Apache .INDENT 0.0 .TP .B salt.modules.apache.directives() Return list of directives together with expected arguments and places where the directive is valid (\fBapachectl \-L\fP) .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq apache.directives .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.apache.fullversion() Return server version from apachectl \-V .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq apache.fullversion .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.apache.modules() Return list of static and shared modules from apachectl \-M .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq apache.modules .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.apache.servermods() Return list of modules compiled into the server (apachectl \-l) .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq apache.servermods .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.apache.signal(signal=None) Signals httpd to start, restart, or stop. .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq apache.signal restart .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.apache.version() Return server version from apachectl \-v .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq apache.version .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.apache.vhosts() Show the settings as parsed from the config file (currently only shows the virtualhost settings). (\fBapachectl \-S\fP) Because each additional virtual host adds to the execution time, this command may require a long timeout be specified. .sp CLI Example: .sp .nf .ft C salt \-t 10 \(aq*\(aq apache.vhosts .ft P .fi .UNINDENT .SS salt.modules.apt .sp Support for APT (Advanced Packaging Tool) .INDENT 0.0 .TP .B salt.modules.apt.available_version(name) The available version of the package in the repository .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq pkg.available_version .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.apt.install(pkg, refresh=False, repo=\(aq\(aq, skip_verify=False, debconf=None, **kwargs) Install the passed package .INDENT 7.0 .TP .B pkg The name of the package to be installed .TP .B refresh False Update apt before continuing .TP .B repo (default) Specify a package repository to install from (e.g., \fBapt\-get \-t unstable install somepackage\fP) .TP .B skip_verify False Skip the GPG verification check (e.g., \fB\-\-allow\-unauthenticated\fP) .TP .B debconf None Provide the path to a debconf answers file, processed before installation. .UNINDENT .sp Return a dict containing the new package names and versions: .sp .nf .ft C {\(aq\(aq: {\(aqold\(aq: \(aq\(aq, \(aqnew\(aq: \(aq\(aq]} .ft P .fi .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq pkg.install .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.apt.list_pkgs(regex_string=\(aq\(aq) List the packages currently installed in a dict: .sp .nf .ft C {\(aq\(aq: \(aq\(aq} .ft P .fi .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq pkg.list_pkgs .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.apt.purge(pkg) Remove a package via \fBapt\-get purge\fP along with all configuration files and unused dependencies. .sp Returns a list containing the names of the removed packages .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq pkg.purge .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.apt.refresh_db() Updates the APT database to latest packages based upon repositories .sp Returns a dict: .sp .nf .ft C {\(aq\(aq: Bool} .ft P .fi .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq pkg.refresh_db .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.apt.remove(pkg) Remove a single package via \fBapt\-get remove\fP .sp Returns a list containing the names of the removed packages. .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq pkg.remove .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.apt.upgrade(refresh=True) Upgrades all packages via \fBapt\-get dist\-upgrade\fP .sp Returns a list of dicts containing the package names, and the new and old versions: .sp .nf .ft C [ {\(aq\(aq: {\(aqold\(aq: \(aq\(aq, \(aqnew\(aq: \(aq\(aq] }\(aq, ... ] .ft P .fi .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq pkg.upgrade .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.apt.upgrade_available(name) Check whether or not an upgrade is available for a given package .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq pkg.upgrade_available .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.apt.version(name) Returns a string representing the package version or an empty string if not installed .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq pkg.version .ft P .fi .UNINDENT .SS salt.modules.archive .sp A module to wrap archive calls .INDENT 0.0 .TP .B salt.modules.archive.gunzip(gzipfile) Uses the gunzip command to unpack gzip files .sp CLI Example to create \fB/tmp/sourcefile.txt\fP: .sp .nf .ft C salt \(aq*\(aq archive.gunzip /tmp/sourcefile.txt.gz .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.archive.gzip(sourcefile) Uses the gzip command to create gzip files .sp CLI Example to create \fB/tmp/sourcefile.txt.gz\fP: .sp .nf .ft C salt \(aq*\(aq archive.gzip /tmp/sourcefile.txt .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.archive.rar(rarfile, *sources) Uses the rar command to create rar files Uses rar for Linux from \fI\%http://www.rarlab.com/\fP .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq archive.rar /tmp/rarfile.rar /tmp/sourcefile1 /tmp/sourcefile2 .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.archive.tar(options, tarfile, *sources) Uses the tar command to pack, unpack, etc tar files .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq archive.tar cjvf /tmp/tarfile.tar.bz2 /tmp/file1 /tmp/file2 .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.archive.unrar(rarfile, dest, *xfiles) Uses the unrar command to unpack rar files Uses rar for Linux from \fI\%http://www.rarlab.com/\fP .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq archive.unrar /tmp/rarfile.rar /home/strongbad/ file1 file2 .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.archive.unzip(zipfile, dest, *xfiles) Uses the unzip command to unpack zip files .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq archive.unzip /tmp/zipfile.zip /home/strongbad/ file1 file2 .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.archive.zip(zipfile, *sources) Uses the zip command to create zip files .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq archive.zip /tmp/zipfile.zip /tmp/sourcefile1 /tmp/sourcefile2 .ft P .fi .UNINDENT .SS salt.modules.butterkvm .sp Specialized routines used by the butter cloud component .INDENT 0.0 .TP .B salt.modules.butterkvm.create(instance, vda, image, pin) Create a virtual machine, this is part of the butter vm system and assumes that the files prepared by butter are available via shared storage. AKA \- don\(aqt call this from the command line! .INDENT 7.0 .TP .B instance string The path to the instance directory for the given vm on shared storage .TP .B vda The location where the virtual machine image needs to be placed .TP .B image The image to move into place .TP .B pin A "pin" data structure defining the myriad of possible vdb\-vbz disk images to generate .UNINDENT .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq butterkvm.create \e .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.butterkvm.full_butter_data(local_path) Return the full virt info, but add butter data! .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq buttervm.full_butter_data .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.butterkvm.libvirt_creds() Returns the user and group that the disk images should be owned by .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq butterkvm.libvirt_creds .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.butterkvm.local_images(local_path) return the virtual machine names for all of the images located in the butter cloud\(aqs local_path in a list: .sp .nf .ft C [\(aqvm1.boo.com\(aq, \(aqvm2.foo.com\(aq] .ft P .fi .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq buttervm.local_images .ft P .fi .UNINDENT .SS salt.modules.cluster .sp The cluster module is used to distribute and activate salt HA cluster components .INDENT 0.0 .TP .B salt.modules.cluster.distrib(minions, master_conf, master_pem, conf_file) Set up this minion as a failover master \- only intended for use by the cluster interface .UNINDENT .SS salt.modules.cmd .sp A module for shelling out .sp Keep in mind that this module is insecure, in that it can give whomever has access to the master root execution access to all salt minions .INDENT 0.0 .TP .B salt.modules.cmdmod.exec_code(lang, code, cwd=None) Pass in two strings, the first naming the executable language, aka \- python2, python3, ruby, perl, lua, etc. the second string containing the code you wish to execute. The stdout and stderr will be returned .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq cmd.exec_code ruby \(aqputs "cheese"\(aq .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.cmdmod.has_exec(cmd) Returns true if the executable is available on the minion, false otherwise .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq cmd.has_exec cat .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.cmdmod.retcode(cmd, cwd=None, runas=None, shell=\(aq/bin/sh\(aq, env=()) Execute a shell command and return the command\(aqs return code. .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq cmd.retcode "file /bin/bash" .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.cmdmod.run(cmd, cwd=None, runas=None, shell=\(aq/bin/sh\(aq, env=()) Execute the passed command and return the output as a string .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq cmd.run "ls \-l | awk \(aq/foo/{print $2}\(aq" .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.cmdmod.run_all(cmd, cwd=None, runas=None, shell=\(aq/bin/sh\(aq, env=()) Execute the passed command and return a dict of return data .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq cmd.run_all "ls \-l | awk \(aq/foo/{print $2}\(aq" .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.cmdmod.run_stderr(cmd, cwd=None, runas=None, shell=\(aq/bin/sh\(aq, env=()) Execute a command and only return the standard error .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq cmd.run_stderr "ls \-l | awk \(aq/foo/{print $2}\(aq" .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.cmdmod.run_stdout(cmd, cwd=None, runas=None, shell=\(aq/bin/sh\(aq, env=()) Execute a command, and only return the standard out .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq cmd.run_stdout "ls \-l | awk \(aq/foo/{print $2}\(aq" .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.cmdmod.which(cmd) Returns the path of an executable available on the minion, None otherwise .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq cmd.which cat .ft P .fi .UNINDENT .SS salt.modules.cp .sp Minion side functions for salt\-cp .INDENT 0.0 .TP .B salt.modules.cp.cache_dir(path, env=\(aqbase\(aq) Download and cache everything under a directory from the master .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq cp.cache_dir salt://path/to/dir .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.cp.cache_file(path, env=\(aqbase\(aq) Used to cache a single file in the local salt\-master file cache. .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq cp.cache_file salt://path/to/file .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.cp.cache_files(paths, env=\(aqbase\(aq) Used to gather many files from the master, the gathered files will be saved in the minion cachedir reflective to the paths retrieved from the master. .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq cp.cache_files salt://pathto/file1,salt://pathto/file1 .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.cp.cache_local_file(path) Cache a local file on the minion in the localfiles cache .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq cp.cache_local_file /etc/hosts .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.cp.cache_master(env=\(aqbase\(aq) Retrieve all of the files on the master and cache them locally .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq cp.cache_master .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.cp.get_dir(path, dest, env=\(aqbase\(aq) Used to recursively copy a directory from the salt master .sp CLI Example: .INDENT 7.0 .INDENT 3.5 salt \(aq*\(aq cp.get_dir salt://path/to/dir/ /minion/dest .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.cp.get_file(path, dest, env=\(aqbase\(aq) Used to get a single file from the salt master .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq cp.get_file salt://path/to/file /minion/dest .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.cp.get_url(path, dest, env=\(aqbase\(aq) Used to get a single file from a URL. .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq cp.get_url salt://my/file /tmp/mine salt \(aq*\(aq cp.get_url http://www.slashdot.org /tmp/index.html .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.cp.hash_file(path, env=\(aqbase\(aq) Return the hash of a file, to get the hash of a file on the salt master file server prepend the path with salt:// otherwise, prepend the file with / for a local file. .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq cp.hash_file salt://path/to/file .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.cp.is_cached(path, env=\(aqbase\(aq) Return a boolean if the given path on the master has been cached on the minion .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq cp.is_cached salt://path/to/file .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.cp.list_master(env=\(aqbase\(aq) List all of the files stored on the master .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq cp.list_master .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.cp.list_minion(env=\(aqbase\(aq) List all of the files cached on the minion .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq cp.list_minion .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.cp.recv(files, dest) Used with salt\-cp, pass the files dict, and the destination. .sp This function receives small fast copy files from the master via salt\-cp .UNINDENT .SS salt.modules.cron .sp Work with cron .INDENT 0.0 .TP .B salt.modules.cron.list_tab(user) Return the contents of the specified user\(aqs crontab .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq cron.list_tab root .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.cron.ls(user) Return the contents of the specified user\(aqs crontab .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq cron.list_tab root .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.cron.raw_cron(user) Return the contents of the user\(aqs crontab .UNINDENT .INDENT 0.0 .TP .B salt.modules.cron.rm(user, minute, hour, dom, month, dow, cmd) Remove a cron job up for a specified user. .UNINDENT .INDENT 0.0 .TP .B salt.modules.cron.rm_job(user, minute, hour, dom, month, dow, cmd) Remove a cron job up for a specified user. .UNINDENT .INDENT 0.0 .TP .B salt.modules.cron.set_job(user, minute, hour, dom, month, dow, cmd) Sets a cron job up for a specified user. .UNINDENT .INDENT 0.0 .TP .B salt.modules.cron.set_special(user, special, cmd) Set up a special command in the crontab. .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq cron.set_special @hourly \(aqecho foobar\(aq .ft P .fi .UNINDENT .SS salt.modules.data .sp Manage a local persistent data structure that can hold any arbitrairy data specific to the minion .INDENT 0.0 .TP .B salt.modules.data.dump(new_data) Replace the entire datastore with a passed data structure .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq data.dump \(aq{\(aqeggs\(aq: \(aqspam\(aq}\(aq .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.data.getval(key) Get a value from the minion datastore .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq data.getval .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.data.getvals(keys) Get values from the minion datastore .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq data.getvals .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.data.load() Return all of the data in the minion datastore .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq data.load .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.data.update(key, value) Update a key with a value in the minion datastore .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq data.update .ft P .fi .UNINDENT .SS salt.modules.debconfmod .sp Support for Debconf .INDENT 0.0 .TP .B salt.modules.debconfmod.get_selections(fetchempty=True) Answers to debconf questions for all packages in the following format: .sp .nf .ft C {\(aqpackage\(aq: [[\(aqquestion\(aq, \(aqtype\(aq, \(aqvalue\(aq], ...]} .ft P .fi .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq debconf.get_selections .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.debconfmod.set(package, question, type, value, *extra) Set answers to debconf questions for a package. .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq debconf.set [ ...] .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.debconfmod.set_file(path) Set answers to debconf questions from a file. .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq debconf.set_file salt://pathto/pkg.selections .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.debconfmod.show(name) Answers to debconf questions for a package in the following format: .sp .nf .ft C [[\(aqquestion\(aq, \(aqtype\(aq, \(aqvalue\(aq], ...] .ft P .fi .sp If debconf doesn\(aqt know about a package, we return None. .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq debconf.show .ft P .fi .UNINDENT .SS salt.modules.disk .sp Module for gathering disk information .INDENT 0.0 .TP .B salt.modules.disk.inodeusage() Return inode usage information for volumes mounted on this minion .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq disk.inodeusage .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.disk.usage() Return usage information for volumes mounted on this minion .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq disk.usage .ft P .fi .UNINDENT .SS salt.modules.ebuild .sp Support for Portage .INDENT 0.0 .TP .B salt.modules.ebuild.available_version(name) The available version of the package in the repository .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq pkg.available_version .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.ebuild.install(pkg, refresh=False, **kwargs) Install the passed package .sp Return a dict containing the new package names and versions: .sp .nf .ft C {\(aq\(aq: {\(aqold\(aq: \(aq\(aq, \(aqnew\(aq: \(aq\(aq]} .ft P .fi .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq pkg.install .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.ebuild.list_pkgs() List the packages currently installed in a dict: .sp .nf .ft C {\(aq\(aq: \(aq\(aq} .ft P .fi .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq pkg.list_pkgs .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.ebuild.purge(pkg) Portage does not have a purge, this function calls remove .sp Return a list containing the removed packages: .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq pkg.purge .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.ebuild.refresh_db() Updates the portage tree (emerge \-\-sync) .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq pkg.refresh_db .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.ebuild.remove(pkg) Remove a single package via emerge \-\-unmerge .sp Return a list containing the names of the removed packages: .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq pkg.remove .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.ebuild.update(pkg, refresh=False) Updates the passed package (emerge \-\-update package) .sp Return a dict containing the new package names and versions: .sp .nf .ft C {\(aq\(aq: {\(aqold\(aq: \(aq\(aq, \(aqnew\(aq: \(aq\(aq]} .ft P .fi .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq pkg.update .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.ebuild.upgrade(refresh=False) Run a full system upgrade (emerge \-\-update world) .sp Return a dict containing the new package names and versions: .sp .nf .ft C {\(aq\(aq: {\(aqold\(aq: \(aq\(aq, \(aqnew\(aq: \(aq\(aq]} .ft P .fi .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq pkg.upgrade .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.ebuild.version(name) Returns a version if the package is installed, else returns an empty string .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq pkg.version .ft P .fi .UNINDENT .SS salt.modules.file .sp Manage information about files on the minion, set/read user, group, and mode data .INDENT 0.0 .TP .B salt.modules.file.append(path, *args) Append text to the end of a file .sp Usage: .sp .nf .ft C salt \(aq*\(aq file.append /etc/motd \e "With all thine offerings thou shalt offer salt."\e "Salt is what makes things taste bad when it isn\(aqt in them." .ft P .fi .sp New in version 0.9.5. .UNINDENT .INDENT 0.0 .TP .B salt.modules.file.chgrp(path, group) Change the group of a file .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq file.chgrp /etc/passwd root .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.file.chown(path, user, group) Chown a file, pass the file the desired user and group .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq file.chown /etc/passwd root root .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.file.comment(path, regex, char=\(aq#\(aq, backup=\(aq.bak\(aq) Comment out specified lines in a file .INDENT 7.0 .TP .B path The full path to the file to be edited .TP .B regex A regular expression used to find the lines that are to be commented; this pattern will be wrapped in parenthesis and will move any preceding/trailing \fB^\fP or \fB$\fP characters outside the parenthesis (e.g., the pattern \fB^foo$\fP will be rewritten as \fB^(foo)$\fP) .TP .B char \fB#\fP The character to be inserted at the beginning of a line in order to comment it out .TP .B backup \fB.bak\fP The file will be backed up before edit with this file extension .IP Warning This backup will be overwritten each time \fBsed\fP / \fBcomment\fP / \fBuncomment\fP is called. Meaning the backup will only be useful after the first invocation. .RE .UNINDENT .sp Usage: .sp .nf .ft C salt \(aq*\(aq file.comment /etc/modules pcspkr .ft P .fi .sp New in version 0.9.5. .UNINDENT .INDENT 0.0 .TP .B salt.modules.file.contains(path, text, limit=\(aq\(aq, escape=False) Return True if the file at \fBpath\fP contains \fBtext\fP .sp Usage: .sp .nf .ft C salt \(aq*\(aq file.contains /etc/crontab \(aqmymaintenance.sh\(aq .ft P .fi .sp New in version 0.9.5. .UNINDENT .INDENT 0.0 .TP .B salt.modules.file.find(path, *opts) Approximate the Unix find(1) command and return a list of paths that meet the specified critera. .sp The options include match criteria: .sp .nf .ft C name = path\-glob # case sensitive iname = path\-glob # case insensitive regex = path\-regex # case sensitive iregex = path\-regex # case insensitive type = file\-types # match any listed type user = users # match any listed user group = groups # match any listed group size = [+\-]number[size\-unit] # default unit = byte mtime = interval # modified since date grep = regex # search file contents .ft P .fi .sp and/or actions: .sp .nf .ft C delete [= file\-types] # default type = \(aqf\(aq exec = command [arg ...] # where {} is replaced by pathname print [= print\-opts] .ft P .fi .sp The default action is \(aqprint=path\(aq. .sp file\-glob: .sp .nf .ft C * = match zero or more chars ? = match any char [abc] = match a, b, or c [!abc] or [^abc] = match anything except a, b, and c [x\-y] = match chars x through y [!x\-y] or [^x\-y] = match anything except chars x through y {a,b,c} = match a or b or c .ft P .fi .sp path\-regex: a Python re (regular expression) pattern to match pathnames .sp file\-types: a string of one or more of the following: .sp .nf .ft C a: all file types b: block device c: character device d: directory p: FIFO (named pipe) f: plain file l: symlink s: socket .ft P .fi .sp users: a space and/or comma separated list of user names and/or uids .sp groups: a space and/or comma separated list of group names and/or gids .sp size\-unit: .sp .nf .ft C b: bytes k: kilobytes m: megabytes g: gigabytes t: terabytes .ft P .fi .sp interval: .sp .nf .ft C [w] [[d]] [h] [m] [s] where: w: week d: day h: hour m: minute s: second .ft P .fi .sp print\-opts: a comma and/or space separated list of one or more of the following: .sp .nf .ft C group: group name md5: MD5 digest of file contents mode: file permissions (as integer) mtime: last modification time (as time_t) name: file basename path: file absolute path size: file size in bytes type: file type user: user name .ft P .fi .sp CLI Examples: .sp .nf .ft C salt \(aq*\(aq file.find / type=f name=\e*.bak size=+10m salt \(aq*\(aq file.find /var mtime=+30d size=+10m print=path,size,mtime salt \(aq*\(aq file.find /var/log name=\e*.[0\-9] mtime=+30d size=+10m delete .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.file.get_gid(path) Return the id of the group that owns a given file .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq file.get_gid /etc/passwd .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.file.get_group(path) Return the group that owns a given file .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq file.get_group /etc/passwd .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.file.get_mode(path) Return the mode of a file .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq file.get_mode /etc/passwd .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.file.get_sum(path, form=\(aqmd5\(aq) Return the sum for the given file, default is md5, sha1, sha224, sha256, sha384, sha512 are supported .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq file.get_sum /etc/passwd sha512 .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.file.get_uid(path) Return the id of the user that owns a given file .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq file.get_uid /etc/passwd .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.file.get_user(path) Return the user that owns a given file .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq file.get_user /etc/passwd .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.file.gid_to_group(gid) Convert the group id to the group name on this system .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq file.gid_to_group 0 .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.file.group_to_gid(group) Convert the group to the gid on this system .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq file.group_to_gid root .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.file.sed(path, before, after, limit=\(aq\(aq, backup=\(aq.bak\(aq, options=\(aq\-r \-e\(aq, flags=\(aqg\(aq, escape_all=False) Make a simple edit to a file .sp Equivalent to: .sp .nf .ft C sed "// s/// " .ft P .fi .INDENT 7.0 .TP .B path The full path to the file to be edited .TP .B before A pattern to find in order to replace with \fBafter\fP .TP .B after Text that will replace \fBbefore\fP .TP .B limit \fB\(aq\(aq\fP An initial pattern to search for before searching for \fBbefore\fP .TP .B backup \fB.bak\fP The file will be backed up before edit with this file extension; \fBWARNING:\fP each time \fBsed\fP/\fBcomment\fP/\fBuncomment\fP is called will overwrite this backup .TP .B options \fB\-r \-e\fP Options to pass to sed .TP .B flags \fBg\fP Flags to modify the sed search; e.g., \fBi\fP for case\-insensitve pattern matching .UNINDENT .sp Forward slashes and single quotes will be escaped automatically in the \fBbefore\fP and \fBafter\fP patterns. .sp Usage: .sp .nf .ft C salt \(aq*\(aq file.sed /etc/httpd/httpd.conf \(aqLogLevel warn\(aq \(aqLogLevel info\(aq .ft P .fi .sp New in version 0.9.5. .UNINDENT .INDENT 0.0 .TP .B salt.modules.file.set_mode(path, mode) Set the mode of a file .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq file.set_mode /etc/passwd 0644 .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.file.touch(name, atime=None, mtime=None) Just like \(aqnix\(aqs "touch" command, create a file if it doesn\(aqt exist or simply update the atime and mtime if it already does. .INDENT 7.0 .TP .B atime: Access time in Unix epoch time .TP .B mtime: Last modification in Unix epoch time .TP .B Usage:: salt \(aq*\(aq file.touch /var/log/emptyfile .UNINDENT .sp New in version 0.9.5. .UNINDENT .INDENT 0.0 .TP .B salt.modules.file.uid_to_user(uid) Convert a uid to a user name .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq file.uid_to_user 0 .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.file.uncomment(path, regex, char=\(aq#\(aq, backup=\(aq.bak\(aq) Uncomment specified commented lines in a file .INDENT 7.0 .TP .B path The full path to the file to be edited .TP .B regex A regular expression used to find the lines that are to be uncommented. This regex should not include the comment character. A leading \fB^\fP character will be stripped for convenience (for easily switching between comment() and uncomment()). .TP .B char \fB#\fP The character to remove in order to uncomment a line; if a single whitespace character follows the comment it will also be removed .TP .B backup \fB.bak\fP The file will be backed up before edit with this file extension; \fBWARNING:\fP each time \fBsed\fP/\fBcomment\fP/\fBuncomment\fP is called will overwrite this backup .UNINDENT .sp Usage: .sp .nf .ft C salt \(aq*\(aq file.uncomment /etc/hosts.deny \(aqALL: PARANOID\(aq .ft P .fi .sp New in version 0.9.5. .UNINDENT .INDENT 0.0 .TP .B salt.modules.file.user_to_uid(user) Convert user name to a uid .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq file.user_to_uid root .ft P .fi .UNINDENT .SS salt.modules.freebsdkmod .sp Module to manage FreeBSD kernel modules .INDENT 0.0 .TP .B salt.modules.freebsdkmod.available() Return a list of all available kernel modules .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq kmod.available .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.freebsdkmod.check_available(mod) Check to see if the specified kernel module is available .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq kmod.check_available kvm .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.freebsdkmod.load(mod) Load the specified kernel module .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq kmod.load kvm .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.freebsdkmod.lsmod() Return a dict containing information about currently loaded modules .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq kmod.lsmod .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.freebsdkmod.remove(mod) Remove the specified kernel module .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq kmod.remove kvm .ft P .fi .UNINDENT .SS salt.modules.freebsdpkg .sp Package support for FreeBSD .INDENT 0.0 .TP .B salt.modules.freebsdpkg.available_version(name) The available version of the package in the repository .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq pkg.available_version .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.freebsdpkg.install(name, *args, **kwargs) Install the passed package .sp Return a dict containing the new package names and versions: .sp .nf .ft C {\(aq\(aq: {\(aqold\(aq: \(aq\(aq, \(aqnew\(aq: \(aq\(aq]} .ft P .fi .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq pkg.install .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.freebsdpkg.list_pkgs() List the packages currently installed as a dict: .sp .nf .ft C {\(aq\(aq: \(aq\(aq} .ft P .fi .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq pkg.list_pkgs .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.freebsdpkg.purge(name) Remove a single package with pkg_delete .sp Returns a list containing the removed packages. .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq pkg.purge .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.freebsdpkg.refresh_db() Update the ports tree with portsnap. If the ports tree does not exist it will be downloaded and set up. .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq pkg.refresh_db .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.freebsdpkg.rehash() Recomputes internal hash table for the PATH variable. Use whenever a new command is created during the current session. .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq pkg.rehash .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.freebsdpkg.remove(name) Remove a single package with pkg_delete .sp Returns a list containing the removed packages. .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq pkg.remove .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.freebsdpkg.upgrade() Run a full system upgrade, a \fBfreebsd\-update fetch install\fP .sp Return a dict containing the new package names and versions: .sp .nf .ft C {\(aq\(aq: {\(aqold\(aq: \(aq\(aq, \(aqnew\(aq: \(aq\(aq]} .ft P .fi .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq pkg.upgrade .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.freebsdpkg.version(name) Returns a version if the package is installed, else returns an empty string .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq pkg.version .ft P .fi .UNINDENT .SS salt.modules.freebsdservice .sp The service module for FreeBSD .INDENT 0.0 .TP .B salt.modules.freebsdservice.get_all() Return a list of all available services .UNINDENT .INDENT 0.0 .TP .B salt.modules.freebsdservice.get_disabled() Return what services are available but not enabled to start at boot .UNINDENT .INDENT 0.0 .TP .B salt.modules.freebsdservice.get_enabled() Return what services are set to run on boot .UNINDENT .INDENT 0.0 .TP .B salt.modules.freebsdservice.restart(name) Restart the named service .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq service.restart .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.freebsdservice.start(name) Start the specified service .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq service.start .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.freebsdservice.status(name, sig=None) Return the status for a service, returns the PID or an empty string if the service is running or not, pass a signature to use to find the service via ps .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq service.status [service signature] .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.freebsdservice.stop(name) Stop the specified service .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq service.stop .ft P .fi .UNINDENT .SS salt.modules.gem .sp Manage ruby gems. .INDENT 0.0 .TP .B salt.modules.gem.install(gems, ruby=None, runas=None) Installs one or several gems. .INDENT 7.0 .TP .B gems The gems to install. .TP .B ruby None If RVM is installed, the ruby version and gemset to use. .TP .B runas None The user to run gem as. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.gem.list(prefix=\(aq\(aq, ruby=None, runas=None) List locally installed gems. .INDENT 7.0 .TP .B prefix : Only list gems when the name matches this prefix. .TP .B ruby None If RVM is installed, the ruby version and gemset to use. .TP .B runas None The user to run gem as. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.gem.sources_add(source_uri, ruby=None, runas=None) Add a gem source. .INDENT 7.0 .TP .B source_uri The source URI to add. .TP .B ruby None If RVM is installed, the ruby version and gemset to use. .TP .B runas None The user to run gem as. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.gem.sources_list(ruby=None, runas=None) List the configured gem sources. .INDENT 7.0 .TP .B ruby None If RVM is installed, the ruby version and gemset to use. .TP .B runas None The user to run gem as. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.gem.sources_remove(source_uri, ruby=None, runas=None) Remove a gem source. .INDENT 7.0 .TP .B source_uri The source URI to remove. .TP .B ruby None If RVM is installed, the ruby version and gemset to use. .TP .B runas None The user to run gem as. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.gem.uninstall(gems, ruby=None, runas=None) Uninstall one or several gems. .INDENT 7.0 .TP .B gems The gems to uninstall. .TP .B ruby None If RVM is installed, the ruby version and gemset to use. .TP .B runas None The user to run gem as. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.gem.update(gems, ruby=None, runas=None) Update one or several gems. .INDENT 7.0 .TP .B gems The gems to update. .TP .B ruby None If RVM is installed, the ruby version and gemset to use. .TP .B runas None The user to run gem as. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.gem.update_system(version=\(aq\(aq, ruby=None, runas=None) Update rubygems. .INDENT 7.0 .TP .B version (newest) The version of rubygems to install. .TP .B ruby None If RVM is installed, the ruby version and gemset to use. .TP .B runas None The user to run gem as. .UNINDENT .UNINDENT .SS salt.modules.gentoo_service .sp Top level package command wrapper, used to translate the os detected by the grains to the correct service manager .INDENT 0.0 .TP .B salt.modules.gentoo_service.disable(name) Disable the named service to start at boot .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq service.disable .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.gentoo_service.disabled(name) Return True if the named servioce is enabled, false otherwise .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq service.enabled .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.gentoo_service.enable(name) Enable the named service to start at boot .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq service.enable .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.gentoo_service.enabled(name) Return True if the named servioce is enabled, false otherwise .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq service.enabled .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.gentoo_service.get_all() Return all available boot services .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq service.get_enabled .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.gentoo_service.get_disabled() Return a set of services that are installed but disabled .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq service.get_enabled .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.gentoo_service.get_enabled() Return a list of service that are enabled on boot .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq service.get_enabled .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.gentoo_service.restart(name) Restart the named service .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq service.restart .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.gentoo_service.start(name) Start the specified service .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq service.start .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.gentoo_service.status(name, sig=None) Return the status for a service, returns the PID or an empty string if the service is running or not, pass a signature to use to find the service via ps .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq service.status [service signature] .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.gentoo_service.stop(name) Stop the specified service .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq service.stop .ft P .fi .UNINDENT .SS salt.modules.git .sp Support for the Git SCM .INDENT 0.0 .TP .B salt.modules.git.archive(cwd, output, rev=\(aqHEAD\(aq, fmt=None, prefix=None, user=None) Export a tarball from the repository .INDENT 7.0 .TP .B cwd The path to the Git repository .TP .B output The path to the archive tarball .TP .B rev: HEAD The revision to create an archive from .TP .B fmt: None Format of the resulting archive, zip and tar are commonly used .TP .B prefix None Prepend / to every filename in the archive .TP .B user None Run git as a user other than what the minion runs as .UNINDENT .sp If \fBprefix\fP is not specified it defaults to the basename of the repo directory. .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq git.archive /path/to/repo /path/to/archive.tar.gz .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.git.checkout(cwd, rev, force=False, opts=None, user=None) Checkout a given revision .INDENT 7.0 .TP .B cwd The path to the Git repository .TP .B rev The remote branch or revision to checkout .TP .B force False Force a checkout even if there might be overwritten changes .TP .B opts None Any additional options to add to the command line .TP .B user None Run git as a user other than what the minion runs as .UNINDENT .sp CLI Examples: .sp .nf .ft C salt \(aq*\(aq git.checkout /path/to/repo somebranch user=jeff salt \(aq*\(aq git.checkout /path/to/repo opts=\(aqtestbranch \-\- conf/file1 file2\(aq salt \(aq*\(aq git.checkout /path/to/repo rev=origin/mybranch opts=\-\-track .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.git.clone(cwd, repository, opts=None, user=None) Clone a new repository .INDENT 7.0 .TP .B cwd The path to the Git repository .TP .B repository The git uri of the repository .TP .B opts None Any additional options to add to the command line .TP .B user None Run git as a user other than what the minion runs as .UNINDENT .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq git.clone /path/to/repo git://github.com/saltstack/salt.git salt \(aq*\(aq git.clone /path/to/repo.git\e git://github.com/saltstack/salt.git \(aq\-\-bare \-\-origin github\(aq .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.git.describe(cwd, rev=\(aqHEAD\(aq, user=None) Returns the git describe string (or the SHA hash if there are no tags) for the given revision .INDENT 7.0 .TP .B cwd The path to the Git repository .TP .B rev: HEAD The revision to describe .TP .B user None Run git as a user other than what the minion runs as .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.git.fetch(cwd, opts=None, user=None) Perform a fetch on the given repository .INDENT 7.0 .TP .B cwd The path to the Git repository .TP .B opts None Any additional options to add to the command line .TP .B user None Run git as a user other than what the minion runs as .UNINDENT .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq git.fetch /path/to/repo \(aq\-\-all\(aq salt \(aq*\(aq git.fetch cwd=/path/to/repo opts=\(aq\-\-all\(aq user=johnny .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.git.init(cwd, opts=None, user=None) Initialize a new git repository .INDENT 7.0 .TP .B cwd The path to the Git repository .TP .B opts None Any additional options to add to the command line .TP .B user None Run git as a user other than what the minion runs as .UNINDENT .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq git.init /path/to/repo.git opts=\(aq\-\-bare\(aq .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.git.merge(cwd, branch=\(aq@{upstream}\(aq, opts=None, user=None) Merge a given branch .INDENT 7.0 .TP .B cwd The path to the Git repository .TP .B branch @{upstream} The remote branch or revision to merge into the current branch .TP .B opts None Any additional options to add to the command line .TP .B user None Run git as a user other than what the minion runs as .UNINDENT .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq git.fetch /path/to/repo salt \(aq*\(aq git.merge /path/to/repo @{upstream} .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.git.pull(cwd, opts=None, user=None) Perform a pull on the given repository .INDENT 7.0 .TP .B cwd The path to the Git repository .TP .B opts None Any additional options to add to the command line .TP .B user None Run git as a user other than what the minion runs as .UNINDENT .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq git.pull /path/to/repo opts=\(aq\-\-rebase origin master\(aq .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.git.rebase(cwd, rev=\(aqmaster\(aq, opts=None, user=None) Rebase the current branch .INDENT 7.0 .TP .B cwd The path to the Git repository .TP .B rev master The revision to rebase onto the current branch .TP .B opts None Any additional options to add to the command line .TP .B user None Run git as a user other than what the minion runs as .UNINDENT .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq git.rebase /path/to/repo master .ft P .fi .sp That is the same as: git rebase master .UNINDENT .INDENT 0.0 .TP .B salt.modules.git.revision(cwd, rev=\(aqHEAD\(aq, short=False, user=None) Returns the long hash of a given identifier (hash, branch, tag, HEAD, etc) .INDENT 7.0 .TP .B cwd The path to the Git repository .TP .B rev: HEAD The revision .TP .B short: False Return an abbreviated SHA1 git hash .TP .B user None Run git as a user other than what the minion runs as .UNINDENT .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq git.revision /path/to/repo mybranch .ft P .fi .UNINDENT .SS salt.modules.grains .sp Control aspects of the grains data .INDENT 0.0 .TP .B salt.modules.grains.item(key=None) Return a singe component of the grains data .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq grains.item os .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.grains.items() Return the grains data .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq grains.items .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.grains.ls() Return a list of all available grains .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq grains.ls .ft P .fi .UNINDENT .SS salt.modules.groupadd .sp Manage groups on Linux .INDENT 0.0 .TP .B salt.modules.groupadd.add(name, gid=None) Add the specified group .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq group.add foo 3456 .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.groupadd.chgid(name, gid) Change the gid for a named group .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq group.chgid foo 4376 .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.groupadd.delete(name) Remove the named group .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq group.delete foo .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.groupadd.getent() Return info on all groups .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq group.getent .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.groupadd.info(name) Return information about a group .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq group.info foo .ft P .fi .UNINDENT .SS salt.modules.hg .sp Support for the Mercurial SCM .INDENT 0.0 .TP .B salt.modules.hg.archive(cwd, output, rev=\(aqtip\(aq, fmt=None, prefix=None, user=None) Export a tarball from the repository .INDENT 7.0 .TP .B cwd The path to the Mercurial repository .TP .B output The path to the archive tarball .TP .B rev: tip The revision to create an archive from .TP .B fmt: None Format of the resulting archive. Mercurial supports: tar, tbz2, tgz, zip, uzip, and files formats. .TP .B prefix None Prepend / to every filename in the archive .TP .B user None Run hg as a user other than what the minion runs as .UNINDENT .sp If \fBprefix\fP is not specified it defaults to the basename of the repo directory. .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq hg.archive /path/to/repo output=/tmp/archive.tgz fmt=tgz .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.hg.clone(cwd, repository, opts=None, user=None) Clone a new repository .INDENT 7.0 .TP .B cwd The path to the Mercurial repository .TP .B repository The hg uri of the repository .TP .B opts None Any additional options to add to the command line .TP .B user None Run hg as a user other than what the minion runs as .UNINDENT .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq hg.clone /path/to/repo https://bitbucket.org/birkenfeld/sphinx .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.hg.describe(cwd, rev=\(aqtip\(aq, user=None) Mimick git describe and return an identifier for the given revision .INDENT 7.0 .TP .B cwd The path to the Mercurial repository .TP .B rev: tip The path to the archive tarball .TP .B user None Run hg as a user other than what the minion runs as .UNINDENT .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq hg.describe /path/to/repo .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.hg.pull(cwd, opts=None, user=None) Perform a pull on the given repository .INDENT 7.0 .TP .B cwd The path to the Mercurial repository .TP .B opts None Any additional options to add to the command line .TP .B user None Run hg as a user other than what the minion runs as .UNINDENT .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq hg.pull /path/to/repo \(aq\-u\(aq .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.hg.revision(cwd, rev=\(aqtip\(aq, short=False, user=None) Returns the long hash of a given identifier (hash, branch, tag, HEAD, etc) .INDENT 7.0 .TP .B cwd The path to the Mercurial repository .TP .B rev: tip The revision .TP .B short: False Return an abbreviated commit hash .TP .B user None Run hg as a user other than what the minion runs as .UNINDENT .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq hg.revision /path/to/repo mybranch .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.hg.update(cwd, rev, force=False, user=None) Update to a given revision .INDENT 7.0 .TP .B cwd The path to the Mercurial repository .TP .B rev The revision to update to .TP .B force False Force an update .TP .B user None Run hg as a user other than what the minion runs as .UNINDENT .sp CLI Example: .sp .nf .ft C salt devserver1 hg.update /path/to/repo somebranch .ft P .fi .UNINDENT .SS salt.modules.hosts .sp Manage the information in the hosts file .INDENT 0.0 .TP .B salt.modules.hosts.add_host(ip, alias) Add a host to an existing entry, if the entry is not in place then create it with the given host .INDENT 7.0 .TP .B CLI Example:: salt \(aq*\(aq hosts.add_host .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.hosts.get_alias(ip) Return the list of aliases associated with an ip .INDENT 7.0 .TP .B CLI Example:: salt \(aq*\(aq hosts.get_alias .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.hosts.get_ip(host) Return the ip associated with the named host .INDENT 7.0 .TP .B CLI Example:: salt \(aq*\(aq hosts.get_ip .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.hosts.has_pair(ip, alias) Return true if the alias is set .INDENT 7.0 .TP .B CLI Example:: salt \(aq*\(aq hosts.has_pair .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.hosts.list_hosts() Return the hosts found in the hosts file in this format: .sp .nf .ft C {\(aq\(aq: [\(aqalias1\(aq, \(aqalias2\(aq, ...]} .ft P .fi .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq hosts.list_hosts .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.hosts.rm_host(ip, alias) Remove a host entry from the hosts file .INDENT 7.0 .TP .B CLI Example:: salt \(aq*\(aq hosts.rm_host .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.hosts.set_host(ip, alias) Set the host entry in the hosts file for the given ip, this will overwrite any previous entry for the given ip .INDENT 7.0 .TP .B CLI Example:: salt \(aq*\(aq hosts.set_host .UNINDENT .UNINDENT .SS salt.modules.kmod .sp Module to manage Linux kernel modules .INDENT 0.0 .TP .B salt.modules.kmod.available() Return a list of all available kernel modules .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq kmod.available .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.kmod.check_available(mod) Check to see if the specified kernel module is available .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq kmod.check_available kvm .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.kmod.load(mod) Load the specified kernel module .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq kmod.load kvm .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.kmod.lsmod() Return a dict containing information about currently loaded modules .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq kmod.lsmod .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.kmod.remove(mod) Remove the specified kernel module .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq kmod.remove kvm .ft P .fi .UNINDENT .SS salt.modules.kvm_hyper .sp Provide the hyper module for kvm hypervisors. This is the interface used to interact with kvm on behalf of the salt\-virt interface .sp Required python modules: libvirt .INDENT 0.0 .TP .B salt.modules.kvm_hyper.freecpu() Return an int representing the number of unallocated cpus on this hypervisor .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq virt.freemem .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.kvm_hyper.freemem() Return an int representing the amount of memory that has not been given to virtual machines on this node .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq virt.freemem .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.kvm_hyper.get_conf(name) Returns the xml for a given vm .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq virt.get_conf .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.kvm_hyper.get_disks(name) Return the disks of a named virt .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq virt.get_disks .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.kvm_hyper.halt(name) Hard power down a virtual machine .UNINDENT .INDENT 0.0 .TP .B salt.modules.kvm_hyper.hyper_info() Return a dict with information about this hypervisor .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq virt.node_info .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.kvm_hyper.hyper_type() Return that type of hypervisor this is .UNINDENT .INDENT 0.0 .TP .B salt.modules.kvm_hyper.init(name, cpus, mem, image, storage_dir, network={\(aqeth0\(aq: {\(aqbridge\(aq: \(aqbr0\(aq, \(aqmac\(aq: \(aq\(aq}}, desc=\(aq\(aq, opts={}) Create a KVM virtual machine based on these passed options, the virtual machine will be started upon creation .sp CLI Example: .INDENT 7.0 .INDENT 3.5 salt node1 webserver 2 2048 salt://fedora/f16.img:virt /srv/vm/images .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.kvm_hyper.list_virts() Return a list of virtual machine names on the minion .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq virt.list_virts .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.kvm_hyper.pause(name) Pause the named virtual machine .UNINDENT .INDENT 0.0 .TP .B salt.modules.kvm_hyper.purge(name) Hard power down and purge a virtual machine, this will destroy a vm and all associated vm data .UNINDENT .INDENT 0.0 .TP .B salt.modules.kvm_hyper.resume(name) Resume the named virtual machine .UNINDENT .INDENT 0.0 .TP .B salt.modules.kvm_hyper.set_autostart(name) Set the named virtual machine to autostart when the hypervisor boots .UNINDENT .INDENT 0.0 .TP .B salt.modules.kvm_hyper.start(config) Start an already defined virtual machine that has been shut down .UNINDENT .INDENT 0.0 .TP .B salt.modules.kvm_hyper.virt_info() Return detailed information about the vms on this hyper in a dict: .sp .nf .ft C {\(aqcpu\(aq: , \(aqmaxMem\(aq: , \(aqmem\(aq: , \(aqstate\(aq: \(aq\(aq, \(aqcputime\(aq } .ft P .fi .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq virt.vm_info .ft P .fi .UNINDENT .SS salt.modules.linux_sysctl .sp Module for viewing and modifying sysctl parameters .INDENT 0.0 .TP .B salt.modules.linux_sysctl.assign(name, value) Assign a single sysctl parameter for this minion .sp CLI Example: salt \(aq*\(aq sysctl.assign net.ipv4.ip_forward 1 .UNINDENT .INDENT 0.0 .TP .B salt.modules.linux_sysctl.get(name) Return a single sysctl parameter for this minion .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq sysctl.get net.ipv4.ip_forward .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.linux_sysctl.persist(name, value, config=\(aq/etc/sysctl.conf\(aq) Assign and persist a simple sysctl parameter for this minion .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq sysctl.persist net.ipv4.ip_forward 1 .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.linux_sysctl.show() Return a list of sysctl parameters for this minion .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq sysctl.show .ft P .fi .UNINDENT .SS salt.modules.mdadm .sp Salt module to manage RAID arrays with mdadm .INDENT 0.0 .TP .B salt.modules.mdadm.detail(device=\(aq/dev/md0\(aq) Show detail for a specified RAID device .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq raid.detail \(aq/dev/md0\(aq .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.mdadm.list() List the RAID devices. .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq raid.list .ft P .fi .UNINDENT .SS salt.modules.moosefs .sp Module for gathering and managing information about MooseFS .INDENT 0.0 .TP .B salt.modules.moosefs.dirinfo(path, opts=None) Return information on a directory located on the Moose .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq moosefs.dirinfo /path/to/dir/ [\-[n][h|H]] .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.moosefs.fileinfo(path) Return information on a file located on the Moose .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq moosefs.fileinfo /path/to/dir/ .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.moosefs.getgoal(path, opts=None) Return goal(s) for a file or directory .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq moosefs.getgoal /path/to/file [\-[n][h|H]] salt \(aq*\(aq moosefs.getgoal /path/to/dir/ [\-[n][h|H][r]] .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.moosefs.mounts() Return a list of current MooseFS mounts .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq moosefs.mounts .ft P .fi .UNINDENT .SS salt.modules.mount .sp Salt module to manage unix mounts and the fstab file .INDENT 0.0 .TP .B salt.modules.mount.active() List the active mounts. .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq mount.active .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.mount.fstab(config=\(aq/etc/fstab\(aq) List the contents of the fstab .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq mount.fstab .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.mount.is_fuse_exec(cmd) Returns true if the command passed is a fuse mountable application. .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq mount.is_fuse_exec sshfs .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.mount.mount(name, device, mkmnt=False, fstype=\(aq\(aq, opts=\(aqdefaults\(aq) Mount a device .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq mount.mount /mnt/foo /dev/sdz1 True .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.mount.remount(name, device, mkmnt=False, fstype=\(aq\(aq, opts=\(aqdefaults\(aq) Attempt to remount a device, if the device is not already mounted, mount is called .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq mount.remount /mnt/foo /dev/sdz1 True .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.mount.rm_fstab(name, config=\(aq/etc/fstab\(aq) Remove the mount point from the fstab .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq /mnt/foo .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.mount.set_fstab(name, device, fstype, opts=\(aqdefaults\(aq, dump=0, pass_num=0, config=\(aq/etc/fstab\(aq) Verify that this mount is represented in the fstab, chage the mount point to match the data passed, or add the mount if it is not present. .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq mount.set_fstab /mnt/foo /dev/sdz1 ext4 .ft P .fi .UNINDENT .SS salt.modules.mysql .sp Module to provide MySQL compatibility to salt. .sp In order to connect to MySQL, certain configuration is required in /etc/salt/minion on the relevant minions. Some sample configs might look like: .sp .nf .ft C mysql.host: \(aqlocalhost\(aq mysql.port: 3306 mysql.user: \(aqroot\(aq mysql.pass: \(aq\(aq mysql.db: \(aqmysql\(aq .ft P .fi .sp You can also use a defaults file: .sp .nf .ft C mysql.default_file: \(aq/etc/mysql/debian.cnf\(aq .ft P .fi .sp Required python modules: MySQLdb .INDENT 0.0 .TP .B salt.modules.mysql.connect(**kwargs) wrap authentication credentials here .UNINDENT .INDENT 0.0 .TP .B salt.modules.mysql.db_check(name, table=None) Repairs the full database or just a given table .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq mysql.db_check dbname .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.mysql.db_create(name) Adds a databases to the MySQL server. .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq mysql.db_create \(aqdbname\(aq .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.mysql.db_exists(name) Checks if a database exists on the MySQL server. .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq mysql.db_exists \(aqdbname\(aq .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.mysql.db_list() Return a list of databases of a MySQL server using the output from the \fBSHOW DATABASES\fP query. .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq mysql.db_list .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.mysql.db_optimize(name, table=None) Optimizes the full database or just a given table .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq mysql.db_optimize dbname .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.mysql.db_remove(name) Removes a databases from the MySQL server. .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq mysql.db_remove \(aqdbname\(aq .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.mysql.db_repair(name, table=None) Repairs the full database or just a given table .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq mysql.db_repair dbname .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.mysql.db_tables(name) Shows the tables in the given MySQL database (if exists) .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq mysql.db_tables \(aqdatabase\(aq .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.mysql.free_slave() Frees a slave from its master. This is a WIP, do not use. .UNINDENT .INDENT 0.0 .TP .B salt.modules.mysql.grant_add(grant, database, user, host=\(aqlocalhost\(aq, grant_option=False, escape=True) Adds a grant to the MySQL server. .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq mysql.grant_add \(aqSELECT|INSERT|UPDATE|...\(aq \(aqdatabase.*\(aq \(aqfrank\(aq \(aqlocalhost\(aq .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.mysql.grant_revoke(grant, database, user, host=\(aqlocalhost\(aq, grant_option=False) Removes a grant from the MySQL server. .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq mysql.grant_revoke \(aqSELECT,INSERT,UPDATE\(aq \(aqdatabase.*\(aq \(aqfrank\(aq \(aqlocalhost\(aq .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.mysql.slave_lag() Return the number of seconds that a slave SQL server is lagging behind the master, if the host is not a slave it will return \-1. If the server is configured to be a slave for replication but slave IO is not running then \-2 will be returned. .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq mysql.slave_lag .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.mysql.status() Return the status of a MySQL server using the output from the \fBSHOW STATUS\fP query. .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq mysql.status .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.mysql.user_chpass(user, host=\(aqlocalhost\(aq, password=None, password_hash=None) Change password for MySQL user .sp CLI Examples: .sp .nf .ft C salt \(aq*\(aq mysql.user_chpass frank localhost newpassword salt \(aq*\(aq mysql.user_chpass frank localhost password_hash=\(aqhash\(aq .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.mysql.user_create(user, host=\(aqlocalhost\(aq, password=None, password_hash=None) Creates a MySQL user. .sp CLI Examples: .sp .nf .ft C salt \(aq*\(aq mysql.user_create \(aqusername\(aq \(aqhostname\(aq \(aqpassword salt \(aq*\(aq mysql.user_create \(aqusername\(aq \(aqhostname\(aq password_hash=\(aqhash\(aq .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.mysql.user_exists(user, host=\(aqlocalhost\(aq) Checks if a user exists on the MySQL server. .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq mysql.user_exists \(aqusername\(aq \(aqhostname\(aq .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.mysql.user_grants(user, host=\(aqlocalhost\(aq) Shows the grants for the given MySQL user (if it exists) .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq mysql.user_grants \(aqfrank\(aq \(aqlocalhost\(aq .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.mysql.user_info(user, host=\(aqlocalhost\(aq) Get full info on a MySQL user .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq mysql.user_info root localhost .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.mysql.user_list() Return a list of users on a MySQL server .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq mysql.user_list .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.mysql.user_remove(user, host=\(aqlocalhost\(aq) Delete MySQL user .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq mysql.user_remove frank localhost .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.mysql.version() Return the version of a MySQL server using the output from the \fBSELECT VERSION()\fP query. .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq mysql.version .ft P .fi .UNINDENT .SS salt.modules.network .sp Module for gathering and managing network information .INDENT 0.0 .TP .B salt.modules.network.dig(host) Performs a DNS lookup with dig .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq network.dig archlinux.org .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.network.hwaddr(interface) Returns the hwaddr for a given interface .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq network.hwaddr eth0 .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.network.interfaces() Returns a dictionary of interfaces with various information about each (up/down state, ip address, netmask, and hwaddr) .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq network.interfaces .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.network.ipaddr(interface) Returns the IP address for a given interface .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq network.ipaddr eth0 .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.network.isportopen(host, port) Return status of a port .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq network.isportopen 127.0.0.1 22 .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.network.netmask(interface) Returns the netmask for a given interface .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq network.netmask eth0 .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.network.netstat() Return information on open ports and states .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq network.netstat .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.network.ping(host) Performs a ping to a host .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq network.ping archlinux.org .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.network.traceroute(host) Performs a traceroute to a 3rd party host .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq network.traceroute archlinux.org .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.network.up(interface) Returns True if interface is up, otherwise returns False .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq network.up eth0 .ft P .fi .UNINDENT .SS salt.modules.nginx .sp Support for nginx .INDENT 0.0 .TP .B salt.modules.nginx.signal(signal=None) Signals httpd to start, restart, or stop. .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq nginx.signal reload .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.nginx.version() Return server version from nginx \-v .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq nginx.version .ft P .fi .UNINDENT .SS salt.modules.pacman .sp A module to wrap pacman calls, since Arch is the best (\fI\%https://wiki.archlinux.org/index.php/Arch_is_the_best\fP) .INDENT 0.0 .TP .B salt.modules.pacman.available_version(name) The available version of the package in the repository .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq pkg.available_version .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.pacman.install(name, refresh=False, **kwargs) Install the passed package, add refresh=True to install with an \-Sy .sp Return a dict containing the new package names and versions: .sp .nf .ft C {\(aq\(aq: {\(aqold\(aq: \(aq\(aq, \(aqnew\(aq: \(aq\(aq]} .ft P .fi .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq pkg.install .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.pacman.list_pkgs() List the packages currently installed as a dict: .sp .nf .ft C {\(aq\(aq: \(aq\(aq} .ft P .fi .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq pkg.list_pkgs .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.pacman.purge(name) Recursively remove a package and all dependencies which were installed with it, this will call a \fBpacman \-Rsc\fP .sp Return a list containing the removed packages. .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq pkg.purge .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.pacman.refresh_db() Just run a \fBpacman \-Sy\fP, return a dict: .sp .nf .ft C {\(aq\(aq: Bool} .ft P .fi .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq pkg.refresh_db .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.pacman.remove(name) Remove a single package with \fBpacman \-R\fP .sp Return a list containing the removed packages. .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq pkg.remove .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.pacman.upgrade() Run a full system upgrade, a pacman \-Syu .sp Return a dict containing the new package names and versions: .sp .nf .ft C {\(aq\(aq: {\(aqold\(aq: \(aq\(aq, \(aqnew\(aq: \(aq\(aq]} .ft P .fi .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq pkg.upgrade .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.pacman.upgrade_available(name) Check whether or not an upgrade is available for a given package .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq pkg.upgrade_available .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.pacman.version(name) Returns a version if the package is installed, else returns an empty string .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq pkg.version .ft P .fi .UNINDENT .SS salt.modules.pillar .sp Extract the pillar data for this minion .INDENT 0.0 .TP .B salt.modules.pillar.data() Returns the pillar derived from the configured pillar source. The pillar source is derived from the file_client option in the minion config .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq pillar.data .ft P .fi .UNINDENT .SS salt.modules.pip .sp Install Python packages with pip to either the system or a virtualenv .INDENT 0.0 .TP .B salt.modules.pip.freeze(bin_env=None) Return a list of installed packages either globally or in the specified virtualenv .INDENT 7.0 .TP .B bin_env path to pip bin or path to virtualenv. If doing an uninstall from the system python and want to use a specific pip bin (pip\-2.7, pip\-2.6, etc..) just specify the pip bin you want. If uninstalling from a virtualenv, just use the path to the virtualenv (/home/code/path/to/virtualenv/) .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.pip.install(pkgs=None, requirements=None, env=None, bin_env=None, log=None, proxy=None, timeout=None, editable=None, find_links=None, index_url=None, extra_index_url=None, no_index=False, mirrors=None, build=None, target=None, download=None, download_cache=None, source=None, upgrade=False, force_reinstall=False, ignore_installed=False, no_deps=False, no_install=False, no_download=False, install_options=None) Install packages with pip .sp Install packages individually or from a pip requirements file. Install packages globally or to a virtualenv. .INDENT 7.0 .TP .B pkgs comma separated list of packages to install .TP .B requirements path to requirements .TP .B bin_env path to pip bin or path to virtualenv. If doing a system install, and want to use a specific pip bin (pip\-2.7, pip\-2.6, etc..) just specify the pip bin you want. If installing into a virtualenv, just use the path to the virtualenv (/home/code/path/to/virtualenv/) .TP .B env depreicated, use bin_env now .TP .B log Log file where a complete (maximum verbosity) record will be kept .TP .B proxy Specify a proxy in the form user:passwd@proxy.server:port. Note that the user:password@ is optional and required only if you are behind an authenticated proxy. If you provide user@proxy.server:port then you will be prompted for a password. .TP .B timeout Set the socket timeout (default 15 seconds) .TP .B editable install something editable(ie git+https://github.com/worldcompany/djangoembed.git#egg=djangoembed) .TP .B find_links URL to look for packages at .TP .B index_url Base URL of Python Package Index .TP .B extra_index_url Extra URLs of package indexes to use in addition to \fBindex_url\fP .TP .B no_index Ignore package index .TP .B mirrors Specific mirror URLs to query (automatically adds \-\-use\-mirrors) .TP .B build Unpack packages into \fBbuild\fP dir .TP .B target Install packages into \fBtarget\fP dir .TP .B download Download packages into \fBdownload\fP instead of installing them .TP .B download_cache Cache downloaded packages in \fBdownload_cache\fP dir .TP .B source Check out \fBeditable\fP packages into \fBsource\fP dir .TP .B upgrade Upgrade all packages to the newest available version .TP .B force_reinstall When upgrading, reinstall all packages even if they are already up\-to\-date. .TP .B ignore_installed Ignore the installed packages (reinstalling instead) .TP .B no_deps Ignore package dependencies .TP .B no_install Download and unpack all packages, but don\(aqt actually install them .TP .B no_download Don\(aqt download any packages, just install the ones already downloaded (completes an install run with \-\-no\-install) .TP .B install_options Extra arguments to be supplied to the setup.py install command (use like \-\-install\-option="\-\-install\- scripts=/usr/local/bin"). Use multiple \-\-install\- option options to pass multiple options to setup.py install. If you are using an option with a directory path, be sure to use absolute path. .UNINDENT .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq pip.install , salt \(aq*\(aq pip.install requirements=/path/to/requirements.txt salt \(aq*\(aq pip.install bin_env=/path/to/virtualenv salt \(aq*\(aq pip.install bin_env=/path/to/pip_bin .ft P .fi .sp Comlicated CLI example: .sp .nf .ft C salt \(aq*\(aq pip.install markdown,django editable=git+https://github.com/worldcompany/djangoembed.git#egg=djangoembed upgrade=True no_deps=True .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.pip.list(prefix=\(aq\(aq, bin_env=None) Filter list of instaslled apps from \fBfreeze\fP and check to see if \fBprefix\fP exists in the list of packages installed. .UNINDENT .INDENT 0.0 .TP .B salt.modules.pip.uninstall(pkgs=None, requirements=None, bin_env=None, log=None, proxy=None, timeout=None) Uninstall packages with pip .sp Uninstall packages individually or from a pip requirements file. Uninstall packages globally or from a virtualenv. .INDENT 7.0 .TP .B pkgs comma separated list of packages to install .TP .B requirements path to requirements .TP .B bin_env path to pip bin or path to virtualenv. If doing an uninstall from the system python and want to use a specific pip bin (pip\-2.7, pip\-2.6, etc..) just specify the pip bin you want. If uninstalling from a virtualenv, just use the path to the virtualenv (/home/code/path/to/virtualenv/) .TP .B log Log file where a complete (maximum verbosity) record will be kept .TP .B proxy Specify a proxy in the form user:passwd@proxy.server:port. Note that the user:password@ is optional and required only if you are behind an authenticated proxy. If you provide user@proxy.server:port then you will be prompted for a password. .TP .B timeout Set the socket timeout (default 15 seconds) .UNINDENT .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq pip.uninstall , salt \(aq*\(aq pip.uninstall requirements=/path/to/requirements.txt salt \(aq*\(aq pip.uninstall bin_env=/path/to/virtualenv salt \(aq*\(aq pip.uninstall bin_env=/path/to/pip_bin .ft P .fi .UNINDENT .SS salt.modules.ps .sp A salt interface to psutil, a system and process library. See \fI\%http://code.google.com/p/psutil\fP. .sp Required python modules: psutil .INDENT 0.0 .TP .B salt.modules.ps.boot_time() Return the boot time in number of seconds since the epoch began. .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq ps.boot_time .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.ps.cached_physical_memory() Return the amount cached memory. .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq ps.cached_physical_memory .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.ps.cpu_percent(interval=0.1, per_cpu=False) Return the percent of time the CPU is busy. .INDENT 7.0 .TP .B interval the number of seconds to sample CPU usage over .TP .B per_cpu if True return an array of CPU percent busy for each CPU, otherwise aggregate all percents into one number .UNINDENT .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq ps.cpu_percent .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.ps.cpu_times(per_cpu=False) Return the percent of time the CPU spends in each state, e.g. user, system, idle, nice, iowait, irq, softirq. .INDENT 7.0 .TP .B per_cpu if True return an array of percents for each CPU, otherwise aggregate all percents into one number .UNINDENT .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq ps.cpu_times .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.ps.disk_io_counters() Return disk I/O statisitics. .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq ps.disk_io_counters .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.ps.disk_partition_usage(all=False) Return a list of disk partitions plus the mount point, filesystem and usage statistics. .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq ps.disk_partition_usage .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.ps.disk_partitions(all=False) Return a list of disk partitions and their device, mount point, and filesystem type. .INDENT 7.0 .TP .B all if set to False, only return local, physical partitions (hard disk, USB, CD/DVD partitions). If True, return all filesystems. .UNINDENT .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq ps.disk_partitions .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.ps.disk_usage(path) Given a path, return a dict listing the total available space as well as the free space, and used space. .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq ps.disk_usage /home .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.ps.get_pid_list() Return a list of process ids (PIDs) for all running processes. .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq ps.get_pid_list .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.ps.network_io_counters() Return network I/O statisitics. .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq ps.network_io_counters .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.ps.num_cpus() Return the number of CPUs. .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq ps.num_cpus .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.ps.physical_memory_buffers() Return the amount of physical memory buffers. .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq ps.physical_memory_buffers .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.ps.physical_memory_usage() Return a dict that describes free and available physical memory. .sp CLI Examples: .sp .nf .ft C salt \(aq*\(aq ps.physical_memory_usage .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.ps.top(num_processes=5, interval=3) Return a list of top CPU consuming processes during the interval. num_processes = return the top N CPU consuming processes interval = the number of seconds to sample CPU usage over .UNINDENT .INDENT 0.0 .TP .B salt.modules.ps.total_physical_memory() Return the total number of bytes of physical memory. .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq ps.total_physical_memory .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.ps.virtual_memory_usage() Return a dict that describes free and available memory, both physical and virtual. .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq virtual_memory_usage .ft P .fi .UNINDENT .SS salt.modules.publish .sp Publish a command from a minion to a target .INDENT 0.0 .TP .B salt.modules.publish.full_data(tgt, fun, arg=None, expr_form=\(aqglob\(aq, returner=\(aq\(aq, timeout=5) Return the full data about the publication, this is invoked in the same way as the publish function .sp CLI Example: .sp .nf .ft C salt system.example.com publish.full_data \(aq*\(aq cmd.run \(aqls \-la /tmp\(aq .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.publish.publish(tgt, fun, arg=None, expr_form=\(aqglob\(aq, returner=\(aq\(aq, timeout=5) Publish a command from the minion out to other minions, publications need to be enabled on the Salt master and the minion needs to have permission to publish the command. The Salt master will also prevent a recursive publication loop, this means that a minion cannot command another minion to command another minion as that would create an infinite command loop. .sp The arguments sent to the minion publish function are separated with commas. This means that for a minion executing a command with multiple args it will look like this: .sp .nf .ft C salt system.example.com publish.publish \(aq*\(aq user.add \(aqfoo,1020,1020\(aq .ft P .fi .sp CLI Example: .sp .nf .ft C salt system.example.com publish.publish \(aq*\(aq cmd.run \(aqls \-la /tmp\(aq .ft P .fi .UNINDENT .SS salt.modules.puppet .sp Execute puppet routines .INDENT 0.0 .TP .B salt.modules.puppet.fact(name) Run facter for a specific fact .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq puppet.fact kernel .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.puppet.facts() Run facter and return the results .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq puppet.facts .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.puppet.noop(tags=None) Execute a puppet noop run and return a dict with the stderr, stdout, return code, etc. If an argument is specified, it is treated as a comma separated list of tags passed to puppetd \-\-test \-\-noop \-\-tags .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq puppet.noop salt \(aq*\(aq puppet.noop web::server,django::base .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.puppet.run(tags=None) Execute a puppet run and return a dict with the stderr, stdout, return code, etc. If an argument is specified, it is treated as a comma separated list of tags passed to puppetd \-\-test \-\-tags: \fI\%http://projects.puppetlabs.com/projects/1/wiki/Using_Tags\fP .sp CLI Examples: .sp .nf .ft C salt \(aq*\(aq puppet.run salt \(aq*\(aq puppet.run basefiles::edit,apache::server .ft P .fi .UNINDENT .SS salt.modules.pw_group .sp Manage groups on Linux .INDENT 0.0 .TP .B salt.modules.pw_group.add(name, gid=None) Add the specified group .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq group.add foo 3456 .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.pw_group.chgid(name, gid) Change the gid for a named group .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq group.chgid foo 4376 .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.pw_group.delete(name) Remove the named group .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq group.delete foo .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.pw_group.getent() Return info on all groups .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq group.getent .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.pw_group.info(name) Return information about a group .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq group.info foo .ft P .fi .UNINDENT .SS salt.modules.pw_user .sp Manage users with the useradd command .INDENT 0.0 .TP .B salt.modules.pw_user.add(name, uid=None, gid=None, groups=None, home=True, shell=None) Add a user to the minion .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq user.add name .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.pw_user.chgid(name, gid) Change the default group of the user .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq user.chgid foo 4376 .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.pw_user.chgroups(name, groups, append=False) Change the groups this user belongs to, add append to append the specified groups .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq user.chgroups foo wheel,root True .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.pw_user.chhome(name, home, persist=False) Change the home directory of the user, pass true for persist to copy files to the new home dir .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq user.chhome foo /home/users/foo True .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.pw_user.chshell(name, shell) Change the default shell of the user .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq user.chshell foo /bin/zsh .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.pw_user.chuid(name, uid) Change the uid for a named user .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq user.chuid foo 4376 .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.pw_user.delete(name, remove=False, force=False) Remove a user from the minion .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq user.delete name True True .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.pw_user.getent() Return the list of all info for all users .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq user.getent .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.pw_user.info(name) Return user information .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq user.info root .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.pw_user.list_groups(name) Return a list of groups the named user belongs to .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq user.groups foo .ft P .fi .UNINDENT .SS salt.modules.rh_service .sp Service support for classic Red Hat type systems. This interface uses the service command (so it is compatible with upstart systems) and the chkconfig command. .INDENT 0.0 .TP .B salt.modules.rh_service.disable(name) Disable the named service to start at boot .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq service.disable .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.rh_service.disabled(name) Check to see if the named service is disabled to start on boot .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq service.disabled .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.rh_service.enable(name) Enable the named service to start at boot .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq service.enable .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.rh_service.enabled(name) Check to see if the named service is enabled to start on boot .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq service.enabled .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.rh_service.get_all() Return all installed services .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq service.get_all .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.rh_service.get_disabled() Return the disabled services .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq service.get_disabled .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.rh_service.get_enabled() Return the enabled services .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq service.get_enabled .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.rh_service.restart(name) Restart the named service .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq service.restart .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.rh_service.start(name) Start the specified service .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq service.start .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.rh_service.status(name, sig=None) Return the status for a service, returns a bool whether the service is running. .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq service.status .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.rh_service.stop(name) Stop the specified service .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq service.stop .ft P .fi .UNINDENT .SS salt.modules.rvm .sp Manage ruby installations and gemsets with RVM, the Ruby Version Manager. .INDENT 0.0 .TP .B salt.modules.rvm.do(ruby, command, runas=None) Execute a command in an RVM controlled environment. .INDENT 7.0 .TP .B ruby: The ruby to use. .TP .B command: The command to execute. .TP .B runas None The user to run rvm as. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.rvm.gemset_copy(source, destination, runas=None) Copy all gems from one gemset to another. .INDENT 7.0 .TP .B source The name of the gemset to copy, complete with ruby version. .TP .B destination The destination gemset. .TP .B runas None The user to run rvm as. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.rvm.gemset_create(ruby, gemset, runas=None) Creates a gemset. .INDENT 7.0 .TP .B ruby The ruby version to create the gemset for. .TP .B gemset The name of the gemset to create. .TP .B runas None The user to run rvm as. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.rvm.gemset_delete(ruby, gemset, runas=None) Deletes a gemset. .INDENT 7.0 .TP .B ruby The ruby version the gemset belongs to. .TP .B gemset The gemset to delete. .TP .B runas None The user to run rvm as. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.rvm.gemset_empty(ruby, gemset, runas=None) Remove all gems from a gemset. .INDENT 7.0 .TP .B ruby The ruby version the gemset belongs to. .TP .B gemset The gemset to empty. .TP .B runas None The user to run rvm as. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.rvm.gemset_list(ruby=\(aqdefault\(aq, runas=None) List all gemsets for the given ruby. .INDENT 7.0 .TP .B ruby default The ruby version to list the gemsets for .TP .B runas None The user to run rvm as. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.rvm.gemset_list_all(runas=None) List all gemsets for all installed rubies. .sp Note that you must have set a default ruby before this can work. .INDENT 7.0 .TP .B runas None The user to run rvm as. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.rvm.get(version=\(aqstable\(aq, runas=None) Update RVM. .INDENT 7.0 .TP .B version stable Which version of RVM to install, e.g. stable or head. .TP .B ruby The version of ruby to reinstall. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.rvm.install() Install RVM system wide. .UNINDENT .INDENT 0.0 .TP .B salt.modules.rvm.install_ruby(ruby, runas=None) Install a ruby implementation. .INDENT 7.0 .TP .B ruby The version of ruby to install. .TP .B runas None The user to run rvm as. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.rvm.is_installed() Check if RVM is installed. .UNINDENT .INDENT 0.0 .TP .B salt.modules.rvm.list(runas=None) List all rvm installed rubies. .INDENT 7.0 .TP .B runas None The user to run rvm as. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.rvm.reinstall_ruby(ruby, runas=None) Reinstall a ruby implementation. .INDENT 7.0 .TP .B ruby The version of ruby to reinstall. .TP .B runas None The user to run rvm as. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.rvm.rubygems(ruby, version, runas=None) Installs a specific rubygems version in the given ruby. .INDENT 7.0 .TP .B ruby The ruby to install rubygems for. .TP .B version The version of rubygems to install or \(aqremove\(aq to use the version that ships with 1.9 .TP .B runas None The user to run rvm as. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.rvm.set_default(ruby, runas=None) Set the default ruby. .INDENT 7.0 .TP .B ruby The version of ruby to make the default. .TP .B runas None The user to run rvm as. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.rvm.wrapper(ruby_string, wrapper_prefix, runas=None, *binaries) Install RVM wrapper scripts. .INDENT 7.0 .TP .B ruby_string Ruby/gemset to install wrappers for. .TP .B wrapper_prefix What to prepend to the name of the generated wrapper binaries. .TP .B runas None The user to run rvm as. .TP .B binaries None The names of the binaries to create wrappers for. When nothing is given, wrappers for ruby, gem, rake, irb, rdoc, ri and testrb are generated. .UNINDENT .UNINDENT .SS salt.modules.saltutil .sp The Saltutil module is used to manage the state of the salt minion itself. It is used to manage minion modules as well as automate updates to the salt minion .INDENT 0.0 .TP .B salt.modules.saltutil.find_job(jid) Return the data for a specific job id .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq saltutil.find_job .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.saltutil.kill_job(jid) Sends a termination signal (SIGTERM 15) to the named salt job\(aqs process .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq saltutil.kill_job .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.saltutil.refresh_pillar() Queue the minion to refresh the pillar data. .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq saltutil.refresh_pillar .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.saltutil.running() Return the data on all running processes salt on the minion .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq saltutil.running .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.saltutil.signal_job(jid, sig) Sends a signal to the named salt job\(aqs process .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq saltutil.signal_job 15 .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.saltutil.sync_all(env=\(aqbase\(aq) Sync down all of the dynamic modules from the file server for a specific environment .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq saltutil.sync_all .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.saltutil.sync_grains(env=\(aqbase\(aq) Sync the grains from the _grains directory on the salt master file server. This function is environment aware, pass the desired environment to grab the contents of the _grains directory, base is the default environment. .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq saltutil.sync_grains .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.saltutil.sync_modules(env=\(aqbase\(aq) Sync the modules from the _modules directory on the salt master file server. This function is environment aware, pass the desired environment to grab the contents of the _modules directory, base is the default environment. .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq saltutil.sync_modules .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.saltutil.sync_renderers(env=\(aqbase\(aq) Sync the renderers from the _renderers directory on the salt master file server. This function is environment aware, pass the desired environment to grab the contents of the _renderers directory, base is the default environment. .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq saltutil.sync_renderers .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.saltutil.sync_returners(env=\(aqbase\(aq) Sync the returners from the _returners directory on the salt master file server. This function is environment aware, pass the desired environment to grab the contents of the _returners directory, base is the default environment. .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq saltutil.sync_returners .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.saltutil.sync_states(env=\(aqbase\(aq) Sync the states from the _states directory on the salt master file server. This function is environment aware, pass the desired environment to grab the contents of the _states directory, base is the default environment. .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq saltutil.sync_states .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.saltutil.term_job(jid) Sends a termination signal (SIGTERM 15) to the named salt job\(aqs process .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq saltutil.term_job .ft P .fi .UNINDENT .SS salt.modules.selinux .sp Execute calls on selinux .INDENT 0.0 .TP .B salt.modules.selinux.getenforce() Return the mode selinux is running in .sp CLE Example: .sp .nf .ft C salt \(aq*\(aq selinux.getenforce .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.selinux.setenforce(mode) Set the enforcing mode .UNINDENT .SS salt.modules.service .sp The default service module, if not otherwise specified salt will fall back to this basic module .INDENT 0.0 .TP .B salt.modules.service.reload(name) Restart the named service .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq service.reload .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.service.restart(name) Restart the named service .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq service.restart .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.service.start(name) Start the specified service .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq service.start .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.service.status(name, sig=None) Return the status for a service, returns the PID or an empty string if the service is running or not, pass a signature to use to find the service via ps .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq service.status [service signature] .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.service.stop(name) Stop the specified service .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq service.stop .ft P .fi .UNINDENT .SS salt.modules.shadow .sp Manage the shadow file .INDENT 0.0 .TP .B salt.modules.shadow.info(name) Return information for the specified user .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq shadow.info root .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.shadow.set_password(name, password) Set the password for a named user. The password must be a properly defined hash, the password hash can be generated with this command: \fBopenssl passwd \-1 \fP .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq shadow.set_password root $1$UYCIxa628.9qXjpQCjM4a.. .ft P .fi .UNINDENT .SS salt.modules.solr .SS Apache Solr Salt Module .sp Author: Jed Glazner Version: 0.2.1 Modified: 12/09/2011 .sp This module uses http requests to talk to the apache solr request handlers to gather information and report errors. Because of this the minion doesn\(aqt necessarily need to reside on the actual slave. However if you want to use the signal function the minion must reside on the physical solr host. .sp This module supports multi\-core and standard setups. Certain methods are master/slave specific. Make sure you set the solr.type. If you have questions or want a feature request please ask. .SS Coming Features in 0.3 .INDENT 0.0 .IP 1. 3 Add command for checking for replication failures on slaves .IP 2. 3 Improve match_index_versions since it\(aqs pointless on busy solr masters .IP 3. 3 Add additional local fs checks for backups to make sure they succeeded .UNINDENT .SS Override these in the minion config .INDENT 0.0 .TP .B solr.cores A list of core names eg [\(aqcore1\(aq,\(aqcore2\(aq]. An empty list indicates non\-multicore setup. .TP .B solr.baseurl The root level url to access solr via http .TP .B solr.request_timeout The number of seconds before timing out an http/https/ftp request. If nothing is specified then the python global timeout setting is used. .TP .B solr.type Possible values are \(aqmaster\(aq or \(aqslave\(aq .TP .B solr.backup_path The path to store your backups. If you are using cores and you can specify to append the core name to the path in the backup method. .TP .B solr.num_backups For versions of solr >= 3.5. Indicates the number of backups to keep. This option is ignored if your version is less. .TP .B solr.init_script The full path to your init script with start/stop options .TP .B solr.dih.options A list of options to pass to the dih. .UNINDENT .SS Required Options for DIH .INDENT 0.0 .TP .B clean False Clear the index before importing .TP .B commit True Commit the documents to the index upon completion .TP .B optimize True Optimize the index after commit is complete .TP .B verbose True Get verbose output .UNINDENT .INDENT 0.0 .TP .B salt.modules.solr.abort_import(handler, host=None, core_name=None, verbose=False) MASTER ONLY Aborts an existing import command to the specified handler. This command can only be run if the minion is is configured with solr.type=master .INDENT 7.0 .TP .B handler str The name of the data import handler. .TP .B host str (None) The solr host to query. __opts__[\(aqhost\(aq] is default. .TP .B core str (None) The core the handler belongs to. .TP .B verbose boolean (False) Run the command with verbose output. .UNINDENT .sp Return : dict<str,obj>: .sp .nf .ft C {\(aqsuccess\(aq:boolean, \(aqdata\(aq:dict, \(aqerrors\(aq:list, \(aqwarnings\(aq:list} .ft P .fi .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq solr.abort_import dataimport None music {\(aqclean\(aq:True} .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.solr.backup(host=None, core_name=None, append_core_to_path=False) Tell solr make a backup. This method can be mis\-leading since it uses the backup api. If an error happens during the backup you are not notified. The status: \(aqOK\(aq in the response simply means that solr received the request successfully. .INDENT 7.0 .TP .B host str (None) The solr host to query. __opts__[\(aqhost\(aq] is default. .TP .B core_name str (None) The name of the solr core if using cores. Leave this blank if you are not using cores or if you want to check all cores. .TP .B append_core_to_path boolean (False) If True add the name of the core to the backup path. Assumes that minion backup path is not None. .UNINDENT .sp Return : dict<str,obj>: .sp .nf .ft C {\(aqsuccess\(aq:boolean, \(aqdata\(aq:dict, \(aqerrors\(aq:list, \(aqwarnings\(aq:list} .ft P .fi .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq solr.backup music .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.solr.core_status(host=None, core_name=None) MULTI\-CORE HOSTS ONLY Get the status for a given core or all cores if no core is specified .INDENT 7.0 .TP .B host str (None) The solr host to query. __opts__[\(aqhost\(aq] is default. .TP .B core_name str The name of the core to reload .UNINDENT .sp Return : dict<str,obj>: .sp .nf .ft C {\(aqsuccess\(aq:boolean, \(aqdata\(aq:dict, \(aqerrors\(aq:list, \(aqwarnings\(aq:list} .ft P .fi .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq solr.core_status None music .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.solr.delta_import(handler, host=None, core_name=None, options={}, extra=[]) Submits an import command to the specified handler using specified options. This command can only be run if the minion is is configured with solr.type=master .INDENT 7.0 .TP .B handler str The name of the data import handler. .TP .B host str (None) The solr host to query. __opts__[\(aqhost\(aq] is default. .TP .B core str (None) The core the handler belongs to. .TP .B options dict (__opts__) A list of options such as clean, optimize commit, verbose, and pause_replication. leave blank to use __opts__ defaults. options will be merged with __opts__ .TP .B extra dict ([]) Extra name value pairs to pass to the handler. eg ["name=value"] .UNINDENT .sp Return : dict<str,obj>: .sp .nf .ft C {\(aqsuccess\(aq:boolean, \(aqdata\(aq:dict, \(aqerrors\(aq:list, \(aqwarnings\(aq:list} .ft P .fi .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq solr.delta_import dataimport None music {\(aqclean\(aq:True} .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.solr.full_import(handler, host=None, core_name=None, options={}, extra=[]) MASTER ONLY Submits an import command to the specified handler using specified options. This command can only be run if the minion is is configured with solr.type=master .INDENT 7.0 .TP .B handler str The name of the data import handler. .TP .B host str (None) The solr host to query. __opts__[\(aqhost\(aq] is default. .TP .B core str (None) The core the handler belongs to. .TP .B options dict (__opts__) A list of options such as clean, optimize commit, verbose, and pause_replication. leave blank to use __opts__ defaults. options will be merged with __opts__ .TP .B extra dict ([]) Extra name value pairs to pass to the handler. e.g. ["name=value"] .UNINDENT .sp Return : dict<str,obj>: .sp .nf .ft C {\(aqsuccess\(aq:boolean, \(aqdata\(aq:dict, \(aqerrors\(aq:list, \(aqwarnings\(aq:list} .ft P .fi .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq solr.full_import dataimport None music {\(aqclean\(aq:True} .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.solr.import_status(handler, host=None, core_name=None, verbose=False) Submits an import command to the specified handler using specified options. This command can only be run if the minion is is configured with solr.type: \(aqmaster\(aq .INDENT 7.0 .TP .B handler str The name of the data import handler. .TP .B host str (None) The solr host to query. __opts__[\(aqhost\(aq] is default. .TP .B core str (None) The core the handler belongs to. .TP .B verbose boolean (False) Specifies verbose output .UNINDENT .sp Return : dict<str,obj>: .sp .nf .ft C {\(aqsuccess\(aq:boolean, \(aqdata\(aq:dict, \(aqerrors\(aq:list, \(aqwarnings\(aq:list} .ft P .fi .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq solr.import_status dataimport None music False .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.solr.is_replication_enabled(host=None, core_name=None) SLAVE CALL Check for errors, and determine if a slave is replicating or not. .INDENT 7.0 .TP .B host str (None) The solr host to query. __opts__[\(aqhost\(aq] is default. .TP .B core_name str (None) The name of the solr core if using cores. Leave this blank if you are not using cores or if you want to check all cores. .UNINDENT .sp Return : dict<str,obj>: .sp .nf .ft C {\(aqsuccess\(aq:boolean, \(aqdata\(aq:dict, \(aqerrors\(aq:list, \(aqwarnings\(aq:list} .ft P .fi .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq solr.is_replication_enabled music .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.solr.lucene_version(core_name=None) Gets the lucene version that solr is using. If you are running a multi\-core setup you should specify a core name since all the cores run under the same servlet container, they will all have the same version. .INDENT 7.0 .TP .B core_name str (None) The name of the solr core if using cores. Leave this blank if you are not using cores or if you want to check all cores. .UNINDENT .sp Return: dict<str,obj>: .sp .nf .ft C {\(aqsuccess\(aq:boolean, \(aqdata\(aq:dict, \(aqerrors\(aq:list, \(aqwarnings\(aq:list} .ft P .fi .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq solr.lucene_version .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.solr.match_index_versions(host=None, core_name=None) SLAVE CALL Verifies that the master and the slave versions are in sync by comparing the index version. If you are constantly pushing updates the index the master and slave versions will seldom match. A solution to this is pause indexing every so often to allow the slave to replicate and then call this method before allowing indexing to resume. .INDENT 7.0 .TP .B host str (None) The solr host to query. __opts__[\(aqhost\(aq] is default. .TP .B core_name str (None) The name of the solr core if using cores. Leave this blank if you are not using cores or if you want to check all cores. .UNINDENT .sp Return : dict<str,obj>: .sp .nf .ft C {\(aqsuccess\(aq:boolean, \(aqdata\(aq:dict, \(aqerrors\(aq:list, \(aqwarnings\(aq:list} .ft P .fi .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq solr.match_index_versions music .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.solr.optimize(host=None, core_name=None) Search queries fast, but it is a very expensive operation. The ideal process is to run this with a master/slave configuration. Then you can optimize the master, and push the optimized index to the slaves. If you are running a single solr instance, or if you are going to run this on a slave be aware than search performance will be horrible while this command is being run. Additionally it can take a LONG time to run and your http request may timeout. If that happens adjust your timeout settings. .INDENT 7.0 .TP .B host str (None) The solr host to query. __opts__[\(aqhost\(aq] is default. .TP .B core_name str (None) The name of the solr core if using cores. Leave this blank if you are not using cores or if you want to check all cores. .UNINDENT .sp Return : dict<str,obj>: .sp .nf .ft C {\(aqsuccess\(aq:boolean, \(aqdata\(aq:dict, \(aqerrors\(aq:list, \(aqwarnings\(aq:list} .ft P .fi .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq solr.optimize music .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.solr.ping(host=None, core_name=None) Does a health check on solr, makes sure solr can talk to the indexes. .INDENT 7.0 .TP .B host str (None) The solr host to query. __opts__[\(aqhost\(aq] is default. .TP .B core_name str (None) The name of the solr core if using cores. Leave this blank if you are not using cores or if you want to check all cores. .UNINDENT .sp Return : dict<str,obj>: .sp .nf .ft C {\(aqsuccess\(aq:boolean, \(aqdata\(aq:dict, \(aqerrors\(aq:list, \(aqwarnings\(aq:list} .ft P .fi .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq solr.ping music .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.solr.reload_core(host=None, core_name=None) MULTI\-CORE HOSTS ONLY Load a new core from the same configuration as an existing registered core. While the "new" core is initializing, the "old" one will continue to accept requests. Once it has finished, all new request will go to the "new" core, and the "old" core will be unloaded. .INDENT 7.0 .TP .B host str (None) The solr host to query. __opts__[\(aqhost\(aq] is default. .TP .B core_name str The name of the core to reload .UNINDENT .sp Return : dict<str,obj>: .sp .nf .ft C {\(aqsuccess\(aq:boolean, \(aqdata\(aq:dict, \(aqerrors\(aq:list, \(aqwarnings\(aq:list} .ft P .fi .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq solr.reload_core None music {\(aqsuccess\(aq:bool, \(aqdata\(aq:dict, \(aqerrors\(aq:list, \(aqwarnings\(aq:list} .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.solr.reload_import_config(handler, host=None, core_name=None, verbose=False) MASTER ONLY re\-loads the handler config XML file. This command can only be run if the minion is a \(aqmaster\(aq type .INDENT 7.0 .TP .B handler str The name of the data import handler. .TP .B host str (None) The solr host to query. __opts__[\(aqhost\(aq] is default. .TP .B core str (None) The core the handler belongs to. .TP .B verbose boolean (False) Run the command with verbose output. .UNINDENT .sp Return : dict<str,obj>: .sp .nf .ft C {\(aqsuccess\(aq:boolean, \(aqdata\(aq:dict, \(aqerrors\(aq:list, \(aqwarnings\(aq:list} .ft P .fi .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq solr.reload_import_config dataimport None music {\(aqclean\(aq:True} .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.solr.replication_details(host=None, core_name=None) Get the full replication details. .INDENT 7.0 .TP .B host str (None) The solr host to query. __opts__[\(aqhost\(aq] is default. .TP .B core_name str (None) The name of the solr core if using cores. Leave this blank if you are not using cores or if you want to check all cores. .UNINDENT .sp Return : dict<str,obj>: .sp .nf .ft C {\(aqsuccess\(aq:boolean, \(aqdata\(aq:dict, \(aqerrors\(aq:list, \(aqwarnings\(aq:list} .ft P .fi .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq solr.replication_details music .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.solr.set_is_polling(polling, host=None, core_name=None) SLAVE CALL Prevent the slaves from polling the master for updates. .INDENT 7.0 .TP .B polling boolean True will enable polling. False will disable it. .TP .B host str (None) The solr host to query. __opts__[\(aqhost\(aq] is default. .TP .B core_name str (None) The name of the solr core if using cores. Leave this blank if you are not using cores or if you want to check all cores. .UNINDENT .sp Return : dict<str,obj>: .sp .nf .ft C {\(aqsuccess\(aq:boolean, \(aqdata\(aq:dict, \(aqerrors\(aq:list, \(aqwarnings\(aq:list} .ft P .fi .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq solr.set_is_polling False .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.solr.set_replication_enabled(status, host=None, core_name=None) MASTER ONLY Sets the master to ignore poll requests from the slaves. Useful when you don\(aqt want the slaves replicating during indexing or when clearing the index. .INDENT 7.0 .TP .B status boolean Sets the replication status to the specified state. .TP .B host str (None) The solr host to query. __opts__[\(aqhost\(aq] is default. .TP .B core_name str (None) The name of the solr core if using cores. Leave this blank if you are not using cores or if you want to set the status on all cores. .UNINDENT .sp Return : dict<str,obj>: .sp .nf .ft C {\(aqsuccess\(aq:boolean, \(aqdata\(aq:dict, \(aqerrors\(aq:list, \(aqwarnings\(aq:list} .ft P .fi .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq solr.set_replication_enabled false, None, music .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.solr.signal(signal=None) Signals Apache Solr to start, stop, or restart. Obviously this is only going to work if the minion resides on the solr host. Additionally Solr doesn\(aqt ship with an init script so one must be created. .INDENT 7.0 .TP .B signal str (None) The command to pass to the apache solr init valid values are \(aqstart\(aq, \(aqstop\(aq, and \(aqrestart\(aq .UNINDENT .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq solr.signal restart .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.solr.version(core_name=None) Gets the solr version for the core specified. You should specify a core here as all the cores will run under the same servlet container and so will all have the same version. .INDENT 7.0 .TP .B core_name str (None) The name of the solr core if using cores. Leave this blank if you are not using cores or if you want to check all cores. .UNINDENT .sp Return : dict<str,obj>: .sp .nf .ft C {\(aqsuccess\(aq:boolean, \(aqdata\(aq:dict, \(aqerrors\(aq:list, \(aqwarnings\(aq:list} .ft P .fi .sp CLI Example: .sp .nf .ft C alt \(aq*\(aq solr.version .ft P .fi .UNINDENT .SS salt.modules.ssh .sp Manage client ssh components .INDENT 0.0 .TP .B salt.modules.ssh.auth_keys(user, config=\(aq.ssh/authorized_keys\(aq) Return the authorized keys for the specified user .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq ssh.auth_keys root .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.ssh.host_keys(keydir=None) Return the minion\(aqs host keys .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq ssh.host_keys .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.ssh.rm_auth_key(user, key, config=\(aq.ssh/authorized_keys\(aq) Remove an authorized key from the specified user\(aqs authorized key file .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq ssh.rm_auth_key <user> <key> .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.ssh.set_auth_key(user, key, enc=\(aqssh\-rsa\(aq, comment=\(aq\(aq, options=[], config=\(aq.ssh/authorized_keys\(aq) Add a key to the authorized_keys file .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq ssh.set_auth_key <user> <key> dsa \(aqmy key\(aq \(aq[]\(aq .ssh/authorized_keys .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.ssh.set_auth_key_from_file(user, source, config=\(aq.ssh/authorized_keys\(aq) Add a key to the authorized_keys file, using a file as the source. .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq ssh.set_auth_key_from_file <user> salt://ssh_keys/<user>.id_rsa.pub .ft P .fi .UNINDENT .SS salt.modules.state .sp Control the state system on the minion .INDENT 0.0 .TP .B salt.modules.state.high(data) Execute the compound calls stored in a single set of high data This function is mostly intended for testing the state system .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq state.high \(aq{"vim": {"pkg": ["installed"]}}\(aq .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.state.highstate() Retrive the state data from the salt master for this minion and execute it .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq state.highstate .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.state.low(data) Execute a single low data call This function is mostly intended for testing the state system .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq state.low \(aq{"state": "pkg", "fun": "installed", "name": "vi"}\(aq .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.state.show_highstate() Retrieve the highstate data from the salt master and display it .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq state.show_highstate .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.state.show_lowstate() List out the low data that will be applied to this minion .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq state.show_lowstate .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.state.show_masterstate() Display the data gathered from the master compiled state .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq state.show_masterstate .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.state.sls(mods, env=\(aqbase\(aq) Execute a set list of state modules from an environment, default environment is base .sp CLI Example: .INDENT 7.0 .INDENT 3.5 salt \(aq*\(aq state.sls core,edit.vim dev .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.state.template(tem) Execute the information stored in a template file on the minion .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq state.template \(aq<Path to template on the minion>\(aq .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.state.template_str(tem) Execute the information stored in a template file on the minion .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq state.template_str \(aq<Template String>\(aq .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.state.top(topfn) Execute a specific top file instead of the default .UNINDENT .SS salt.modules.status .sp Module for returning various status data about a minion. These data can be useful for compiling into stats later. .INDENT 0.0 .TP .B salt.modules.status.all_status() Return a composite of all status data and info for this minion. Warning: There is a LOT here! .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq status.all_status .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.status.cpuinfo() Return the CPU info for this minion .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq status.cpuinfo .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.status.cpustats() Return the CPU stats for this minon .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq status.cpustats .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.status.custom() Return a custom composite of status data and info for this minon, based on the minion config file. An example config like might be: .sp .nf .ft C status.cpustats.custom: [ \(aqcpu\(aq, \(aqctxt\(aq, \(aqbtime\(aq, \(aqprocesses\(aq ] .ft P .fi .sp Where status refers to status.py, cpustats is the function where we get our data, and custom is this function It is followed by a list of keys that we want returned. .sp This function is meant to replace all_status(), which returns anything and everything, which we probably don\(aqt want. .sp By default, nothing is returned. Warning: Depending on what you include, there can be a LOT here! .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq status.custom .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.status.diskstats() Return the disk stats for this minion .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq status.diskstats .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.status.diskusage(*args) Return the disk usage for this minion .sp Usage: .sp .nf .ft C salt \(aq*\(aq status.diskusage [paths and/or filesystem types] .ft P .fi .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq status.diskusage # usage for all filesystems salt \(aq*\(aq status.diskusage / /tmp # usage for / and /tmp salt \(aq*\(aq status.diskusage ext? # usage for ext[234] filesystems salt \(aq*\(aq status.diskusage / ext? # usage for / and all ext filesystems .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.status.loadavg() Return the load averages for this minion .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq status.loadavg .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.status.meminfo() Return the CPU stats for this minion .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq status.meminfo .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.status.netdev() Return the network device stats for this minion .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq status.netdev .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.status.netstats() Return the network stats for this minion .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq status.netstats .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.status.procs() Return the process data .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq status.procs .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.status.uptime() Return the uptime for this minion .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq status.uptime .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.status.vmstats() Return the virtual memory stats for this minion .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq status.vmstats .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.status.w() Return a list of logged in users for this minion, using the w command .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq status.w .ft P .fi .UNINDENT .SS salt.modules.systemd .sp Provide the service module for systemd .INDENT 0.0 .TP .B salt.modules.systemd.disable(name) Disable the named service to not start when the system boots .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq service.disable <service name> .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.systemd.disabled(name) Return if the named service is disabled to start on boot .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq service.disabled <service name> .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.systemd.enable(name) Enable the named service to start when the system boots .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq service.enable <service name> .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.systemd.enabled(name) Return if the named service is enabled to start on boot .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq service.enabled <service name> .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.systemd.get_all() Return a list of all available services .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq service.get_all .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.systemd.get_disabled() Return a list of all disabled services .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq service.get_disabled .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.systemd.get_enabled() Return a list of all enabled services .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq service.get_enabled .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.systemd.restart(name) Start the specified service with systemd .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq service.start <service name> .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.systemd.start(name) Start the specified service with systemd .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq service.start <service name> .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.systemd.status(name, sig=None) Return the status for a service via systemd, returns the PID if the service is running or an empty string if the service is not running .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq service.status <service name> .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.systemd.stop(name) Stop the specifed service with systemd .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq service.stop <service name> .ft P .fi .UNINDENT .SS salt.modules.test .sp Module for running arbitrary tests .INDENT 0.0 .TP .B salt.modules.test.collatz(start) Execute the collatz conjecture from the passed starting number, returns the sequence and the time it took to compute. Used for performance tests. .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq test.collatz 3 .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.test.conf_test() Return the value for test.foo in the minion configuration file, or return the default value .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq test.conf_test .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.test.cross_test(func, args=None) Execute a minion function via the __salt__ object in the test module, used to verify that the minion functions can be called via the __salt__ module. .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq test.cross_test file.gid_to_group 0 .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.test.echo(text) Return a string \- used for testing the connection .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq test.echo \(aqfoo bar baz quo qux\(aq .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.test.fib(num) Return a Fibonacci sequence up to the passed number, and the timeit took to compute in seconds. Used for performance tests .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq test.fib 3 .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.test.get_opts() Return the configuration options passed to this minion .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq test.get_opts .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.test.kwarg(**kwargs) Print out the data passed into the function \fB**kwargs\fP, this is used to both test the publication data and cli kwarg passing, but also to display the information available within the publication data. .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq test.kwarg .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.test.outputter(data) Test the outputter, pass in data to return .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq test.outputter foobar .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.test.ping() Just used to make sure the minion is up and responding Return True .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq test.ping .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.test.version() Return the version of salt on the minion .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq test.version .ft P .fi .UNINDENT .SS salt.modules.tomcat .sp Support for Tomcat .INDENT 0.0 .TP .B salt.modules.tomcat.fullversion() Return all server information from catalina.sh version .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq tomcat.fullversion .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.tomcat.signal(signal=None) Signals catalina to start, stop, securestart, forcestop. .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq tomcat.signal start .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.tomcat.version() Return server version from catalina.sh version .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq tomcat.version .ft P .fi .UNINDENT .SS salt.modules.upstart .sp Module for the management of upstart systems. The Upstart system only supports service starting, stopping and restarting. .sp DO NOT use this module on red hat systems, as red hat systems should use the rh_service module, since red hat systems support chkconfig .INDENT 0.0 .TP .B salt.modules.upstart.disable(name) Disable the named service from starting on boot .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq service.disable <service name> .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.upstart.enable(name) Enable the named service to start at boot .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq service.enable <service name> .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.upstart.restart(name) Restart the named service .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq service.restart <service name> .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.upstart.start(name) Start the specified service .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq service.start <service name> .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.upstart.status(name, sig=None) Return the status for a service, returns a bool whether the service is running. .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq service.status <service name> .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.upstart.stop(name) Stop the specified service .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq service.stop <service name> .ft P .fi .UNINDENT .SS salt.modules.useradd .sp Manage users with the useradd command .INDENT 0.0 .TP .B salt.modules.useradd.add(name, uid=None, gid=None, groups=None, home=True, shell=None, fullname=None, roomnumber=None, workphone=None, homephone=None, other=None) Add a user to the minion .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq user.add name <uid> <gid> <groups> <home> <shell> .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.useradd.chfullname(name, fullname) Change the users Full Name .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq user.chfullname foo "Foo Bar" .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.useradd.chgid(name, gid) Change the default group of the user .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq user.chgid foo 4376 .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.useradd.chgroups(name, groups, append=False) Change the groups this user belongs to, add append to append the specified groups .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq user.chgroups foo wheel,root True .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.useradd.chhome(name, home, persist=False) Change the home directory of the user, pass true for persist to copy files to the new home dir .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq user.chhome foo /home/users/foo True .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.useradd.chhomephone(name, homephone) Change the user\(aqs Home Phone .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq user.chhomephone foo "7735551234" .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.useradd.chother(name, other) Change the user\(aqs "Other" GECOS field .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq user.chother foo "fax=7735555678" .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.useradd.chroomnumber(name, roomnumber) Change the user\(aqs Room Number .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq user.chroomnumber foo 123 .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.useradd.chshell(name, shell) Change the default shell of the user .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq user.chshell foo /bin/zsh .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.useradd.chuid(name, uid) Change the uid for a named user .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq user.chuid foo 4376 .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.useradd.chworkphone(name, workphone) Change the user\(aqs Work Phone .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq user.chworkphone foo "7735550123" .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.useradd.delete(name, remove=False, force=False) Remove a user from the minion .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq user.delete name True True .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.useradd.getent() Return the list of all info for all users .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq user.getent .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.useradd.info(name) Return user information .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq user.info root .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.useradd.list_groups(name) Return a list of groups the named user belongs to .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq user.groups foo .ft P .fi .UNINDENT .SS salt.modules.virt .sp Work with virtual machines managed by libvirt .sp Required python modules: libvirt .INDENT 0.0 .TP .B salt.modules.virt.create(vm_) Start a defined domain .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq virt.create <vm name> .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.virt.create_xml_path(path) Start a defined domain .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq virt.create_xml_path <path to xml file on the node> .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.virt.create_xml_str(xml) Start a domain based on the xml passed to the function .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq virt.create_xml_str <xml in string format> .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.virt.destroy(vm_) Hard power down the virtual machine, this is equivalent to pulling the power .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq virt.destroy <vm name> .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.virt.freecpu() Return an int representing the number of unallocated cpus on this hypervisor .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq virt.freecpu .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.virt.freemem() Return an int representing the amount of memory that has not been given to virtual machines on this node .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq virt.freemem .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.virt.full_info() Return the node_info, vm_info and freemem .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq virt.full_info .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.virt.get_disks(vm_) Return the disks of a named vm .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq virt.get_disks <vm name> .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.virt.get_graphics(vm_) Returns the information on vnc for a given vm .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq virt.get_graphics <vm name> .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.virt.get_macs(vm_) Return a list off MAC addresses from the named vm .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq virt.get_macs <vm name> .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.virt.get_nics(vm_) Return info about the network interfaces of a named vm .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq virt.get_nics <vm name> .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.virt.get_xml(vm_) Returns the xml for a given vm .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq virt.get_xml <vm name> .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.virt.is_hyper() Returns a bool whether or not this nos is a hypervisor of any kind .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq virt.is_hyper .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.virt.is_kvm_hyper() Returns a bool whether or not this node is a KVM hypervisor .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq virt.is_kvm_hyper .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.virt.is_xen_hyper() Returns a bool whether or not this node is a XEN hypervisor .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq virt.is_xen_hyper .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.virt.list_active_vms() Return a list of names for active virtual machine on the minion .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq virt.list_active_vms .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.virt.list_inactive_vms() Return a list of names for inactive virtual machine on the minion .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq virt.list_inactive_vms .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.virt.list_vms() Return a list of virtual machine names on the minion .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq virt.list_vms .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.virt.migrate(vm_, target) Shared storage migration .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq virt.migrate <vm name> <target hypervisor> .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.virt.migrate_non_shared(vm_, target) Attempt to execute non\-shared storage "all" migration .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq virt.migrate_non_shared <vm name> <target hypervisor> .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.virt.migrate_non_shared_inc(vm_, target) Attempt to execute non\-shared storage "all" migration .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq virt.migrate_non_shared_inc <vm name> <target hypervisor> .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.virt.node_info() Return a dict with information about this node .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq virt.node_info .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.virt.pause(vm_) Pause the named vm .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq virt.pause <vm name> .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.virt.purge(vm_, dirs=False) Recursively destroy and delete a virtual machine, pass True for dir\(aqs to also delete the directories containing the virtual machine disk images \- USE WITH EXTREME CAUTION! .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq virt.purge <vm name> .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.virt.resume(vm_) Resume the named vm .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq virt.resume <vm name> .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.virt.seed_non_shared_migrate(disks, force=False) Non shared migration requires that the disks be present on the migration destination, pass the disks information via this function, to the migration destination before executing the migration. .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq virt.seed_non_shared_migrate <disks> .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.virt.set_autostart(vm_, state=\(aqon\(aq) Set the autostart flag on a VM so that the VM will start with the host system on reboot. .INDENT 7.0 .TP .B CLI Example:: salt "*" virt.enable_autostart <vm name> <on | off> .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.virt.shutdown(vm_) Send a soft shutdown signal to the named vm .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq virt.shutdown <vm name> .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.virt.start(vm_) Alias for the obscurely named \(aqcreate\(aq function .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq virt.start <vm name> .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.virt.undefine(vm_) Remove a defined vm, this does not purge the virtual machine image, and this only works if the vm is powered down .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq virt.undefine <vm name> .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.virt.virt_type() Returns the virtual machine type as a string .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq virt.virt_type .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.virt.vm_info() Return detailed information about the vms on this hyper in a dict: .sp .nf .ft C {\(aqcpu\(aq: <int>, \(aqmaxMem\(aq: <int>, \(aqmem\(aq: <int>, \(aqstate\(aq: \(aq<state>\(aq, \(aqcputime\(aq <int>} .ft P .fi .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq virt.vm_info .ft P .fi .UNINDENT .SS salt.modules.virtualenv .sp Create virtualenv environments .INDENT 0.0 .TP .B salt.modules.virtualenv.create(path, venv_bin=\(aqvirtualenv\(aq, no_site_packages=False, system_site_packages=False, distribute=False, clear=False, python=\(aq\(aq, extra_search_dir=\(aq\(aq, never_download=False, prompt=\(aq\(aq, runas=None) Create a virtualenv .INDENT 7.0 .TP .B path The path to create the virtualenv .TP .B venv_bin \(aqvirtualenv\(aq The name (and optionally path) of the virtualenv command. This can also be set globally in the minion config file as \fBvirtualenv.venv_bin\fP. .TP .B no_site_packages False Passthrough argument given to virtualenv .TP .B system_site_packages False Passthrough argument given to virtualenv .TP .B distribute False Passthrough argument given to virtualenv .TP .B clear False Passthrough argument given to virtualenv .TP .B python (default) Passthrough argument given to virtualenv .TP .B extra_search_dir (default) Passthrough argument given to virtualenv .TP .B never_download (default) Passthrough argument given to virtualenv .TP .B prompt (default) Passthrough argument given to virtualenv .TP .B runas None Set ownership for the virtualenv .UNINDENT .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq pip.virtualenv /path/to/new/virtualenv .ft P .fi .UNINDENT .SS salt.modules.win_disk .sp Module for gathering disk information on Windows .INDENT 0.0 .TP .B salt.modules.win_disk.usage() Return usage information for volumes mounted on this minion .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq disk.usage .ft P .fi .UNINDENT .SS salt.modules.win_file .sp Manage information about files on the minion, set/read user, group data .sp Required python modules: win32api, win32con, win32security, ntsecuritycon .INDENT 0.0 .TP .B salt.modules.win_file.append(path, *args) Append text to the end of a file .sp Usage: .sp .nf .ft C salt \(aq*\(aq file.append /etc/motd \e "With all thine offerings thou shalt offer salt."\e "Salt is what makes things taste bad when it isn\(aqt in them." .ft P .fi .sp New in version 0.9.5. .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_file.chgrp(path, group) Change the group of a file .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq file.chgrp c:\etemp\etest.txt administrators .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_file.chown(path, user, group) Chown a file, pass the file the desired user and group .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq file.chown c:\etemp\etest.txt myusername administrators .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_file.comment(path, regex, char=\(aq#\(aq, backup=\(aq.bak\(aq) Comment out specified lines in a file .INDENT 7.0 .TP .B path The full path to the file to be edited .TP .B regex A regular expression used to find the lines that are to be commented; this pattern will be wrapped in parenthesis and will move any preceding/trailing \fB^\fP or \fB$\fP characters outside the parenthesis (e.g., the pattern \fB^foo$\fP will be rewritten as \fB^(foo)$\fP) .TP .B char \fB#\fP The character to be inserted at the beginning of a line in order to comment it out .TP .B backup \fB.bak\fP The file will be backed up before edit with this file extension .IP Warning This backup will be overwritten each time \fBsed\fP / \fBcomment\fP / \fBuncomment\fP is called. Meaning the backup will only be useful after the first invocation. .RE .UNINDENT .sp Usage: .sp .nf .ft C salt \(aq*\(aq file.comment /etc/modules pcspkr .ft P .fi .sp New in version 0.9.5. .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_file.contains(path, text, limit=\(aq\(aq) Return True if the file at \fBpath\fP contains \fBtext\fP .sp Usage: .sp .nf .ft C salt \(aq*\(aq file.contains /etc/crontab \(aqmymaintenance.sh\(aq .ft P .fi .sp New in version 0.9.5. .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_file.find(path, *opts) Approximate the Unix find(1) command and return a list of paths that meet the specified critera. .sp The options include match criteria: .sp .nf .ft C name = path\-glob # case sensitive iname = path\-glob # case insensitive regex = path\-regex # case sensitive iregex = path\-regex # case insensitive type = file\-types # match any listed type user = users # match any listed user group = groups # match any listed group size = [+\-]number[size\-unit] # default unit = byte mtime = interval # modified since date grep = regex # search file contents .ft P .fi .sp and/or actions: .sp .nf .ft C delete [= file\-types] # default type = \(aqf\(aq exec = command [arg ...] # where {} is replaced by pathname print [= print\-opts] .ft P .fi .sp The default action is \(aqprint=path\(aq. .sp file\-glob: .sp .nf .ft C * = match zero or more chars ? = match any char [abc] = match a, b, or c [!abc] or [^abc] = match anything except a, b, and c [x\-y] = match chars x through y [!x\-y] or [^x\-y] = match anything except chars x through y {a,b,c} = match a or b or c .ft P .fi .sp path\-regex: a Python re (regular expression) pattern to match pathnames .sp file\-types: a string of one or more of the following: .sp .nf .ft C a: all file types b: block device c: character device d: directory p: FIFO (named pipe) f: plain file l: symlink s: socket .ft P .fi .sp users: a space and/or comma separated list of user names and/or uids .sp groups: a space and/or comma separated list of group names and/or gids .sp size\-unit: .sp .nf .ft C b: bytes k: kilobytes m: megabytes g: gigabytes t: terabytes .ft P .fi .sp interval: .sp .nf .ft C [<num>w] [<num>[d]] [<num>h] [<num>m] [<num>s] where: w: week d: day h: hour m: minute s: second .ft P .fi .sp print\-opts: a comma and/or space separated list of one or more of the following: .sp .nf .ft C group: group name md5: MD5 digest of file contents mode: file permissions (as integer) mtime: last modification time (as time_t) name: file basename path: file absolute path size: file size in bytes type: file type user: user name .ft P .fi .sp CLI Examples: .sp .nf .ft C salt \(aq*\(aq file.find / type=f name=\e*.bak size=+10m salt \(aq*\(aq file.find /var mtime=+30d size=+10m print=path,size,mtime salt \(aq*\(aq file.find /var/log name=\e*.[0\-9] mtime=+30d size=+10m delete .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_file.get_gid(path) Return the id of the group that owns a given file .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq file.get_gid c:\etemp\etest.txt .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_file.get_group(path) Return the group that owns a given file .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq file.get_group c:\etemp\etest.txt .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_file.get_mode(path) Return the mode of a file .sp Right now we\(aqre just returning 777 because Windows\(aq doesn\(aqt have a mode like Linux .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq file.get_mode /etc/passwd .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_file.get_sum(path, form=\(aqmd5\(aq) Return the sum for the given file, default is md5, sha1, sha224, sha256, sha384, sha512 are supported .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq file.get_sum /etc/passwd sha512 .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_file.get_uid(path) Return the id of the user that owns a given file .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq file.get_uid c:\etemp\etest.txt .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_file.get_user(path) Return the user that owns a given file .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq file.get_user c:\etemp\etest.txt .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_file.gid_to_group(gid) Convert the group id to the group name on this system .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq file.gid_to_group S\-1\-5\-21\-626487655\-2533044672\-482107328\-1010 .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_file.group_to_gid(group) Convert the group to the gid on this system .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq file.group_to_gid administrators .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_file.sed(path, before, after, limit=\(aq\(aq, backup=\(aq.bak\(aq, options=\(aq\-r \-e\(aq, flags=\(aqg\(aq) Make a simple edit to a file .sp Equivalent to: .sp .nf .ft C sed <backup> <options> "/<limit>/ s/<before>/<after>/<flags> <file>" .ft P .fi .INDENT 7.0 .TP .B path The full path to the file to be edited .TP .B before A pattern to find in order to replace with \fBafter\fP .TP .B after Text that will replace \fBbefore\fP .TP .B limit \fB\(aq\(aq\fP An initial pattern to search for before searching for \fBbefore\fP .TP .B backup \fB.bak\fP The file will be backed up before edit with this file extension; \fBWARNING:\fP each time \fBsed\fP/\fBcomment\fP/\fBuncomment\fP is called will overwrite this backup .TP .B options \fB\-r \-e\fP Options to pass to sed .TP .B flags \fBg\fP Flags to modify the sed search; e.g., \fBi\fP for case\-insensitve pattern matching .UNINDENT .sp Forward slashes and single quotes will be escaped automatically in the \fBbefore\fP and \fBafter\fP patterns. .sp Usage: .sp .nf .ft C salt \(aq*\(aq file.sed /etc/httpd/httpd.conf \(aqLogLevel warn\(aq \(aqLogLevel info\(aq .ft P .fi .sp New in version 0.9.5. .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_file.touch(name, atime=None, mtime=None) Just like \(aqnix\(aqs "touch" command, create a file if it doesn\(aqt exist or simply update the atime and mtime if it already does. .INDENT 7.0 .TP .B atime: Access time in Unix epoch time .TP .B mtime: Last modification in Unix epoch time .TP .B Usage:: salt \(aq*\(aq file.touch /var/log/emptyfile .UNINDENT .sp New in version 0.9.5. .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_file.uid_to_user(uid) Convert a uid to a user name .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq file.uid_to_user S\-1\-5\-21\-626487655\-2533044672\-482107328\-1010 .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_file.uncomment(path, regex, char=\(aq#\(aq, backup=\(aq.bak\(aq) Uncomment specified commented lines in a file .INDENT 7.0 .TP .B path The full path to the file to be edited .TP .B regex A regular expression used to find the lines that are to be uncommented. This regex should not include the comment character. A leading \fB^\fP character will be stripped for convenience (for easily switching between comment() and uncomment()). .TP .B char \fB#\fP The character to remove in order to uncomment a line; if a single whitespace character follows the comment it will also be removed .TP .B backup \fB.bak\fP The file will be backed up before edit with this file extension; \fBWARNING:\fP each time \fBsed\fP/\fBcomment\fP/\fBuncomment\fP is called will overwrite this backup .UNINDENT .sp Usage: .sp .nf .ft C salt \(aq*\(aq file.uncomment /etc/hosts.deny \(aqALL: PARANOID\(aq .ft P .fi .sp New in version 0.9.5. .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_file.user_to_uid(user) Convert user name to a uid .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq file.user_to_uid myusername .ft P .fi .UNINDENT .SS salt.modules.win_network .sp Module for gathering and managing network information .INDENT 0.0 .TP .B salt.modules.win_network.dig(host) Performs a DNS lookup with dig .sp Note: dig must be installed on the Windows minion .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq network.dig archlinux.org .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_network.hwaddr(interface) Returns the hwaddr for a given interface .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq network.hwaddr \(aqWireless LAN adapter Wireless Network Connection\(aq .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_network.interfaces() Returns a dictionary of interfaces with various information about each (up/down state, ip address, netmask, and hwaddr) .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq network.interfaces .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_network.ipaddr(interface) Returns the IP address for a given interface .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq network.ipaddr \(aqWireless LAN adapter Wireless Network Connection\(aq .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_network.isportopen(host, port) Return status of a port .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq network.isportopen 127.0.0.1 22 .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_network.netmask(interface) Returns the netmask for a given interface .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq network.netmask \(aqWireless LAN adapter Wireless Network Connection\(aq .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_network.netstat() Return information on open ports and states .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq network.netstat .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_network.nslookup(host) Query DNS for information about a domain or ip address .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq network.nslookup archlinux.org .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_network.ping(host) Performs a ping to a host .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq network.ping archlinux.org .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_network.traceroute(host) Performs a traceroute to a 3rd party host .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq network.traceroute archlinux.org .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_network.up(interface) Returns True if interface is up, otherwise returns False .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq network.up \(aqWireless LAN adapter Wireless Network Connection\(aq .ft P .fi .UNINDENT .SS salt.modules.win_service .sp Windows Service module. .INDENT 0.0 .TP .B salt.modules.win_service.disable(name) Disable the named service to start at boot .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq service.disable <service name> .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_service.disabled(name) Check to see if the named service is disabled to start on boot .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq service.disabled <service name> .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_service.enable(name) Enable the named service to start at boot .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq service.enable <service name> .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_service.enabled(name) Check to see if the named service is enabled to start on boot .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq service.enabled <service name> .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_service.get_all() Return all installed services .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq service.get_enabled .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_service.get_disabled() Return the disabled services .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq service.get_disabled .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_service.get_enabled() Return the enabled services .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq service.get_enabled .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_service.getsid(name) Return the sid for this windows service .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_service.restart(name) Restart the named service .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq service.restart <service name> .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_service.start(name) Start the specified service .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq service.start <service name> .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_service.status(name, sig=None) Return the status for a service, returns the PID or an empty string if the service is running or not, pass a signature to use to find the service via ps .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq service.status <service name> [service signature] .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_service.stop(name) Stop the specified service .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq service.stop <service name> .ft P .fi .UNINDENT .SS salt.modules.win_shadow .sp Manage the shadow file .INDENT 0.0 .TP .B salt.modules.win_shadow.info(name) Return information for the specified user This is just returns dummy data so that salt states can work. .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq shadow.info root .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_shadow.set_password(name, password) Set the password for a named user. .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq shadow.set_password root mysecretpassword .ft P .fi .UNINDENT .SS salt.modules.win_useradd .sp Manage Windows users with the net user command .sp NOTE: This currently only works with local user accounts, not domain accounts .INDENT 0.0 .TP .B salt.modules.win_useradd.add(name, uid=None, gid=None, groups=None, home=False, shell=None) Add a user to the minion .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq user.add name password .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_useradd.addgroup(name, group) Add user to a group .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq user.addgroup username groupname .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_useradd.chgroups(name, groups, append=False) Change the groups this user belongs to, add append to append the specified groups .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq user.chgroups foo wheel,root True .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_useradd.chhome(name, home) Change the home directory of the user .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq user.chhome foo \e\efileserver\ehome\efoo .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_useradd.chprofile(name, profile) Change the profile directory of the user .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq user.chprofile foo \e\efileserver\eprofiles\efoo .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_useradd.delete(name) Remove a user from the minion .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq user.delete name .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_useradd.getent() Return the list of all info for all users .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq user.getent .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_useradd.info(name) Return user information .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq user.info root .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_useradd.list_groups(name) Return a list of groups the named user belongs to .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq user.list_groups foo .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_useradd.removegroup(name, group) Remove user from a group .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq user.removegroup username groupname .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.win_useradd.setpassword(name, password) Set a user\(aqs password .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq user.setpassword name password .ft P .fi .UNINDENT .SS salt.modules.yumpkg .sp New in version 0.9.4: This module replaces the "yum" module in previous releases. It is backward compatibile and uses the native yum Python interface instead of the CLI interface. .sp Support for YUM .sp Required python modules: yum, rpm, rpmUtils .INDENT 0.0 .TP .B salt.modules.yumpkg.available_version(name) The available version of the package in the repository .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq pkg.available_version <package name> .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.yumpkg.clean_metadata() Cleans local yum metadata. .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq pkg.clean_metadata .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.yumpkg.install(pkgs, refresh=False, repo=\(aq\(aq, skip_verify=False, **kwargs) Install the passed package(s) .INDENT 7.0 .TP .B pkg The name of the package to be installed .TP .B refresh False Clean out the yum database before executing .TP .B repo (default) Specify a package repository to install from (e.g., \fByum \-\-enablerepo=somerepo\fP) .TP .B skip_verify False Skip the GPG verification check (e.g., \fB\-\-nogpgcheck\fP) .UNINDENT .sp Return a dict containing the new package names and versions: .sp .nf .ft C {\(aq<package>\(aq: {\(aqold\(aq: \(aq<old\-version>\(aq, \(aqnew\(aq: \(aq<new\-version>\(aq]} .ft P .fi .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq pkg.install \(aqpackage package package\(aq .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.yumpkg.list_pkgs(*args) List the packages currently installed in a dict: .sp .nf .ft C {\(aq<package_name>\(aq: \(aq<version>\(aq} .ft P .fi .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq pkg.list_pkgs .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.yumpkg.purge(pkgs) Yum does not have a purge, this function calls remove .sp Return a list containing the removed packages: .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq pkg.purge <package name> .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.yumpkg.refresh_db() Since yum refreshes the database automatically, this runs a yum clean, so that the next yum operation will have a clean database .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq pkg.refresh_db .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.yumpkg.remove(pkgs) Removes packages with yum remove .sp Return a list containing the removed packages: .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq pkg.remove <package,package,package> .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.yumpkg.upgrade() Run a full system upgrade, a yum upgrade .sp Return a dict containing the new package names and versions: .sp .nf .ft C {\(aq<package>\(aq: {\(aqold\(aq: \(aq<old\-version>\(aq, \(aqnew\(aq: \(aq<new\-version>\(aq]} .ft P .fi .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq pkg.upgrade .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.yumpkg.upgrade_available(name) Check whether or not an upgrade is available for a given package .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq pkg.upgrade_available <package name> .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.yumpkg.version(name) Returns a version if the package is installed, else returns an empty string .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq pkg.version <package name> .ft P .fi .UNINDENT .SS salt.modules.yumpkg5 .sp Support for YUM .INDENT 0.0 .TP .B salt.modules.yumpkg5.available_version(name) The available version of the package in the repository .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq pkg.available_version <package name> .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.yumpkg5.install(pkg, refresh=False, repo=\(aq\(aq, skip_verify=False, **kwargs) Install the passed package .INDENT 7.0 .TP .B pkg The name of the package to be installed .TP .B refresh False Clean out the yum database before executing .TP .B repo (default) Specify a package repository to install from (e.g., \fByum \-\-enablerepo=somerepo\fP) .TP .B skip_verify False Skip the GPG verification check (e.g., \fB\-\-nogpgcheck\fP) .UNINDENT .sp Return a dict containing the new package names and versions: .sp .nf .ft C {\(aq<package>\(aq: {\(aqold\(aq: \(aq<old\-version>\(aq, \(aqnew\(aq: \(aq<new\-version>\(aq]} .ft P .fi .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq pkg.install <package name> .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.yumpkg5.list_pkgs() List the packages currently installed in a dict: .sp .nf .ft C {\(aq<package_name>\(aq: \(aq<version>\(aq} .ft P .fi .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq pkg.list_pkgs .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.yumpkg5.purge(pkg) Yum does not have a purge, this function calls remove .sp Return a list containing the removed packages: .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq pkg.purge <package name> .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.yumpkg5.refresh_db() Since yum refreshes the database automatically, this runs a yum clean, so that the next yum operation will have a clean database .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq pkg.refresh_db .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.yumpkg5.remove(pkg) Remove a single package with yum remove .sp Return a list containing the removed packages: .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq pkg.remove <package name> .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.yumpkg5.upgrade() Run a full system upgrade, a yum upgrade .sp Return a dict containing the new package names and versions: .sp .nf .ft C {\(aq<package>\(aq: {\(aqold\(aq: \(aq<old\-version>\(aq, \(aqnew\(aq: \(aq<new\-version>\(aq]} .ft P .fi .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq pkg.upgrade .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.yumpkg5.upgrade_available(name) Check whether or not an upgrade is available for a given package .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq pkg.upgrade_available <package name> .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.yumpkg5.version(name) Returns a version if the package is installed, else returns an empty string .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq pkg.version <package name> .ft P .fi .UNINDENT .SS salt.modules.zypper .sp Package support for openSUSE via the zypper package manager .INDENT 0.0 .TP .B salt.modules.zypper.available_version(name) Return the available version of a given package .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq pkg.available_version <package name> .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.zypper.install(name, refresh=False, **kwargs) Install the passed package, add refresh=True to install with an \-Sy .sp Return a dict containing the new package names and versions: .sp .nf .ft C {\(aq<package>\(aq: {\(aqold\(aq: \(aq<old\-version>\(aq, \(aqnew\(aq: \(aq<new\-version>\(aq]} .ft P .fi .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq pkg.install <package name> .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.zypper.list_pkgs() List the packages currently installed as a dict: .sp .nf .ft C {\(aq<package_name>\(aq: \(aq<version>\(aq} .ft P .fi .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq pkg.list_pkgs .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.zypper.purge(name) Recursively remove a package and all dependencies which were installed with it, this will call a \fBzypper remove \-u\fP .sp Return a list containing the removed packages. .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq pkg.purge <package name> .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.zypper.refresh_db() Just run a \fBzypper refresh\fP, return a dict: .sp .nf .ft C {\(aq<database name>\(aq: Bool} .ft P .fi .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq pkg.refresh_db .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.zypper.remove(name) Remove a single package with \fBzypper remove\fP .sp Return a list containing the removed packages. .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq pkg.remove <package name> .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.zypper.upgrade() Run a full system upgrade, a zypper upgrade .sp Return a dict containing the new package names and versions: .sp .nf .ft C {\(aq<package>\(aq: {\(aqold\(aq: \(aq<old\-version>\(aq, \(aqnew\(aq: \(aq<new\-version>\(aq]} .ft P .fi .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq pkg.upgrade .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.zypper.version(name) Returns a version if the package is installed, else returns an empty string .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq pkg.version <package name> .ft P .fi .UNINDENT .SH RETURNERS .sp By default the return values of the commands sent to the salt minions are returned to the salt\-master. But since the commands executed on the salt minions are detached from the call on the salt master, there is no need for the minion to return the data to the salt master. .sp This is where the returner interface comes in. Returners are modules called in place of returning the data to the salt master. .sp The returner interface allows the return data to be sent to any system that can receive data. This means that return data can be sent to a Redis server, a MongoDB server, a MySQL server, or any system! .IP "See also" .sp \fIFull list of builtin returners\fP .RE .SS Using Returners .sp All commands will return the command data back to the master. Adding more returners will ensure that the data is also sent to the specified returner interfaces. .sp Specifying what returners to use is done when the command is invoked: .sp .nf .ft C salt \(aq*\(aq test.ping \-\-return redis_return .ft P .fi .sp This command will ensure that the redis_return returner is used. .sp It is also possible to specify multiple returners: .sp .nf .ft C salt \(aq*\(aq test.ping \-\-return mongo_return,redis_return,cassandra_return .ft P .fi .sp In this scenario all three returners will be called and the data from the test.ping command will be sent out to the three named returners. .SS Writing a Returner .sp A returner is a module which contains a returner function, the returner function must accept a single argument. this argument is the return data from the called minion function. So if the minion function \fBtest.ping\fP is called the value of the argument will be \fBTrue\fP. .sp A simple returner is implemented here: .sp .nf .ft C import redis import json def returner(ret): \(aq\(aq\(aq Return information to a redis server \(aq\(aq\(aq # Get a redis commection serv = redis.Redis( host=\(aqredis\-serv.example.com\(aq, port=6379, db=\(aq0\(aq) serv.sadd("%(id)s:jobs" % ret, ret[\(aqjid\(aq]) serv.set("%(jid)s:%(id)s" % ret, json.dumps(ret[\(aqreturn\(aq])) serv.sadd(\(aqjobs\(aq, ret[\(aqjid\(aq]) serv.sadd(ret[\(aqjid\(aq], ret[\(aqid\(aq]) .ft P .fi .sp This simple example of a returner set to send the data to a redis server serializes the data as json and sets it in redis. .SS Examples .sp The collection of built\-in salt returners can be found here: \fI\%https://github.com/saltstack/salt/blob/v0.9.8/salt/returners\fP .SH FULL LIST OF BUILTIN RETURNERS .TS center; |l|l|. _ T{ \fBlocal\fP T} T{ The local returner is used to test the returner interface, it just prints the T} _ T{ \fBcassandra_return\fP T} T{ Return data to a Cassandra ColumnFamily T} _ T{ \fBmongo_return\fP T} T{ Return data to a mongodb server T} _ T{ \fBredis_return\fP T} T{ Return data to a redis server T} _ .TE .SS salt.returners.local .sp The local returner is used to test the returner interface, it just prints the return data to the console to verify that it is being passed properly .INDENT 0.0 .TP .B salt.returners.local.returner(ret) Print the return data to the terminal to verify functionality .UNINDENT .SS salt.returners.cassandra_return .sp Return data to a Cassandra ColumnFamily .sp Here\(aqs an example Keyspace / ColumnFamily setup that works with this returner: .sp .nf .ft C create keyspace salt; use salt; create column family returns with key_validation_class=\(aqUTF8Type\(aq and comparator=\(aqUTF8Type\(aq and default_validation_class=\(aqUTF8Type\(aq; .ft P .fi .sp Required python modules: pycassa .INDENT 0.0 .TP .B salt.returners.cassandra_return.returner(ret) Return data to a Cassandra ColumnFamily .UNINDENT .SS salt.returners.mongo_return .sp Return data to a mongodb server .sp This is the default interface for returning data for the butter statd subsytem .sp Required python modules: pymongo .INDENT 0.0 .TP .B salt.returners.mongo_return.returner(ret) Return data to a mongodb server .UNINDENT .SS salt.returners.redis_return .sp Return data to a redis server This is a VERY simple example for pushing data to a redis server and is not necessarily intended as a usable interface. .sp Required python modules: redis .INDENT 0.0 .TP .B salt.returners.redis_return.returner(ret) Return data to a redis data store .UNINDENT .SH FAILHARD GLOBAL OPTION .sp Normally, when a state fails Salt continues to execute the remainder of the defined states and will only refuse to execute states that require the failed state. .sp But the situation may exist, where you would want all state execution to stop if a single state execution fails. The capability to do this is called \fBfailing hard\fP. .SS State Level Failhard .sp A single state can have a failhard set, this means that if this individual state fails that all state execution will immediately stop. This is a great thing to do if there is a state that sets up a critical config file and setting a require for each state that reads the config would be cumbersome. A good example of this would be setting up a package manager early on: .sp .nf .ft C /etc/yum.repos.d/company.repo: file: \- managed \- source: salt://company/yumrepo.conf \- user: root \- group: root \- mode: 644 \- order: 1 \- failhard: True .ft P .fi .sp In this situation, the yum repo is going to be configured before other states, and if it fails to lay down the config file, than no other states will be executed. .SS Global Failhard .sp It may be desired to have failhard be applied to every state that is executed, if this is the case, then failhard can be set in the master configuration file. Setting failhard in the master configuration file will result in failing hard when any minion gathering states from the master have a state fail. .sp This is NOT the default behavior, normally Salt will only fail states that require a failed state. .sp Using the global failhard is generally not recommended, since it can result in states not being executed or even checked. It can also be confusing to see states failhard if an admin is not actively aware that the failhard has been set. .sp To use the global failhard set failhard: True in the master configuration file. .SH HIGHSTATE DATA STRUCTURE DEFINITIONS .SS The Salt State Tree .INDENT 0.0 .TP .B Top file The main state file that instructs minions what environment and modules to use during state execution. .sp Configurable via \fBstate_top\fP. .IP "See also" .sp \fBA detailed description of the top file\fP .RE .UNINDENT .INDENT 0.0 .TP .B State tree A collection of \fBsls\fP files that live under the directory specified in \fBfile_roots\fP. A state tree can be organized into \fIsls modules\fP. .UNINDENT .SS Include declaration .INDENT 0.0 .TP .B Include declaration Defines a list of \fImodule reference\fP strings to include in this \fIsls\fP. .sp Occurs only in the top level of the highstate structure. .UNINDENT .sp Example: .sp .nf .ft C include: \- edit.vim \- http.server .ft P .fi .SS Module reference .INDENT 0.0 .TP .B Module reference The name of a SLS module defined by a separate SLS file and residing on the Salt Master. A module named \fBedit.vim\fP is a reference to the sls file \fBsalt://edit/vim.sls\fP. .UNINDENT .SS ID declaration .INDENT 0.0 .TP .B ID declaration Defines an individual highstate component. Always references a value of a dictionary containing keys referencing \fIstate declarations\fP and \fIrequisite declarations\fP. Can be overridden by a \fIname declaration\fP or a \fInames declaration\fP. .sp Occurs on the top level or under the \fIextend declaration\fP. .UNINDENT .IP Note Naming gotchas .sp Must \fBnot\fP contain a dot, otherwise highstate summary output will be unpredictable. (This has been fixed in versions 0.9.7 and above) .sp Must be unique across entire state tree. If the same ID declaration is used twice, only the first one matched will be used. All subsequent ID declarations with the same name will be ignored. .RE .SS Extend declaration .INDENT 0.0 .TP .B Extend declaration Extends a \fIname declaration\fP from an included \fBsls module\fP. The keys of the extend declaration always define existing \fIID declarations\fP which have been defined in included \fBsls modules\fP. .sp Occurs only in the top level and defines a dictionary. .UNINDENT .sp Extend declarations are useful for adding\-to or overriding parts of a \fIstate declaration\fP that is defined in another \fBsls\fP files. In the following contrived example, the shown \fBmywebsite.sls\fP file is \fBinclude\fP \-ing and \fBextend\fP \-ing the \fBapache.sls\fP module in order to add a \fBwatch\fP declaration that will restart Apache whenever the Apache configuration file, \fBmywebsite\fP changes. .sp .nf .ft C include: \- apache extend: apache: service: \- watch: \- file: mywebsite mywebsite: file: \- managed .ft P .fi .SS State declaration .INDENT 0.0 .TP .B State declaration A list which contains one string defining the \fIfunction declaration\fP and any number of \fIfunction arg declaration\fP dictionaries. .sp Can, optionally, contain a number of additional components like the name override components — \fIname\fP and \fInames\fP. Can also contain \fIrequisite declarations\fP. .sp Occurs under an \fIID declaration\fP. .UNINDENT .SS Requisite declaration .INDENT 0.0 .TP .B Requisite declaration A list containing \fIrequisite references\fP. .sp Used to build the action dependency tree. While Salt states are made to execute in a deterministic order, this order is managed by requiring and watching other Salt states. .sp Occurs as a list component under a \fIstate declaration\fP or as a key under an \fIID declaration\fP. .UNINDENT .SS Requisite reference .INDENT 0.0 .TP .B Requisite reference A single key dictionary. The key is the name of the referenced \fIstate declaration\fP and the value is the ID of the referenced \fIID declaration\fP. .sp Occurs as a single index in a \fIrequisite declaration\fP list. .UNINDENT .SS Function declaration .INDENT 0.0 .TP .B Function declaration The name of the function to call within the state. A state declaration can contain only a single function declaration. .sp For example, the following state declaration calls the \fBinstalled\fP function in the \fBpkg\fP state module: .sp .nf .ft C httpd: pkg: \- installed .ft P .fi .sp Occurs as the only index in the \fIstate declaration\fP list. .UNINDENT .SS Function arg declaration .INDENT 0.0 .TP .B Function arg declaration A single key dictionary referencing a Python type which is to be passed to the named \fIfunction declaration\fP as a parameter. The type must be the data type expected by the function. .sp Occurs under a \fIfunction declaration\fP. .UNINDENT .sp For example in the following state declaration \fBuser\fP, \fBgroup\fP, and \fBmode\fP are passed as arguments to the \fBmanaged\fP function in the \fBfile\fP state module: .sp .nf .ft C /etc/http/conf/http.conf: file: \- managed \- user: root \- group: root \- mode: 644 .ft P .fi .SS Name declaration .INDENT 0.0 .TP .B Name declaration Overrides the \fBname\fP argument of a \fIstate declaration\fP. If \fBname\fP is not specified the \fIID declaration\fP satisfies the \fBname\fP argument. .sp The name is always a single key dictionary referencing a string. .UNINDENT .sp Overriding \fBname\fP is useful for a variety of scenarios. .sp For example, avoiding clashing ID declarations. The following two state declarations cannot both have \fB/etc/motd\fP as the ID declaration: .sp .nf .ft C motd_perms: file: \- managed \- name: /etc/motd \- mode: 644 motd_quote: file: \- append \- name: /etc/motd \- text: "Of all smells, bread; of all tastes, salt." .ft P .fi .sp Another common reason to override \fBname\fP is if the ID declaration is long and needs to be referenced in multiple places. In the example below it is much easier to specify \fBmywebsite\fP than to specify \fB/etc/apache2/sites\-available/mywebsite.com\fP multiple times: .sp .nf .ft C mywebsite: file: \- managed \- name: /etc/apache2/sites\-available/mywebsite.com \- source: salt://mywebsite.com a2ensite mywebsite.com: cmd: \- wait \- unless: test \-L /etc/apache2/sites\-enabled/mywebsite.com \- watch: \- file: mywebsite apache2: service: \- running \- watch: \- file: mywebsite .ft P .fi .SS Names declaration .INDENT 0.0 .TP .B Names declaration Expands the contents of the containing \fIstate declaration\fP into multiple state declarations, each with its own name. .UNINDENT .sp For example, given the following state declaration: .sp .nf .ft C python\-pkgs: pkg: \- installed \- names: \- python\-django \- python\-crypto \- python\-yaml .ft P .fi .sp Once converted into the \fIlowstate\fP data structure the above state declaration will be expanded into the following three state declarations: .sp .nf .ft C python\-django: pkg: \- installed python\-crypto: pkg: \- installed python\-yaml: pkg: \- installed .ft P .fi .SS Large example .sp Here is the layout in yaml using the names of the highdata structure components. .sp .nf .ft C <Include Declaration>: \- <Module Reference> \- <Module Reference> <Extend Declaration>: <ID Declaration>: [<overrides>] <ID Declaration>: <State Declaration>: \- <Function> \- <Function Arg> \- <Function Arg> \- <Function Arg> \- <Name>: <name> \- <Requisite Declaration>: \- <Requisite Reference> \- <Requisite Reference> <ID Declaration>: <State Declaration>: \- <Function> \- <Function Arg> \- <Function Arg> \- <Function Arg> \- <Names>: \- <name> \- <name> \- <name> \- <Requisite Declaration>: \- <Requisite Reference> \- <Requisite Reference> .ft P .fi .SH STATE ENFORCEMENT .sp Salt offers an optional interface to manage the configuration or "state" of the salt minions. This interface is a fully capable mechanism used to enforce the state of systems from a central manager. .sp The Salt state system is made to be accurate, simple, and fast. And like the rest of the Salt system, Salt states are highly modular. .SS State management .sp State management, also frequently called software configuration management (SCM), is a program that puts and keeps a system into a predetermined state. It installs software packages, starts or restarts services, or puts configuration files in place and watches them for changes. .sp Having a state management system in place allows you to easily and reliably configure and manage a few servers or a few thousand servers. It allows you to keep that configuration under version control. .sp Salt States is an extension of the Salt Modules that we discussed in the previous \fBremote execution\fP tutorial. Instead of calling one\-off executions the state of a system can be easily defined and then enforced. .SS Understanding the Salt State System Components .sp The Salt state system is comprised of a number of components. As a user, an understanding of the sls and renderer systems are needed. But as a developer, an understanding of salt states and how to write the states is needed as well. .SS Salt SLS System .INDENT 0.0 .TP .B sls The primary system used by the Salt state system is the SLS system. SLS stands for \fBS\fPa\fBL\fPt \fBS\fPtate. .sp The Salt States are files which contain the information about how to configure salt minions. The states are laid out in a directory tree and can be written in many different formats. .sp The contents of the files and they way they are laid out is intended to be as simple as possible while allowing for maximum flexibility. The files are laid out in states and contains information about how the minion needs to be configured. .UNINDENT .SS SLS File Layout .sp SLS files are laid out in the Salt file server. A simple layout can look like this: .sp .nf .ft C top.sls ssh.sls sshd_config users/init.sls users/admin.sls salt/init.sls salt/master.sls .ft P .fi .sp This example shows the core concepts of file layout. The top file is a key component and is used with salt matchers to match SLS states with minions. The \fB.sls\fP files are states. The rest of the files are seen by the salt master as just files that can be downloaded. .sp The states are translated into dot notation, so the \fBssh.sls\fP file is seen as the ssh state, the \fBusers/admin.sls\fP file is seen as the users.admin states. .sp The init.sls files are translated to be the state name of the parent directory, so the \fBsalt/init.sls\fP file translates to the salt state. .sp The plain files are visible to the minions, as well as the state files. In salt, everything is a file; there is no "magic translation" of files and file types. This means that a state file can be distributed to minions just like a plain text or binary file. .SS SLS Files .sp The Salt state files are simple sets of data. Since the SLS files are just data they can be represented in a number of different ways. The default format is yaml generated from a jinja template. This allows for the states files to have all the language constructs of Python and the simplicity of yaml. State files can then be complicated jinja templates that translate down to yaml, or just plain and simple yaml files! .sp The State files are constructed data structures in a simple format. The format allows for many real activates to be expressed in very little text, while maintaining the utmost in readability and usability. .sp Here is an example of a Salt State: .sp .nf .ft C vim: pkg: \- installed salt: pkg: \- latest service: \- running \- require: \- file: /etc/salt/minion \- pkg: salt \- names: \- salt\-master \- salt\-minion \- watch: \- file: /etc/salt/minion /etc/salt/minion: file: \- managed \- source: salt://salt/minion \- user: root \- group: root \- mode: 644 \- require: \- pkg: salt .ft P .fi .sp This short stanza will ensure that vim is installed, salt is installed and up to date, the salt\-master and salt\-minion daemons are running and the Salt minion configuration file is in place. It will also ensure everything is deployed in the right order and that the Salt services are restarted when the watched file updated. .SS The Top File .sp The top file is the mapping for the state system. The top file specifies which minions should have which modules applied and which environments they should draw the states from. .sp The top file works by specifying the environment, containing matchers with lists of Salt states sent to the matching minions: .sp .nf .ft C base: \(aq*\(aq: \- salt \- users \- users.admin \(aqsaltmaster.*\(aq: \- match: pcre \- salt.master .ft P .fi .sp This simple example uses the base environment, which is built into the default salt setup, and then all minions will have the modules salt, users and users.admin since \(aq*\(aq will match all minions. Then the regular expression matcher will match all minions\(aq with an id matching saltmaster.* and add the salt.master state. .SS Renderer System .sp The Renderer system is a key component to the state system. SLS files are representations of Salt "high data" structures. All Salt cares about when reading an sls file is the data structure that is produced from the file. .sp This allows Salt states to be represented by multiple types of files. The Renderer system can be used to allow different formats to be used for sls files. .sp The available renderers can be found in the renderers directory in the Salt source code: .sp \fI\%https://github.com/saltstack/salt/blob/v0.9.8/salt/renderers\fP .sp By default sls files are rendered using jinja as a templating engine, and yaml as the serialization format. Since the rendering system can be extended simply by adding a new renderer to the renderers directory, it is possible that any structured file could be used to represent the SLS files. .sp In the future xml and raw python will be added, as well as many other formats. .SH ORDERING STATES .sp When creating salt sls files, it is often important to ensure that they run in a specific order. While states will always execute in the same order, that order is not necessarily defined the way you want it. .sp A few tools exist in Salt to set up the correct state ordering. These tools consist of requisite declarations and order options. .IP Note Salt does \fBnot\fP execute \fIstate declarations\fP in the order they appear in the source. .RE .SS Requisite Statements .IP Note This document represents behavior exhibited by Salt requisites as of version 0.9.7 of Salt. .RE .sp Often when setting up states any single action will require or depend on another action. Salt allows you to build relationships between states with requisite statements. A requisite statement ensure that the named state is evaluated before the state requiring it. There are two types of requisite statements in Salt, \fBrequire\fP and \fBwatch\fP. .sp These requisite statements are applied to a specific state declaration: .sp .nf .ft C httpd: pkg: \- installed file: \- managed \- name: /etc/httpd/conf/httpd.conf \- source: salt://httpd/httpd.conf \- require: \- pkg: httpd .ft P .fi .sp In this example we use the \fBrequire\fP requisite to declare that the file /etc/httpd/conf/httpd.conf should only be set up if the pkg state executes successfully. .sp The requisite system works by finding the states that are required and executing them before the state that requires them. Then the required states can be evaluated to see if they have executed correctly. .SS Multiple Requisites .sp The requisite statement is passed as a list, allowing for the easy addition of more requisites. Both requisite types can also be separately declared: .sp .nf .ft C httpd: pkg: \- installed service: \- running \- enable: True \- watch: \- file: /etc/httpd/conf/httpd.conf \- require: \- pkg: httpd \- user: httpd \- group: httpd file: \- managed \- name: /etc/httpd/conf/httpd.conf \- source: salt://httpd/httpd.conf \- require: \- pkg: httpd user: \- present group: \- present .ft P .fi .sp In this example the httpd service is only going to be started if the package, user, group and file are executed successfully. .SS The Require Requisite .sp The foundation of the requisite system is the \fBrequire\fP requisite. The require requisite ensures that the required state(s) are executed before the requiring state. So, if a state is declared that sets down a vimrc, then it would be pertinent to make sure that the vimrc file would only be set down if the vim package has been installed: .sp .nf .ft C vim: pkg: \- installed file: \- managed \- source: salt://vim/vimrc \- require: \- pkg: vim .ft P .fi .sp In this case, the vimrc file will only be applied by Salt if and after the vim package is installed. .SS The Watch Requisite .sp The \fBwatch\fP requisite is more advanced than the \fBrequire\fP requisite. The watch requisite executes the same logic as require (therefore if something is watched it does not need to also be required) with the addition of executing logic if the required states have changed in some way. .sp The watch requisite checks to see if the watched states have returned any changes. If the watched state returns changes, and the watched states execute successfully, then the watching state will execute a function that reacts to the changes in the watched states. .sp Perhaps an example can better explain the behavior: .sp .nf .ft C redis: pkg: \- latest file: \- managed \- source: salt://redis/redis.conf \- name: /etc/redis.conf \- require: \- pkg: redis service: \- running \- enable: True \- watch: \- file: /etc/redis.conf \- pkg: redis .ft P .fi .sp In this example the redis service will only be started if the file /etc/redis.conf is applied, and the file is only applied if the package is installed. This is normal require behavior, but if the watched file changes, or the watched package is installed or upgraded, then the redis service is restarted. .SS Watch and the Watcher Function .sp The watch requisite is based on the \fBwatcher\fP function, state python modules can include a function called watcher, this function is then called if the watch call is invoked. In the case of the service module the underlying service is restarted. In the case of the cmd state the command is executed. .sp The watcher function for the service state looks like this: .sp .nf .ft C def watcher(name, sig=None): \(aq\(aq\(aq The service watcher, called to invoke the watch command. name The name of the init or rc script used to manage the service sig The string to search for when looking for the service process with ps \(aq\(aq\(aq if __salt__[\(aqservice.status\(aq](name, sig): changes = {name: __salt__[\(aqservice.restart\(aq](name)} return {\(aqname\(aq: name, \(aqchanges\(aq: changes, \(aqresult\(aq: True, \(aqcomment\(aq: \(aqService restarted\(aq} return {\(aqname\(aq: name, \(aqchanges\(aq: {}, \(aqresult\(aq: True, \(aqcomment\(aq: \(aqService {0} started\(aq.format(name)} .ft P .fi .sp The watch requisite only works if the state that is watching has a watcher function written. If watch is set on a state that does not have a watcher function (like pkg), then the listed states will behave only as if they were under a \fBrequire\fP statement. .SS The Order Option .sp Before using the order option, remember that the majority of state ordering should be done with a \fIrequisite declaration\fP, and that a requisite declaration will override an order option. .sp The order option is used by adding an order number to a state declaration with the option \fIorder\fP: .sp .nf .ft C vim: pkg: \- installed \- order: 1 .ft P .fi .sp By adding the order option to \fI1\fP this ensures that the vim package will be installed in tandem with any other state declaration set to the order \fI1\fP. .sp Any state declared without an order option will be executed after all states with order options are executed. .sp But this construct can only handle ordering states from the beginning. Sometimes you may want to send a state to the end of the line. To do this, set the order to \fBlast\fP: .sp .nf .ft C vim: pkg: \- installed \- order: last .ft P .fi .SH STATE PROVIDERS .sp New in version 0.9.8. .sp Salt predetermines what modules should be mapped to what uses based on the properties of a system. These determinations are generally made for modules that provide things like package and service management. .sp Sometimes in states it may be needed for an alternative module to be used to provide the functionality needed. For instance, an Arch Linux system may have been set up with systemd support, so instead of using the default service module detected for Arch Linux, the systemd module can be used: .sp .nf .ft C httpd: service: \- running \- enable: True \- provider: systemd .ft P .fi .sp In this instance the systemd module will replace the service virtual module which is used by default on Arch Linux, and the httpd service will be set up using systemd. .SS Arbitrary Module Redirects .sp The provider statement can also be used for more powerful means, instead of overwriting or extending the module used for the named service an arbitrary module can be used to provide certain functionality. .sp .nf .ft C emacs: pkg: \- installed \- provider: \- pkg: yumpkg5 \- cmd: customcmd .ft P .fi .sp In this example the default pkg module is being redirected to use the yumpkg5 module (yum via shelling out instead of via the yum api), but is also using a custom module to invoke commands. This could be used to dramatically change the behavior of a given state. .SH THE TOP FILE .sp The top file is used to map what sls modules get loaded onto what minions via the state system. The top file creates a few general abstractions. First it maps what nodes should pull from which environments, next it defines which matches systems should draw from. .SS Environments .sp The environments in the top file corresponds with the environments defined in the file_roots variable. In a simple, single environment setup you only have the base environment, and therefore only one state tree. Here is a simple example of file_roots in the master configuration: .sp .nf .ft C file_roots: base: \- /srv/salt .ft P .fi .sp This means that the top file will only have one environment to pull from, here is a simple, single environment top file: .sp .nf .ft C base: \(aq*\(aq: \- core \- edit .ft P .fi .sp This also means that /srv/salt has a state tree. But if you want to use multiple environments, or partition the file server to serve more than just the state tree, then the file_roots option can be expanded: .sp .nf .ft C file_roots: base: \- /srv/salt/base dev: \- /srv/salt/dev qa: \- /srv/salt/qa prod: \- /srv/salt/prod .ft P .fi .sp Then our top file could reference the environments: .sp .nf .ft C dev: \(aqwebserver*dev*\(aq: \- webserver \(aqdb*dev*\(aq: \- db qa: \(aqwebserver*qa*\(aq: \- webserver \(aqdb*qa*\(aq: \- db prod: \(aqwebserver*prod*\(aq: \- webserver \(aqdb*prod*\(aq: \- db .ft P .fi .sp In this setup we have state trees in 3 of the 4 environments, and no state tree in the base environment. Notice that the targets for the minions specify environment data. In Salt the master determines who is in what environment, and many environments can be crossed together. For instance, a separate global state tree could be added to the base environment if it suits your deployment: .sp .nf .ft C base: \(aq*\(aq: \- global dev: \(aqwebserver*dev*\(aq: \- webserver \(aqdb*dev*\(aq: \- db qa: \(aqwebserver*qa*\(aq: \- webserver \(aqdb*qa*\(aq: \- db prod: \(aqwebserver*prod*\(aq: \- webserver \(aqdb*prod*\(aq: \- db .ft P .fi .sp In this setup all systems will pull the global sls from the base environment, as well as pull from their respective environments. .sp Remember, that since everything is a file in salt, the environments are primarily file server environments, this means that environments that have nothing to do with states can be defined and used to distribute other files. .sp A clean and recommended setup for multiple environments would look like this: .sp .nf .ft C # Master file_roots configuration: file_roots: base: \- /srv/salt/base dev: \- /srv/salt/dev qa: \- /srv/salt/qa prod: \- /srv/salt/prod .ft P .fi .sp Then only place state trees in the dev, qa and prod environments, leaving the base environment open for generic file transfers. Then the top.sls file would look something like this: .sp .nf .ft C dev: \(aqwebserver*dev*\(aq: \- webserver \(aqdb*dev*\(aq: \- db qa: \(aqwebserver*qa*\(aq: \- webserver \(aqdb*qa*\(aq: \- db prod: \(aqwebserver*prod*\(aq: \- webserver \(aqdb*prod*\(aq: \- db .ft P .fi .SH STATE MODULES .sp State Modules are the components that map to actual enforcement and management of salt states. .SS States are \- Easy to Write! .sp State Modules should be easy to write and straightforward. The information passed to the SLS data structures will map directly to the states modules. .sp Mapping the information from the SLS data is simple, this example should illustrate: .sp .nf .ft C /etc/salt/master: # maps to "name" file: # maps to State module filename eg https://github.com/saltstack/salt/blob/develop/salt/states/file.py \- managed # maps to the managed function in the file State module \- user: root # one of many options passed to the manage function \- group: root \- mode: 644 \- source: salt://salt/master .ft P .fi .sp Therefore this SLS data can be directly linked to a module, function and arguments passed to that function. .sp This does issue the burden, that function names, state names and function arguments should be very human readable inside state modules, since they directly define the user interface. .SS Using Custom State Modules .sp Place your custom state modules inside a \fB_states\fP directory within the \fBfile_roots\fP specified by the master config file. These custom state modules can then be distributed in a number of ways. Custom state modules are distributed when state.highstate is run, or via the saltutil.sync_states function. .SS Cross Calling Modules .sp As with Execution Modules, State Modules can also make use of the \fB__salt__\fP and \fB__grains__\fP data. .sp It is important to note that the real work of state management should not be done in the state module unless it is needed. A good example is the pkg state module. This module does not do any package management work, it just calls the pkg execution module. This makes the pkg state module completely generic, which is why there is only one pkg state module and many backend pkg execution modules. .sp On the other hand some modules will require that the logic be placed in the state module, a good example of this is the file module. But in the vast majority of cases this is not the best approach, and writing specific execution modules to do the backend work will be the optimal solution. .SS Return Data .sp A State Module must return a dict containing the following keys/values: .INDENT 0.0 .IP \(bu 2 \fBname:\fP The same value passed to the state as "name". .IP \(bu 2 \fBchanges:\fP A dict describing the changes made. Each thing changed should be a key, with its value being another dict with keys called "old" and "new" containing the old/new values. For example, the pkg state\(aqs \fBchanges\fP dict has one key for each package changed, with the "old" and "new" keys in its sub\-dict containing the old and new versions of the package. .IP \(bu 2 \fBresult:\fP A boolean value. \fITrue\fP if the action was successful, otherwise \fIFalse\fP. .IP \(bu 2 \fBcomment:\fP A string containing a summary of the result. .UNINDENT .SS Watcher Function .sp If the state being written should support the watch requisite then a watcher function needs to be declared. The watcher function is called whenever the watch requisite is invoked and should be generic to the behavior of the state itself. .sp The watcher function should accept all of the options that the normal state functions accept (as they will be passed into the watcher function). .sp A watcher function typically is used to execute state specific reactive behavior, for instance, the watcher for the service module restarts the named service and makes it useful for the watcher to make the service react to changes in the environment. .sp The watcher function also needs to return the same data that a normal state function returns. .SS Mod_init Interface .sp Some states need to execute something only once to ensure that an environment has been set up, or certain conditions global to the state behavior can be predefined. This is the realm of the mod_init interface. .sp A state module can have a function called \fBmod_init\fP which executes when the first state of this type is called. This interface was created primarily to improve the pkg state. When packages are installed the package metadata needs to be refreshed, but refreshing the package metadata every time a package is installed is wasteful. The mod_init function for the pkg state sets a flag down so that the first, and only the first, package installation attempt will refresh the package database (the package database can of course be manually called to refresh via the \fBrefresh\fP option in the pkg state). .sp The mod_init function must accept the \fBLow State Data\fP for the given executing state as an argument. The low state data is a dict and can be seen by executing the state.show_lowstate function. Then the mod_init function must return a bool. If the return value is True, then the mod_init function will not be executed again, meaning that the needed behavior has been set up. Otherwise, if the mod_init function returns False, then the function will be called the next time. .sp A good example of the mod_init function is found in the pkg state module: .sp .nf .ft C def mod_init(low): \(aq\(aq\(aq Refresh the package database here so that it only needs to happen once \(aq\(aq\(aq if low[\(aqfun\(aq] == \(aqinstalled\(aq or low[\(aqfun\(aq] == \(aqlatest\(aq: rtag = __gen_rtag() if not os.path.exists(rtag): open(rtag, \(aqw+\(aq).write(\(aq\(aq) return True else: return False .ft P .fi .sp The mod_init function in the pkg state accepts the low state data as \fBlow\fP and then checks to see if the function being called is going to install packages, if the function is not going to install packages then there is no need to refresh the package database. Therefore if the package database is prepared to refresh, then return True and the mod_init will not be called the next time a pkg state is evaluated, otherwise return False and the mod_init will be called next time a pkg state is evaluated. .SH FULL LIST OF BUILTIN STATES .TS center; |l|l|. _ T{ \fBcmd\fP T} T{ Command Executions T} _ T{ \fBcron\fP T} T{ Cron Management T} _ T{ \fBfile\fP T} T{ File Management T} _ T{ \fBgem\fP T} T{ Management of rubygems T} _ T{ \fBgroup\fP T} T{ Group Management T} _ T{ \fBhost\fP T} T{ Hosts File Management T} _ T{ \fBkmod\fP T} T{ Kernel Module Management T} _ T{ \fBmount\fP T} T{ Mount Management T} _ T{ \fBmysql_database\fP T} T{ MySQL Database Management T} _ T{ \fBmysql_user\fP T} T{ MySQL User Management T} _ T{ \fBpkg\fP T} T{ Package Management T} _ T{ \fBrvm\fP T} T{ Management of ruby installations and gemsets with RVM T} _ T{ \fBservice\fP T} T{ Service Management T} _ T{ \fBssh_auth\fP T} T{ SSH Authorized Key Management T} _ T{ \fBsysctl\fP T} T{ Kernel Sysctl Management T} _ T{ \fBuser\fP T} T{ User Management T} _ T{ \fBvirtualenv\fP T} T{ virtualenv management T} _ .TE .SS salt.states.cmd .SS Command Executions .sp The cmd state module manages the enforcement of executed commands, this state can tell a command to run under certain circumstances. .SS Available Functions .sp The cmd state only has a single function, the \fBrun\fP function .INDENT 0.0 .TP .B run Execute a command given certain conditions .sp A simple example: .sp .nf .ft C date > /tmp/salt\-run: cmd: \- run .ft P .fi .UNINDENT .sp Only run if another execution returns successfully, in this case truncate syslog if there is no disk space: .sp .nf .ft C > /var/log/messages: cmd: \- run \- unless: echo \(aqfoo\(aq > /tmp/.test .ft P .fi .IP Warning Please be advised that on Unix systems the shell being used by python to run executions is /bin/sh, this requires that commands are formatted to execute under /bin/sh. Some capabilities of newer shells such as bash, zsh and ksh will not always be available on minions. .RE .INDENT 0.0 .TP .B salt.states.cmd.mod_watch(name, onlyif=None, unless=None, cwd=\(aq/root\(aq, user=None, group=None, shell=\(aq/bin/sh\(aq, env=()) Run a command if certain circumstances are met .INDENT 7.0 .TP .B name The command to execute, remember that the command will execute with the path and permissions of the salt\-minion. .TP .B onlyif A command to run as a check, run the named command only if the command passed to the \fBonlyif\fP option returns true .TP .B unless A command to run as a check, only run the named command if the command passed to the \fBunless\fP option returns false .TP .B cwd The current working directory to execute the command in, defaults to /root .TP .B user The user name to run the command as .TP .B group The group context to run the command as .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.cmd.run(name, onlyif=None, unless=None, cwd=\(aq/root\(aq, user=None, group=None, shell=\(aq/bin/sh\(aq, env=()) Run a command if certain circumstances are met .INDENT 7.0 .TP .B name The command to execute, remember that the command will execute with the path and permissions of the salt\-minion. .TP .B onlyif A command to run as a check, run the named command only if the command passed to the \fBonlyif\fP option returns true .TP .B unless A command to run as a check, only run the named command if the command passed to the \fBunless\fP option returns false .TP .B cwd The current working directory to execute the command in, defaults to /root .TP .B user The user name to run the command as .TP .B group The group context to run the command as .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.cmd.wait(name, onlyif=None, unless=None, cwd=\(aq/root\(aq, user=None, group=None) Run the given command only if the watch statement calls it .INDENT 7.0 .TP .B name The command to execute, remember that the command will execute with the path and permissions of the salt\-minion. .TP .B onlyif A command to run as a check, run the named command only if the command passed to the \fBonlyif\fP option returns true .TP .B unless A command to run as a check, only run the named command if the command passed to the \fBunless\fP option returns false .TP .B cwd The current working directory to execute the command in, defaults to /root .TP .B user The user name to run the command as .TP .B group The group context to run the command as .UNINDENT .UNINDENT .SS salt.states.cron .SS Cron Management .sp The cron state module allows for user crontabs to be cleanly managed. .sp Cron declarations require a number of parameters. The timing parameters, need to be declared, minute, hour, daymonth, month and dayweek. The user who\(aqs crontab is to be edited also needs to be defined. .sp By default the timing arguments are all \fB*\fP and the user is root. When making changes to an existing cron job the name declaration is the unique factor, so if and existing cron that looks like this: .sp .nf .ft C date > /tmp/crontest: cron: \- present \- user: root \- minute: 5 .ft P .fi .sp Is changed to this: .sp .nf .ft C date > /tmp/crontest: cron: \- present \- user: root \- minute: 7 \- hour: 2 .ft P .fi .sp Then the existing cron will be updated, but if the cron command is changed, then a new cron job will be added to the user\(aqs crontab. .INDENT 0.0 .TP .B salt.states.cron.absent(name, user=\(aqroot\(aq, minute=\(aq*\(aq, hour=\(aq*\(aq, daymonth=\(aq*\(aq, month=\(aq*\(aq, dayweek=\(aq*\(aq) Verifies that the specified cron job is absent for the specified user, only the name is matched when removing a cron job. .INDENT 7.0 .TP .B name The command that should be absent in the user crontab. .TP .B user The name of the user who\(aqs crontab needs to be modified, defaults to the root user .TP .B minute The information to be set into the minute section, this can be any string supported by your cron system\(aqs the minute field. Default is \fB*\fP .TP .B hour The information to be set in the hour section. Default is \fB*\fP .TP .B daymonth The information to be set in the day of month section. Default is \fB*\fP .TP .B month The information to be set in the month section. Default is \fB*\fP .TP .B dayweek The information to be set in the day of day of week section. Default is \fB*\fP .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.cron.present(name, user=\(aqroot\(aq, minute=\(aq*\(aq, hour=\(aq*\(aq, daymonth=\(aq*\(aq, month=\(aq*\(aq, dayweek=\(aq*\(aq) Verifies that the specified cron job is present for the specified user. For more advanced information about what exactly can be set in the cron timing parameters check your cron system\(aqs documentation. Most Unix\-like systems\(aq cron documentation can be found via the crontab man page: \fBman 5 crontab\fP. .INDENT 7.0 .TP .B name The command that should be executed by the cron job. .TP .B user The name of the user who\(aqs crontab needs to be modified, defaults to the root user .TP .B minute The information to be set into the minute section, this can be any string supported by your cron system\(aqs the minute field. Default is \fB*\fP .TP .B hour The information to be set in the hour section. Default is \fB*\fP .TP .B daymonth The information to be set in the day of month section. Default is \fB*\fP .TP .B month The information to be set in the month section. Default is \fB*\fP .TP .B dayweek The information to be set in the day of day of week section. Default is \fB*\fP .UNINDENT .UNINDENT .SS salt.states.file .SS File Management .sp Salt States can aggressively manipulate files on a system. There are a number of ways in which files can be managed. .sp Regular files can be enforced with the \fBmanaged\fP function. This function downloads files from the salt master and places them on the target system. The downloaded files can be rendered as a jinja or mako template adding a dynamic component to file management. An example of \fBfile.managed\fP which makes use of the jinja templating system would look like this: .sp .nf .ft C /etc/http/conf/http.conf: file: \- managed \- source: salt://apache/http.conf \- user: root \- group: root \- mode: 644 \- template: jinja \- context: custom_var: "override" \- defaults: custom_var: "default value" other_var: 123 .ft P .fi .sp Directories can be managed via the \fBdirectory\fP function. This function can create and enforce the permissions on a directory. A directory statement will look like this: .sp .nf .ft C /srv/stuff/substuf: file: \- directory \- user: fred \- group: users \- mode: 755 \- makedirs: True .ft P .fi .sp If you need to enforce user and/or group ownership recursively on the directory\(aqs contents, you can do so by adding a \fBrecurse\fP directive: .sp .nf .ft C /srv/stuff/substuf: file: \- directory \- user: fred \- group: users \- mode: 755 \- makedirs: True \- recurse: \- user \- group .ft P .fi .sp Symlinks can be easily created, the symlink function is very simple and only takes a few arguments: .sp .nf .ft C /etc/grub.conf: file: \- symlink \- target: /boot/grub/grub.conf .ft P .fi .sp Recursive directory management can also be set via the \fBrecurse\fP function. Recursive directory management allows for a directory on the salt master to be recursively copied down to the minion. This is a great tool for deploying large code and configuration systems. A recuse state would look something like this: .sp .nf .ft C /opt/code/flask: file: \- recurse \- source: salt://code/flask .ft P .fi .INDENT 0.0 .TP .B salt.states.file.absent(name) Verify that the named file or directory is absent, this will work to reverse any of the functions in the file state module. .INDENT 7.0 .TP .B name The path which should be deleted .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.file.append(name, text) Ensure that some text appears at the end of a file .sp The text will not be appended again if it already exists in the file. You may specify a single line of text or a list of lines to append. .sp Multi\-line example: .sp .nf .ft C /etc/motd: file: \- append \- text: | Thou hadst better eat salt with the Philosophers of Greece, than sugar with the Courtiers of Italy. \- Benjamin Franklin .ft P .fi .sp Multiple lines of text: .sp .nf .ft C /etc/motd: file: \- append \- text: \- Trust no one unless you have eaten much salt with him. \- Salt is born of the purest of parents: the sun and the sea. .ft P .fi .sp New in version 0.9.5. .UNINDENT .INDENT 0.0 .TP .B salt.states.file.comment(name, regex, char=\(aq#\(aq, backup=\(aq.bak\(aq) Usage: .sp .nf .ft C /etc/fstab: file: \- comment \- regex: ^//10.10.20.5 .ft P .fi .sp New in version 0.9.5. .UNINDENT .INDENT 0.0 .TP .B salt.states.file.directory(name, user=None, group=None, recurse=[], mode=None, makedirs=False, clean=False, require=None) Ensure that a named directory is present and has the right perms .INDENT 7.0 .TP .B name The location to create or manage a directory .TP .B user The user to own the directory, this defaults to the user salt is running as on the minion .TP .B group The group ownership set for the directory, this defaults to the group salt is running as on the minion .TP .B recurse Enforce user/group ownership of directory recursively .TP .B mode The permissions to set on this directory, aka 755 .TP .B makedirs If the directory is located in a path without a parent directory, then the state will fail. If makedirs is set to True, then the parent directories will be created to facilitate the creation of the named file. .TP .B clean Make sure that only files that are set up by salt and required by this function are kept. If this option is set then everything in this directory will be deleted unless it is required. .TP .B require Require other resources such as packages or files .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.file.managed(name, source=None, source_hash=\(aq\(aq, user=None, group=None, mode=None, template=None, makedirs=False, context=None, defaults=None, __env__=\(aqbase\(aq) Manage a given file, this function allows for a file to be downloaded from the salt master and potentially run through a templating system. .INDENT 7.0 .TP .B name The location of the file to manage .TP .B source The source file to download to the minion, this source file can be hosted on either the salt master server, or on an http or ftp server. For files hosted on the salt file server, if the file is located on the master in the directory named spam, and is called eggs, the source string is salt://spam/eggs. If source is left blank or None, the file will be created as an empty file and the content will not be managed .sp If the file is hosted on a http or ftp server then the source_hash argument is also required .TP .B source_hash: This can be either a file which contains a source hash string for the source, or a source hash string. The source hash string is the hash algorithm followed by the hash of the file: md5=e138491e9d5b97023cea823fe17bac22 .TP .B user The user to own the file, this defaults to the user salt is running as on the minion .TP .B group The group ownership set for the file, this defaults to the group salt is running as on the minion .TP .B mode The permissions to set on this file, aka 644, 0775, 4664 .TP .B template If this setting is applied then the named templating engine will be used to render the downloaded file, currently jinja and mako are supported .TP .B makedirs If the file is located in a path without a parent directory, then the state will fail. If makedirs is set to True, then the parent directories will be created to facilitate the creation of the named file. .TP .B context Overrides default context variables passed to the template. .TP .B defaults Default context passed to the template. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.file.recurse(name, source, clean=False, require=None, user=None, group=None, dir_mode=None, file_mode=None, __env__=\(aqbase\(aq) Recurse through a subdirectory on the master and copy said subdirecory over to the specified path. .INDENT 7.0 .TP .B name The directory to set the recursion in .TP .B source The source directory, this directory is located on the salt master file server and is specified with the salt:// protocol. If the directory is located on the master in the directory named spam, and is called eggs, the source string is salt://spam/eggs .TP .B clean Make sure that only files that are set up by salt and required by this function are kept. If this option is set then everything in this directory will be deleted unless it is required. .TP .B require Require other resources such as packages or files .TP .B user The user to own the directory, this defaults to the user salt is running as on the minion .TP .B group The group ownership set for the directory, this defaults to the group salt is running as on the minion .TP .B dir_mode The permissions mode to set any directories created .TP .B file_mode The permissions mode to set any files created .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.file.sed(name, before, after, limit=\(aq\(aq, backup=\(aq.bak\(aq, options=\(aq\-r \-e\(aq, flags=\(aqg\(aq) Maintain a simple edit to a file .sp The file will be searched for the \fBbefore\fP pattern before making the edit and then searched for the \fBafter\fP pattern to verify the edit was successful using \fBsalt.modules.file.contains\fP. In general the \fBlimit\fP pattern should be as specific as possible and \fBbefore\fP and \fBafter\fP should contain the minimal text to be changed. .sp Usage: .sp .nf .ft C # Disable the epel repo by default /etc/yum.repos.d/epel.repo: file: \- sed \- before: 1 \- after: 0 \- limit: ^enabled= # Remove ldap from nsswitch /etc/nsswitch.conf: file: \- sed \- before: \(aqldap\(aq \- after: \(aq\(aq \- limit: \(aq^passwd:\(aq .ft P .fi .sp New in version 0.9.5. .UNINDENT .INDENT 0.0 .TP .B salt.states.file.symlink(name, target, force=False, makedirs=False) Create a symlink .INDENT 7.0 .TP .B name The location of the symlink to create .TP .B target The location that the symlink points to .TP .B force If the location of the symlink exists and is not a symlink then the state will fail, set force to True and any file or directory in the way of the symlink file will be deleted to make room for the symlink .TP .B makedirs If the location of the symlink does not already have a parent directory then the state will fail, setting makedirs to True will allow Salt to create the parent directory .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.file.touch(name, atime=None, mtime=None, makedirs=False) Replicate the \(aqnix "touch" command to create a new empty file or update the atime and mtime of an existing file. .sp Usage: .sp .nf .ft C /var/log/httpd/logrotate.empty file: \- touch .ft P .fi .sp New in version 0.9.5. .UNINDENT .INDENT 0.0 .TP .B salt.states.file.uncomment(name, regex, char=\(aq#\(aq, backup=\(aq.bak\(aq) Usage: .sp .nf .ft C /etc/adduser.conf: file: \- uncomment \- regex: EXTRA_GROUPS .ft P .fi .sp New in version 0.9.5. .UNINDENT .SS salt.states.gem .SS Management of rubygems .sp A state module to manage rubygems. Gems can be set up to be installed or removed. This module will use RVM if it is installed. In that case you can specify what ruby version and gemset to target. .sp .nf .ft C addressable: gem: \- installed \- runas: rvm \- ruby: jruby@jgemset .ft P .fi .INDENT 0.0 .TP .B salt.states.gem.installed(name, ruby=None, runas=None) Make sure that a gem is installed. .INDENT 7.0 .TP .B name The name of the gem to install .TP .B ruby None For RVM installations: the ruby version and gemset to target. .TP .B runas None The user to run gem as. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.gem.removed(name, ruby=None, runas=None) Make sure that a gem is not installed. .INDENT 7.0 .TP .B name The name of the gem to uninstall .TP .B ruby None For RVM installations: the ruby version and gemset to target. .TP .B runas None The user to run gem as. .UNINDENT .UNINDENT .SS salt.states.group .SS Group Management .sp The group module is used to create and manage unix group settings, groups can be either present or absent: .sp .nf .ft C cheese: group: \- present \- gid: 7648 .ft P .fi .INDENT 0.0 .TP .B salt.states.group.absent(name) Ensure that the named group is absent .INDENT 7.0 .TP .B name The name of the group to remove .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.group.present(name, gid=None) Ensure that a group is present .INDENT 7.0 .TP .B name The name of the group to manage .TP .B gid The group id to assign to the named group, if left empty then the next available group id will be assigned .UNINDENT .UNINDENT .SS salt.states.host .SS Hosts File Management .sp The hosts file can be managed to contain definitions for specific hosts: .sp .nf .ft C salt\-master: host: \- present \- ip: 192.168.0.42 .ft P .fi .INDENT 0.0 .TP .B salt.states.host.absent(name, ip) Ensure that the named host is absent .INDENT 7.0 .TP .B name The host to remove .TP .B ip The ip addr of the host to remove .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.host.present(name, ip) Ensures that the named host is present with the given ip .INDENT 7.0 .TP .B name The host to assign an ip to .TP .B ip The ip addr to apply to the host .UNINDENT .UNINDENT .SS salt.states.kmod .SS Kernel Module Management .sp The Kernel modules on a system can be managed cleanly with the kmod state module: .sp .nf .ft C kvm_amd: kmod: \- present pcspkr: kmod: \- absent .ft P .fi .INDENT 0.0 .TP .B salt.states.kmod.absent(name) Verify that the named kernel module is not loaded .INDENT 7.0 .TP .B name The name of the kernel module to verify is not loaded .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.kmod.present(name) Ensure that the specified kernel module is loaded .INDENT 7.0 .TP .B name The name of the kernel module to verify is loaded .UNINDENT .UNINDENT .SS salt.states.mount .SS Mount Management .sp Mount any type of mountable filesystem with the mounted function: .sp .nf .ft C /mnt/sdb: mount: \- mounted \- device: /dev/sdb1 \- fstype: ext4 \- mkmnt: True \- opts: \- defaults .ft P .fi .INDENT 0.0 .TP .B salt.states.mount.mounted(name, device, fstype, mkmnt=False, opts=[\(aqdefaults\(aq], dump=0, pass_num=0, config=\(aq/etc/fstab\(aq, remount=True, persist=True) Verify that a device is mounted .INDENT 7.0 .TP .B name The path to the location where the device is to be mounted .TP .B device The device name, typically the device node, such as /dev/sdb1 .TP .B fstype The filesystem type, this will be xfs, ext2/3/4 in the case of classic filesystems, and fuse in the case of fuse mounts .TP .B mkmnt If the mount point is not present then the state will fail, set mkmnt to True to create the mount point if it is otherwise not present .TP .B opts A list object of options or a comma delimited list .TP .B dump The dump value to be passed into the fstab, default to 0 .TP .B pass_num The pass value to be passed into the fstab, default to 0 .TP .B config Set an alternative location for the fstab, default to /etc/fstab .TP .B remount Set if the file system can be remounted with the remount option, default to True .TP .B persist Set if the mount should be saved in the fstab, default to True .UNINDENT .UNINDENT .SS salt.states.mysql_database .SS MySQL Database Management .sp The mysql_database module is used to create and manage MySQL databases, databases can be set as either absent or present .sp .nf .ft C frank: mysql_database: \- present .ft P .fi .INDENT 0.0 .TP .B salt.states.mysql_database.absent(name) Ensure that the named database is absent .INDENT 7.0 .TP .B name The name of the database to remove .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.mysql_database.present(name) Ensure that the named database is present with the specified properties .INDENT 7.0 .TP .B name The name of the database to manage .UNINDENT .UNINDENT .SS salt.states.mysql_user .SS MySQL User Management .sp The mysql_database module is used to create and manage MySQL databases, databases can be set as either absent or present .sp .nf .ft C frank: mysql_user: \- present \- host: localhost \- password: bobcat .ft P .fi .INDENT 0.0 .TP .B salt.states.mysql_user.absent(name, host=\(aqlocalhost\(aq) Ensure that the named user is absent .INDENT 7.0 .TP .B name The name of the user to remove .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.mysql_user.present(name, host=\(aqlocalhost\(aq, password=None, password_hash=None) Ensure that the named user is present with the specified properties .INDENT 7.0 .TP .B name The name of the user to manage .TP .B password The password .TP .B password_hash The password in hashed form .UNINDENT .UNINDENT .SS salt.states.pkg .SS Package Management .sp Salt can manage software packages via the pkg state module, packages can be set up to be installed, latest, removed and purged. Package management declarations are typically rather simple: .sp .nf .ft C vim: pkg: \- installed .ft P .fi .INDENT 0.0 .TP .B salt.states.pkg.installed(name, version=None, refresh=False, repo=\(aq\(aq, skip_verify=False, **kwargs) Verify that the package is installed, and only that it is installed. This state will not upgrade an existing package and only verify that it is installed .INDENT 7.0 .TP .B name The name of the package to install .TP .B repo Specify a non\-default repository to install from .TP .B skip_verify False Skip the GPG verification check for the package to be installed .UNINDENT .sp Usage: .sp .nf .ft C httpd: pkg: \- installed \- repo: mycustomrepo \- skip_verify: True .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.states.pkg.latest(name, refresh=False, repo=\(aq\(aq, skip_verify=False, **kwargs) Verify that the named package is installed and the latest available package. If the package can be updated this state function will update the package. Generally it is better for the installed function to be used, as \fBlatest\fP will update the package the package whenever a new package is available .INDENT 7.0 .TP .B name The name of the package to maintain at the latest available version .TP .B repo (default) Specify a non\-default repository to install from .TP .B skip_verify False Skip the GPG verification check for the package to be installed .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.pkg.mod_init(low) Refresh the package database here so that it only needs to happen once .UNINDENT .INDENT 0.0 .TP .B salt.states.pkg.purged(name) Verify that the package is purged, this will call the purge function in the salt pkg module for the platform. .INDENT 7.0 .TP .B name The name of the package to be purged .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.pkg.removed(name) Verify that the package is removed, this will remove the package via the remove function in the salt pkg module for the platform. .INDENT 7.0 .TP .B name The name of the package to be removed .UNINDENT .UNINDENT .SS salt.states.rvm .SS Management of ruby installations and gemsets with RVM .sp This module is used to install and manage ruby installations and gemsets with RVM, the Ruby Version Manager. Different versions of ruby can be installed and gemsets created. RVM itself will be installed automatically if it\(aqs not present. This module will not automatically install packages that RVM depends on or ones that are needed to build ruby. If you want to run RVM as an unprivileged user (recommended) you will have to create this user yourself. This is how a state configuration could look like: .sp .nf .ft C rvm: group: \- present user: \- present \- gid: rvm \- home: /home/rvm \- require: \- group: rvm rvm\-deps: pkg: \- installed \- names: \- bash \- coreutils \- gzip \- bzip2 \- gawk \- sed \- curl \- git\-core \- subversion \- sudo mri\-deps: pkg: \- installed \- names: \- build\-essential \- openssl \- libreadline6 \- libreadline6\-dev \- curl \- git\-core \- zlib1g \- zlib1g\-dev \- libssl\-dev \- libyaml\-dev \- libsqlite3\-0 \- libsqlite3\-dev \- sqlite3 \- libxml2\-dev \- libxslt1\-dev \- autoconf \- libc6\-dev \- libncurses5\-dev \- automake \- libtool \- bison \- subversion \- ruby jruby\-deps: pkg: \- installed \- names: \- curl \- g++ \- openjdk\-6\-jre\-headless ruby\-1.9.2: rvm: \- installed \- default: True \- runas: rvm \- require: \- pkg: rvm\-deps \- pkg: mri\-deps \- user: rvm jruby: rvm: \- installed \- runas: rvm \- require: \- pkg: rvm\-deps \- pkg: jruby\-deps \- user: rvm jgemset: rvm: \- gemset_present \- ruby: jruby \- runas: rvm \- require: \- rvm: jruby mygemset: rvm: \- gemset_present \- ruby: ruby\-1.9.2 \- runas: rvm \- require: \- rvm: ruby\-1.9.2 .ft P .fi .INDENT 0.0 .TP .B salt.states.rvm.gemset_present(name, ruby=\(aqdefault\(aq, runas=None) Verify that the gemset is present. .INDENT 7.0 .TP .B name The name of the gemset. .TP .B ruby default The ruby version this gemset belongs to. .TP .B runas None The use user to run rvm as. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.rvm.installed(name, default=False, runas=None) Verify that the specified ruby is installed with RVM. RVM is installed when necessary. .INDENT 7.0 .TP .B name The version of ruby to install .TP .B default False Whether to make this ruby the default. .TP .B runas None The user to run rvm as. .UNINDENT .UNINDENT .SS salt.states.service .SS Service Management .sp Services are defined as system daemons typically started with system init or rc scripts, services can be defined as running or dead. .sp .nf .ft C httpd: service: \- running .ft P .fi .INDENT 0.0 .TP .B salt.states.service.dead(name, enable=None, sig=None) Ensure that the named service is dead .INDENT 7.0 .TP .B name The name of the init or rc script used to manage the service .TP .B enable Set the service to be enabled at boot time, True sets the service to be enabled, False sets the named service to be disabled. The default is None, which does not enable or disable anything. .TP .B sig The string to search for when looking for the service process with ps .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.service.disabled(name) Verify that the service is disabled on boot, only use this state if you don\(aqt want to manage the running process, remember that if you want to disable a service to use the enable: False option for the running or dead function. .INDENT 7.0 .TP .B name The name of the init or rc script used to manage the service .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.service.enabled(name) Verify that the service is enabled on boot, only use this state if you don\(aqt want to manage the running process, remember that if you want to enable a running service to use the enable: True option for the running or dead function. .INDENT 7.0 .TP .B name The name of the init or rc script used to manage the service .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.service.mod_watch(name, sig=None) The service watcher, called to invoke the watch command. .INDENT 7.0 .TP .B name The name of the init or rc script used to manage the service .TP .B sig The string to search for when looking for the service process with ps .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.service.running(name, enable=None, sig=None) Verify that the service is running .INDENT 7.0 .TP .B name The name of the init or rc script used to manage the service .TP .B enable Set the service to be enabled at boot time, True sets the service to be enabled, False sets the named service to be disabled. The default is None, which does not enable or disable anything. .TP .B sig The string to search for when looking for the service process with ps .UNINDENT .UNINDENT .SS salt.states.ssh_auth .SS SSH Authorized Key Management .sp The information stored in a user\(aqs ssh authorized key file can be easily controlled via the ssh_auth state: .sp .nf .ft C AAAAB3NzaC1kc3MAAACBAL0sQ9fJ5bYTEyY==: ssh_auth: \- present \- user: root \- enc: ssh\-dss thatch: ssh_auth: \- present \- user: root \- source: salt://ssh_keys/thatch.id_rsa.pub .ft P .fi .INDENT 0.0 .TP .B salt.states.ssh_auth.absent(name, user, config=\(aq.ssh/authorized_keys\(aq) Verifies that the specified ssh key is absent .INDENT 7.0 .TP .B name The ssh key to manage .TP .B user The user who owns the ssh authorized keys file to modify .TP .B config The location of the authorized keys file relative to the user\(aqs home directory, defaults to ".ssh/authorized_keys" .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.ssh_auth.present(name, user, enc=\(aqssh\-rsa\(aq, comment=\(aq\(aq, source=\(aq\(aq, options=[], config=\(aq.ssh/authorized_keys\(aq) Verifies that the specified ssh key is present for the specified user .INDENT 7.0 .TP .B name The ssh key to manage .TP .B user The user who owns the ssh authorized keys file to modify .TP .B enc Defines what type of key is being used, can be ssh\-rsa or ssh\-dss .TP .B comment The comment to be placed with the ssh public key .TP .B source The source file for the key(s). Can contain any number of public keys, in standard "authorized_keys" format. If this is set, comment, enc, and options will be ignored. .TP .B options The options passed to the key, pass a list object .TP .B config The location of the authorized keys file relative to the user\(aqs home directory, defaults to ".ssh/authorized_keys" .UNINDENT .UNINDENT .SS salt.states.sysctl .SS Kernel Sysctl Management .sp Control the kernel sysctl system .sp .nf .ft C vm.swappines: sysctl: \- present \- value: 20 .ft P .fi .INDENT 0.0 .TP .B salt.states.sysctl.present(name, value, config=\(aq/etc/sysctl.conf\(aq) Ensure that the named sysctl value is set .INDENT 7.0 .TP .B name The name of the sysctl value to edit .TP .B value The sysctl value to apply .TP .B config The location of the sysctl configuration file .UNINDENT .UNINDENT .SS salt.states.user .SS User Management .sp The user module is used to create and manage user settings, users can be set as either absent or present .sp .nf .ft C fred: user: \- present \- fullname: Fred Jones \- shell: /bin/zsh \- home: /home/fred \- uid: 4000 \- gid: 4000 \- groups: \- wheel \- storage \- games .ft P .fi .INDENT 0.0 .TP .B salt.states.user.absent(name, purge=False, force=False) Ensure that the named user is absent .INDENT 7.0 .TP .B name The name of the user to remove .TP .B purge Set purge to delete all of the user\(aqs file as well as the user .TP .B force If the user is logged in the absent state will fail, set the force option to True to remove the user even if they are logged in .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.states.user.present(name, uid=None, gid=None, groups=None, home=False, password=None, enforce_password=True, shell=None, fullname=None, roomnumber=None, workphone=None, homephone=None, other=None) Ensure that the named user is present with the specified properties .INDENT 7.0 .TP .B name The name of the user to manage .TP .B uid The user id to assign, if left empty then the next available user id will be assigned .TP .B gid The default group id .TP .B groups A list of groups to assign the user to, pass a list object .TP .B home The location of the home directory to manage .TP .B password A password hash to set for the user .TP .B enforce_password Set to False to keep the password from being changed if it has already been set and the password hash differs from what is specified in the "password" field. This option will be ignored if "password" is not specified. .TP .B shell The login shell, defaults to the system default shell .UNINDENT .sp User comment field (GECOS) support (currently Linux\-only): .sp The below values should be specified as strings to avoid ambiguities when the values are loaded. (Especially the phone and room number fields which are likely to contain numeric data) .INDENT 7.0 .TP .B fullname The user\(aqs full name. .TP .B roomnumber The user\(aqs room number .TP .B workphone The user\(aqs work phone number .TP .B homephone The user\(aqs home phone number .TP .B other The user\(aqs "other" GECOS field .UNINDENT .UNINDENT .SS salt.states.virtualenv .sp virtualenv management .INDENT 0.0 .TP .B salt.states.virtualenv.manage(name, venv_bin=\(aqvirtualenv\(aq, requirements=\(aq\(aq, no_site_packages=False, system_site_packages=False, distribute=False, clear=False, python=\(aq\(aq, extra_search_dir=\(aq\(aq, never_download=False, prompt=\(aq\(aq, __env__=\(aqbase\(aq, runas=None) Create a virtualenv and optionally manage it with pip .INDENT 7.0 .TP .B name Path to the virtualenv .TP .B requirements Path to a pip requirements file. If the path begins with \fBsalt://\fP the file will be transfered from the master file server. .UNINDENT .sp Also accepts any kwargs that the virtualenv module will. .UNINDENT .SH RENDERERS .sp The Salt state system operates by gathering information from simple data structures. The state system was designed in this way to make interacting with it generic and simple. This also means that state files (sls files) can be one of many formats. .sp By default sls files are rendered as jinja templates and then parsed as yaml documents. But since the only thing the state system cares about is raw data, the sls files can be any structured format that can be dreamed up. .sp Currently there is support for \fBjinja + yaml\fP, \fBmako + yaml\fP, \fBjinja + json\fP and \fBmako + json\fP. But renderers can be written to support anything. This means that the Salt states could be managed by xml files, html files, puppet files, or any format that can be translated into the data structure used by the state system. .SS Multiple Renderers .sp When deploying a state tree a default renderer is selected in the master configuration file with the renderer option. But multiple renderers can be used inside the same state tree. .sp When rendering sls files Salt checks for the presence of a salt specific shebang line. The shebang line syntax was chosen because it is familiar to the target audience, the systems admin and systems engineer. .sp The shebang line directly calls the name of the renderer as it is specified within Salt. One of the most common reasons to use multiple renderers in to use the python or \fBpy\fP renderer: .sp .nf .ft C #!py def run(): \(aq\(aq\(aq Install the python\-mako package \(aq\(aq\(aq return {\(aqinclude\(aq: [\(aqpython\(aq], \(aqpython\-mako\(aq: {\(aqpkg\(aq: [\(aqinstalled\(aq]}} .ft P .fi .sp The first line is a shebang that references the \fBpy\fP renderer. .SS Writing Renderers .sp Writing a renderer is easy, all that is required is that a python module is placed in the rendered directory and that the module implements the render function. The render function will be passed the path of the sls file. In the render function, parse the passed file and return the data structure derived from the file. .SS Examples .sp The best place to find examples of renderers is in the Salt source code. The renderers included with Salt can be found here: .sp \fI\%https://github.com/saltstack/salt/blob/v0.9.8/salt/renderers\fP .sp Here is a simple jinja + yaml example: .sp .nf .ft C # Import python libs import os # Import Third Party libs import yaml from jinja2 import Template def render(template): \(aq\(aq\(aq Render the data passing the functions and grains into the rendering system \(aq\(aq\(aq if not os.path.isfile(template): return {} passthrough = {} passthrough.update(__salt__) passthrough.update(__grains__) template = Template(open(template, \(aqr\(aq).read()) yaml_data = template.render(**passthrough) return yaml.load(yaml_data) .ft P .fi .SH FULL LIST OF BUILTIN RENDERERS .TS center; |l|l|. _ T{ \fBsalt.renderers.json_jinja\fP T} T{ Process json with the jinja2 templating engine T} _ T{ \fBsalt.renderers.json_mako\fP T} T{ Process json with the Mako templating engine T} _ T{ \fBsalt.renderers.yaml_jinja\fP T} T{ The default rendering engine, process yaml with the jinja2 templating engine T} _ T{ \fBsalt.renderers.yaml_mako\fP T} T{ Process yaml with the Mako templating engine T} _ T{ \fBsalt.renderers.py\fP T} T{ Pure python state renderer T} _ .TE .SS salt.renderers.json_jinja .sp Process json with the jinja2 templating engine .sp This renderer will take a json file with the jinja template and render it to a high data format for salt states. .INDENT 0.0 .TP .B salt.renderers.json_jinja.render(template_file, env=\(aq\(aq, sls=\(aq\(aq) Render the data passing the functions and grains into the rendering system .UNINDENT .SS salt.renderers.json_mako .sp Process json with the Mako templating engine .sp This renderer will take a json file with the Mako template and render it to a high data format for salt states. .INDENT 0.0 .TP .B salt.renderers.json_mako.render(template) Render the data passing the functions and grains into the rendering system .UNINDENT .SS salt.renderers.yaml_jinja .sp The default rendering engine, process yaml with the jinja2 templating engine .sp This renderer will take a yaml file with the jinja2 template and render it to a high data format for salt states. .INDENT 0.0 .TP .B salt.renderers.yaml_jinja.render(template_file, env=\(aq\(aq, sls=\(aq\(aq) Render the data passing the functions and grains into the rendering system .UNINDENT .SS salt.renderers.yaml_mako .sp Process yaml with the Mako templating engine .sp This renderer will take a yaml file within a mako template and render it to a high data format for salt states. .INDENT 0.0 .TP .B salt.renderers.yaml_mako.render(template, env=\(aq\(aq, sls=\(aq\(aq) Render the data passing the functions and grains into the rendering system .UNINDENT .SS salt.renderers.py .sp Pure python state renderer .sp The sls file should contain a function called \fBsls\fP which returns high state data .INDENT 0.0 .TP .B salt.renderers.py.render(template, env=\(aq\(aq, sls=\(aq\(aq) Render the python module\(aqs components .UNINDENT .SH SALT RUNNERS .sp Salt runners are convenience applications executed with the salt\-run command. .sp A Salt runner can be a simple client call, or a complex application. .sp The use for a salt running is to build a frontend hook for running sets of commands via salt or creating special formatted output. .SS Writing Salt Runners .sp Salt runners can be easily written, the work in a similar way to Salt modules except they run on the server side. .sp A runner is a python module that contains functions, each public function is a runner that can be executed via the salt\-run command. .sp If a python module named test.py is created in the runners directory and contains a function called \fBfoo\fP then the function could be called with: .sp .nf .ft C # salt \(aq*\(aq test.foo .ft P .fi .SS Examples .sp The best examples of runners can be found in the Salt source: .sp \fI\%https://github.com/saltstack/salt/blob/v0.9.8/salt/runners\fP .sp A simple runner that returns a well\-formatted list of the minions that are responding to salt calls would look like this: .sp .nf .ft C # Import salt modules import salt.client def up(): \(aq\(aq\(aq Print a list of all of the minions that are up \(aq\(aq\(aq client = salt.client.LocalClient(__opts__[\(aqconfig\(aq]) minions = client.cmd(\(aq*\(aq, \(aqtest.ping\(aq, timeout=1) for minion in sorted(minions): print minion .ft P .fi .SH PEER COMMUNICATION .sp Salt 0.9.0 introduced the capability for salt minions to publish commands. The intent of this feature is not for salt minions to act as independent brokers one with another, but to allow salt minions to pass commands to each other. .sp The peer interface allows a minion to call out publications on the salt master and receive the return data. .sp Since this presents a viable security risk by allowing minions access to the master publisher the capability is turned off by default. The minions can be allowed access to the master publisher on a per minion basis based on regular expressions. Minions with specific ids can be allowed access to certain salt modules and functions. .SS Configuration .sp The configuration is done under the peer setting in the salt master configuration file, here are a number of configuration possibilities. .sp The simplest approach is to enable all communication for all minions, this is only recommended for very secure environments. .sp .nf .ft C peer: .*: \- .* .ft P .fi .sp This configuration will allow minions with ids ending in example.com access to the test, ps, and pkg module functions. .sp .nf .ft C peer: .*example.com: \- test.* \- ps.* \- pkg.* .ft P .fi .sp The configuration logic is simple, a regular expression is passed for matching minion ids, and then a list of expressions matching minion functions is associated with the named minion. For instance, this configuration will also allow minions ending with foo.org access to the publisher. .sp .nf .ft C peer: .*example.com: \- test.* \- ps.* \- pkg.* .*foo.org: \- test.* \- ps.* \- pkg.* .ft P .fi .SH SALT SYNDIC .sp The Salt Syndic interface is a powerful tool which allows for the construction of Salt command topologies. A basic Salt setup has a Salt Master commanding a group of Salt Minions. The Syndic interface is a special passthrough minion, it is run on a master and connects to another master, then the master that the Syndic minion is listening to can control the minions attached to the master running the syndic. .sp The intent for supporting many layouts is not presented with the intent of supposing the use of any single topology, but to allow a more flexible method of controlling many systems. .SS Configuring the Syndic .sp Since the Syndic only needs to be attached to a higher level master the configuration is very simple. On a master that is running a syndic to connect to a higher level master the syndic_master option needs to be set in the master config file. The syndic_master option contains the hostname or ip address of the master server that can control the master that the syndic is running on. .sp The master that the syndic connects to sees the syndic as an ordinary minion, and treats it as such. the higher level master will need to accept the syndic\(aqs minion key like any other minion. This master will also need to set the order_masters value in the configuration to True. The order_masters option in the config on the higher level master is very important, to control a syndic extra information needs to be sent with the publications, the order_masters option makes sure that the extra data is sent out. .SS Running the Syndic .sp The Syndic is a separate daemon that needs to be started on the master that is controlled by a higher master. Starting the Syndic daemon is the same as starting the other Salt daemons. .sp .nf .ft C # salt\-syndic .ft P .fi .SH PYTHON CLIENT API .sp Salt is written to be completely API centric, Salt minions and master can be built directly into third party applications as a communication layer. The Salt client API is very straightforward. .SS Using the LocalClient API .sp Sending information through the client is simple: .sp .nf .ft C # Import the salt client library import salt.client # create a local client object client = salt.client.LocalClient() # make calls with the cmd method ret = client.cmd(\(aq*\(aq, \(aqcmd.run\(aq, [\(aqls \-l\(aq]) .ft P .fi .sp The cmd call is the only one needed for the local client, the arguments are as follows: .INDENT 0.0 .TP .B LocalClient.cmd(tgt, fun, arg=[], timeout=5, expr_form=\(aqglob\(aq) .UNINDENT .sp The LocalClient object only works running as root on the salt\-master, it is the same interface used by the salt command line tool. The arguments are as follows. .INDENT 0.0 .TP .B tgt The tgt option is the target specification, by default a target is passed in as a bash shell glob. The expr_form option allows the tgt to be passed as either a pcre regular expression or as a python list. .UNINDENT .INDENT 0.0 .TP .B fun The name of the function to call on the specified minions. The documentation for these functions can be seen by running on the salt\-master: salt \(aq*\(aq sys.doc .UNINDENT .INDENT 0.0 .TP .B arg The optional arg parameter is used to pass a list of options on to the remote function .UNINDENT .INDENT 0.0 .TP .B timeout The number of seconds to wait after the last minion returns but before all minions return. .UNINDENT .INDENT 0.0 .TP .B expr_form The type of tgt that is passed in, the allowed values are: .INDENT 7.0 .IP \(bu 2 \(aqglob\(aq \- Bash glob completion \- Default .IP \(bu 2 \(aqpcre\(aq \- Perl style regular expression .IP \(bu 2 \(aqlist\(aq \- Python list of hosts .UNINDENT .UNINDENT .SS Compound Command Execution With the Salt API .sp The Salt client API can also send what is called a compound command. Often a collection of commands need to be executed on the targeted minions, rather than send the commands one after another, they can be send in a single publish containing a series of commands. This can dramatically lower overhead and speed up the application communicating with Salt. .sp When commands are executed with compound execution the minion functions called are executed in serial on the minion and the return value is sent back in a different fashion. The return value is a dict, with the function names as keys to the function returns as values. .sp Using the compound command execution system via the API requires that the fun value and the arg value are lists matching by index. This ensures that the order of the executions can be controlled. Any function that has no arguments MUST have an empty array in the corresponding arg index. .sp .nf .ft C # Import the salt client library import salt.client # create a local client object client = salt.client.LocalClient() # make compound execution calls with the cmd method ret = client.cmd(\(aq*\(aq, [\(aqcmd.run\(aq, \(aqtest.ping\(aq, \(aqtest.echo\(aq], [[\(aqls \-l\(aq], [], [\(aqfoo\(aq]]) .ft P .fi .sp This will execute \fBcmd.run ls \-l\fP then \fBtest.ping\fP and finally \fBtest.echo foo\fP. The return data from the minion will look like this: .sp .nf .ft C {\(aqcmd.run\(aq: \(aq<output from ls \-l>\(aq, \(aqtest.ping\(aq: True, \(aqtest.echo\(aq: \(aqfoo\(aq} .ft P .fi .SH SALT FILE SERVER .sp Salt comes with a simple file server suitable for distributing files to the salt minions. The file server is a stateless ZeroMQ server that is built into the salt master. .sp The main intent of the Salt File server is to present files for use in the Salt state system. With this said, the Salt file server can be used for any general file transfer from the master to the minions. .SS The cp Module .sp The cp module is the home of minion side file server operations. The cp module is used by the Salt state system, salt\-cp and can be used to distribute files presented by the Salt file server. .SS Environments .sp Since the file server is made to work with the Salt state system, it supports environments. The environments are defined in the master config file and when referencing an environment the file specified will be based on the root directory of the environment. .SS get_file .sp The cp.get_file function can be used on the minion to download a file from the master, the syntax looks like this: .sp .nf .ft C # salt \(aq*\(aq cp.get_file salt://vimrc /etc/vimrc .ft P .fi .sp This will instruct all salt minions to download the vimrc file and copy it to /etc/vimrc .SS File Server Client API .sp A client API is available which allows for modules and applications to be written which make use of the Salt file server. .sp The file server uses the same authentication and encryption used by the rest of the Salt system for network communication. .SS FileClient Class .sp The FileClient class is used to set up the communication from the minion to the master. When creating a FileClient object the minion configuration needs to be passed in. When using the FileClient from within a minion module the built in \fB__opts__\fP data can be passed: .sp .nf .ft C import salt.minion def get_file(path, dest, env=\(aqbase\(aq): \(aq\(aq\(aq Used to get a single file from the salt master CLI Example: salt \(aq*\(aq cp.get_file salt://vimrc /etc/vimrc \(aq\(aq\(aq # Create the FileClient object client = salt.minion.FileClient(__opts__) # Call get_file return client.get_file(path, dest, False, env) .ft P .fi .sp Using the FileClient class outside of a minion module where the \fB__opts__\fP data is not available, it needs to be generated: .sp .nf .ft C import salt.minion import salt.config def get_file(path, dest, env=\(aqbase\(aq): \(aq\(aq\(aq Used to get a single file from the salt master \(aq\(aq\(aq # Get the configuration data opts = salt.config.minion_config(\(aq/etc/salt/minion\(aq) # Create the FileClient object client = salt.minion.FileClient(opts) # Call get_file return client.get_file(path, dest, False, env) .ft P .fi .SH FILE SERVER CONFIGURATION .sp The Salt file server is a high performance file server written in ZeroMQ. It manages large files quickly and with little overhead, and has been optimized to handle small files in an extremely efficient manner. .sp The Salt file server is an environment aware file server. This means that files can be allocated within many root directories and accessed by specifying both the file path and the environment to search. The individual environments can span across multiple directory roots to crate overlays and to allow for files to be organized in many flexible ways. .SS Environments .sp The Salt file server defaults to the mandatory \fBbase\fP environment. This environment \fBMUST\fP be defined and is used to download files when no environment is specified. .sp Environments allow for files and sls data to be logically separated, but environments are not isolated from each other. This allows for logical isolation of environments by the engineer using Salt, but also allows for information to be used in multiple environments. .SS Directory Overlay .sp The \fBenvironment\fP setting is a list of directories to publish files from. These directories are searched in order to find the specified file and the first file found is returned. .sp This means that directory data is prioritized based on the order in which they are listed. In the case of this \fBfile_roots\fP configuration: .sp .nf .ft C file_roots: base: \- /srv/salt/base \- /srv/salt/failover .ft P .fi .sp If a file\(aqs uri is \fBsalt://httpd/httpd.conf\fP, it will first search for the file at \fB/srv/salt/base/httpd/httpd.conf\fP. If the file is found there it will be returned. If the file is not found there, then \fB/srv/salt/failover/httpd/httpd.conf\fP will be used for the source. .sp This allows for directories to be overlaid and prioritized based on the order they are defined in the configuration. .SS Local File Server .sp New in version 0.9.8. .sp The file server can be rerouted to run from the minion. This is primarily to enable running salt states without a salt master. To use the local file server interface, copy the file server data to the minion and set the file_roots option on the minion to point to the directories copied from the master. Once the minion \fBfile_roots\fP option has been set, change the \fBfile_client\fP option to local to make sure that the local file server interface is used. .SH DYNAMIC MODULE DISTRIBUTION .sp New in version 0.9.5. .sp Salt python modules can be distributed automatically via the salt file server. Under the root of any environment defined via the file_roots option on the master server directories corresponding to the type of module can be used. .sp The directories are prepended with an underscore: .INDENT 0.0 .INDENT 3.5 .INDENT 0.0 .IP 1. 3 _modules .IP 2. 3 _grains .IP 3. 3 _renderers .IP 4. 3 _returners .IP 5. 3 _states .UNINDENT .UNINDENT .UNINDENT .sp The contents of these directories need to be synced over to the minions after python modules have been created in them. There are a number of ways to sync the modules. .SS Sync Via States .sp The minion configuration contains an option \fBautoload_dynamic_modules\fP which defaults to True. This option makes the state system refresh all dynamic modules when states are run. To disable this behavior set \fBautoload_dynamic_modules\fP to False in the minion config. .SS Sync Via the saltutil Module .sp The saltutil module has a number of functions that can be used to sync all or specific dynamic modules. The saltutil module function \fBsaltutil.sync_all\fP will sync all module types over to a minion. For more information see: \fBsalt.modules.saltutil\fP .SH CONFIGURATION FILE EXAMPLES .INDENT 0.0 .IP \(bu 2 \fI\%Example master configuration file\fP .IP \(bu 2 \fI\%Example minion configuration file\fP .UNINDENT .SS Example master configuration file .sp .nf .ft C # DO NOT MODIFY THIS FILE. Copy it to: /etc/salt/master ##### Primary configuration settings ##### ########################################## # The address of the interface to bind to #interface: 0.0.0.0 # The port used by the publisher #publish_port: 4505 # The user to run salt #user: root # The number of worker threads to start, these threads are used to manage # return calls made from minions to the master, if the master seems to be # running slowly, increase the number of threads #worker_threads: 5 # The port used by the communication interface #ret_port: 4506 # The root directory prepended to these options: pki_dir, cachedir, # sock_dir, log_file. #root_dir: / # Directory used to store public key data #pki_dir: /etc/salt/pki # Directory to store job and cache data #cachedir: /var/cache/salt # Set the number of hours to keep old job information #keep_jobs: 24 # Set the default timeout for the salt command and api, the default is 5 # seconds #timeout: 5 # Set the directory used to hold unix sockets #sock_dir: /tmp/salt\-unix # Set the acceptance level for serialization of messages. This should only be # set if the master is newer than 0.9.5 and the minion are older. This option # allows a 0.9.5 and newer master to communicate with minions 0.9.4 and # earlier. It is not recommended to keep this setting on if the minions are # all 0.9.5 or higher, as leaving pickle as the serialization medium is slow # and opens up security risks # #serial: msgpack ##### Security settings ##### ########################################## # Enable "open mode", this mode still maintains encryption, but turns off # authentication, this is only intended for highly secure environments or for # the situation where your keys end up in a bad state. If you run in open mode # you do so at your own risk! #open_mode: False # Enable auto_accept, this setting will automatically accept all incoming # public keys from the minions. Note that this is insecure. #auto_accept: False ##### State System settings ##### ########################################## # The state system uses a "top" file to tell the minions what environment to # use and what modules to use. The state_top file is defined relative to the # root of the base environment. #state_top: top.sls # # The external_nodes option allows Salt to gather data that would normally be # placed in a top file. The external_nodes option is the executable that will # return the ENC data. Remember that Salt will look for external nodes AND top # files and combine the results if both are enabled! #external_nodes: None # # The renderer to use on the minions to render the state data #renderer: yaml_jinja # # The failhard option tells the minions to stop immediately after the first # failure detected in the state execution, defaults to False #failhard: False ##### File Server settings ##### ########################################## # Salt runs a lightweight file server written in zeromq to deliver files to # minions. This file server is built into the master daemon and does not # require a dedicated port. # The file server works on environments passed to the master, each environment # can have multiple root directories, the subdirectories in the multiple file # roots cannot match, otherwise the downloaded files will not be able to be # reliably ensured. A base environment is required to house the top file. # Example: # file_roots: # base: # \- /srv/salt/ # dev: # \- /srv/salt/dev/services # \- /srv/salt/dev/states # prod: # \- /srv/salt/prod/services # \- /srv/salt/prod/states # # Default: #file_roots: # base: # \- /srv/salt # The hash_type is the hash to use when discovering the hash of a file on # the master server, the default is md5, but sha1, sha224, sha256, sha384 # and sha512 are also supported. #hash_type: md5 # The buffer size in the file server can be adjusted here: #file_buffer_size: 1048576 # Pillar Configurations: # The Salt Pillar, is a system that allows for the building of global data # that is refined based on minion. Basically, the pillar creates data that # can be generated to be specific based on the grains of the minion. Pillar # is laid out in the same fashion as the file server, with environments, a top # file and sls files. The difference is that the data does not need to be # in the highstate format, and is generally just key/value pairs. # #pillar_roots: # base: # \- /srv/pillar # ##### Syndic settings ##### ########################################## # The Salt syndic is used to pass commands through a master from a higher # master. Using the syndic is simple, if this is a master that will have # syndic servers(s) below it set the "order_masters" setting to True, if this # is a master that will be running a syndic daemon for passthrough the # "syndic_master" setting needs to be set to the location of the master server # to recieve commands from. # # Set the order_masters setting to True if this master will command lower # masters\(aq syndic interfaces. #order_masters: False # # If this master will be running a salt syndic daemon, syndic_master tells # this master where to receive commands from. #syndic_master: masterofmaster ##### Peer Publish settings ##### ########################################## # Salt minions can send commands to other minions, but only if the minion is # allowed to. By default "Peer Publication" is disabled, and when enabled it # is enabled for specific minions and specific commands. This allows secure # compartmentalization of commands based on individual minions. # # The configuration uses regular expressions to match minions and then a list # of regular expressions to match functions. The following will allow the # minion authenticated as foo.example.com to execute functions from the test # and pkg modules. # peer: # foo.example.com: # \- test.* # \- pkg.* # # This will allow all minions to execute all commands: # peer: # .*: # \- .* # This is not recomanded, since it would allow anyone who gets root on any # single minion to instantly have root on all of the minions! # ##### Cluster settings ##### ########################################## # Salt supports automatic clustering, salt creates a single ip address which # is shared among the individual salt components using ucarp. The private key # and all of the minion keys are maintained across the defined cluster masters. # The failover service is automatically managed via these settings # List the identifiers for the other cluster masters in this manner: # [saltmaster\-01.foo.com,saltmaster\-02.foo.com,saltmaster\-03.foo.com] # The members of this master array must be running as salt minions to # facilitate the distribution of cluster information #cluster_masters: [] # The cluster modes are "paranoid" and "full" # paranoid will only distribute the accepted minion public keys. # full will also distribute the master private key. #cluster_mode: paranoid ##### Logging settings ##### ########################################## # The location of the master log file #log_file: /var/log/salt/master # # The level of messages to send to the log file. # One of \(aqinfo\(aq, \(aqquiet\(aq, \(aqcritical\(aq, \(aqerror\(aq, \(aqdebug\(aq, \(aqwarning\(aq. # Default: \(aqwarning\(aq #log_level: warning # # Logger levels can be used to tweak specific loggers logging levels. # For example, if you want to have the salt library at the \(aqwarning\(aq level, # but you still wish to have \(aqsalt.modules\(aq at the \(aqdebug\(aq level: # log_granular_levels: # \(aqsalt\(aq: \(aqwarning\(aq, # \(aqsalt.modules\(aq: \(aqdebug\(aq # #log_granular_levels: {} ##### Node Groups ##### ########################################## # Node groups allow for logical groupings of minion nodes. # A group consists of a group name and a compound target. # # nodegroups: # group1: \(aqL@foo.domain.com,bar.domain.com,baz.domain.com and bl*.domain.com\(aq, # group2: \(aqG@os:Debian and foo.domain.com\(aq, ##### Range Cluster settings ##### ########################################## # The range server (and optional port) that # serves your cluster information #range_server: range:80 .ft P .fi .SS Example minion configuration file .sp .nf .ft C # DO NOT MODIFY THIS FILE. Copy it to: /etc/salt/minion ##### Primary configuration settings ##### ########################################## # Set the location of the salt master server, if the master server cannot be # resolved, then the minion will fail to start. #master: salt # Set the port used by the master reply and authentication server #master_port: 4506 # The user to run salt #user: root # The root directory prepended to these options: pki_dir, cachedir, log_file. #root_dir: / # The directory to store the pki information in #pki_dir: /etc/salt/pki # Explicitly declare the id for this minion to use, if left commented the id # will be the hostname as returned by the python call: socket.getfqdn() # Since salt uses detached ids it is possible to run multiple minions on the # same machine but with different ids, this can be useful for salt compute # clusters. #id: # Append a domain to a hostname in the event that it does not exist. This is # usefule for systems where socket.getfqdn() does not actually result in a # FQDN (for instance, Solaris). #append_domain: # If the the connection to the server is interrupted, the minion will # attempt to reconnect. sub_timeout allows you to control the rate # of reconnection attempts (in seconds). To disable reconnects, set # this value to 0. #sub_timeout: 60 # Where cache data goes #cachedir: /var/cache/salt # The minion can locally cache the return data from jobs sent to it, this # can be a good way to keep track of jobs the minion has executed # (on the minion side). By default this feature is disabled, to enable # set cache_jobs to True #cache_jobs: False # When waiting for a master to accept the minion\(aqs public key, salt will # continuously attempt to reconnect until successful. This is the time, in # seconds, between those reconnection attempts. #acceptance_wait_time = 10 # When healing a dns_check is run, this is to make sure that the originally # resolved dns has not changed, if this is something that does not happen in # your environment then set this value to False. #dns_check: True ##### Minion module management ##### ########################################## # Disable specific modules. This allows the admin to limit the level of # access the master has to the minion #disable_modules: [cmd,test] #disable_returners: [] # # Modules can be loaded from arbitrary paths. This enables the easy deployment # of third party modules. Modules for returners and minions can be loaded. # Specify a list of extra directories to search for minion modules and # returners. These paths must be fully qualified! #module_dirs: [] #returner_dirs: [] #states_dirs: [] #render_dirs: [] # # A module provider can be statically overwritten or extended for the minion # via the providers option, in this case the default module will be # overwritten by the specified module. In this example the pkg module will # be provided by the yumpkg5 module instead of the system default. # # providers: # pkg: yumpkg5 # # Enable Cython modules searching and loading. (Default: False) #cython_enable: False ##### State Management Settings ##### ########################################### # The state management system executes all of the state templates on the minion # to enable more granular control of system state management. The type of # template and serialization used for state management needs to be configured # on the minion, the default renderer is yaml_jinja. This is a yaml file # rendered from a jinja template, the available options are: # yaml_jinja # yaml_mako # json_jinja # json_mako # #renderer: yaml_jinja # # state_verbose allows for the data returned from the minion to be more # verbose. Normaly only states that fail or states that have changes are # returned, but setting state_verbose to True will return all states that # were checked #state_verbose: False # # autoload_dynamic_modules Turns on automatic loading of modules found in the # environments on the master. This is turned on by default, to turn of # autoloading modules when states run set this value to False #autoload_dynamic_modules: True # # clean_dynamic_modules keeps the dynamic modules on the minion in sync with # the dynamic modules on the master, this means that if a dynamic module is # not on the master it will be deleted from the minion. By default this is # enabled and can be disabled by changing this value to False #clean_dynamic_modules: True # # Normally the minion is not isolated to any single environment on the master # when running states, but the environment can be isolated on the minion side # by statically setting it. Remember that the recommended way to manage # environments is to issolate via the top file. #environment: None # # If using the local file directory, then the state top file name needs to be # defined, by default this is top.sls. #state_top: top.sls ##### File Directory Settings ##### ########################################## # The Salt Minion can redirect all file server operations to a local directory, # this allows for the same state tree that is on the master to be used if # coppied completely onto the minion. This is a literal copy of the settings on # the master but used to reference a local directory on the minion. # Set the file client, the client defaults to looking on the master server for # files, but can be directed to look at the local file directory setting # defined below by setting it to local. #file_client: remote # The file directory works on environments passed to the minion, each environment # can have multiple root directories, the subdirectories in the multiple file # roots cannot match, otherwise the downloaded files will not be able to be # reliably ensured. A base environment is required to house the top file. # Example: # file_roots: # base: # \- /srv/salt/ # dev: # \- /srv/salt/dev/services # \- /srv/salt/dev/states # prod: # \- /srv/salt/prod/services # \- /srv/salt/prod/states # # Default: #file_roots: # base: # \- /srv/salt # The hash_type is the hash to use when discovering the hash of a file in # the minion directory, the default is md5, but sha1, sha224, sha256, sha384 # and sha512 are also supported. #hash_type: md5 # The Salt pillar is searched for locally if file_client is set to local. If # this is the case, and pillar data is defined, then the pillar_roots need to # also be configured on the minion: #pillar_roots: # base: # \- /srv/pillar ###### Security settings ##### ########################################### # Enable "open mode", this mode still maintains encryption, but turns off # authentication, this is only intended for highly secure environments or for # the situation where your keys end up in a bad state. If you run in open mode # you do so at your own risk! #open_mode: False ###### Thread settings ##### ########################################### # Disable multiprocessing support, by default when a minion receives a # publication a new process is spawned and the command is executed therein. #multiprocessing: True ###### Logging settings ##### ########################################### # The location of the minion log file #log_file: /var/log/salt/minion # # The level of messages to send to the log file. # One of \(aqinfo\(aq, \(aqquiet\(aq, \(aqcritical\(aq, \(aqerror\(aq, \(aqdebug\(aq, \(aqwarning\(aq. # Default: \(aqwarning\(aq #log_level: warning # # Logger levels can be used to tweak specific loggers logging levels. # For example, if you want to have the salt library at the \(aqwarning\(aq level, # but you still wish to have \(aqsalt.modules\(aq at the \(aqdebug\(aq level: # log_granular_levels: { # \(aqsalt\(aq: \(aqwarning\(aq, # \(aqsalt.modules\(aq: \(aqdebug\(aq # } # #log_granular_levels: {} ###### Module configuration ##### ########################################### # Salt allows for modules to be passed arbitrary configuration data, any data # passed here in valid yaml format will be passed on to the salt minion modules # for use. It is STRONGLY recommended that a naming convention be used in which # the module name is followed by a . and then the value. Also, all top level # data must be applied via the yaml dict construct, some examples: # # A simple value for the test module: #test.foo: foo # # A list for the test module: #test.bar: [baz,quo] # # A dict for the test module: #test.baz: {spam: sausage, cheese: bread} .ft P .fi .SH CONFIGURING THE SALT MASTER .sp The Salt system is amazingly simple and easy to configure, the two components of the Salt system each have a respective configuration file. The \fBsalt\-master\fP is configured via the master configuration file, and the \fBsalt\-minion\fP is configured via the minion configuration file. .IP "See also" .sp \fIexample master configuration file\fP .RE .sp The configuration file for the salt\-master is located at \fB/etc/salt/master\fP. The available options are as follows: .SS Primary Master Configuration .SS \fBinterface\fP .sp Default: \fB0.0.0.0\fP (all interfaces) .sp The local interface to bind to. .sp .nf .ft C interface: 192.168.0.1 .ft P .fi .SS \fBpublish_port\fP .sp Default: \fB4505\fP .sp The network port to set up the publication interface .sp .nf .ft C publish_port: 4505 .ft P .fi .SS \fBuser\fP .sp Default: \fBroot\fP .sp The user to run the Salt processes .sp .nf .ft C user: root .ft P .fi .SS \fBworker_threads\fP .sp Default: \fB5\fP .sp The number of threads to start for receiving commands and replies from minions. If minions are stalling on replies because you have many minions, raise the worker_threads value. .sp .nf .ft C worker_threads: 5 .ft P .fi .SS \fBret_port\fP .sp Default: \fB4506\fP .sp The port used by the return server, this is the server used by Salt to receive execution returns and command executions. .sp .nf .ft C ret_port: 4506 .ft P .fi .SS \fBroot_dir\fP .sp Default: \fB/\fP .sp The system root directory to operate from, change this to make Salt run from an alternative root .sp .nf .ft C root_dir: / .ft P .fi .SS \fBpki_dir\fP .sp Default: \fB/etc/salt/pki\fP .sp The directory to store the pki authentication keys. .sp .nf .ft C pki_dir: /etc/salt/pki .ft P .fi .SS \fBcachedir\fP .sp Default: \fB/var/cache/salt\fP .sp The location used to store cache information, particularly the job information for executed salt commands. .sp .nf .ft C cachedir: /var/cache/salt .ft P .fi .SS \fBkeep_jobs\fP .sp Default: \fB24\fP .sp Set the number of hours to keep old job information .SS \fBsock_dir\fP .sp Default:: \fB/tmp/salt\-unix\fP .sp Set the location to use for creating Unix sockets for master process communication .SS Master Security Settings .SS \fBopen_mode\fP .sp Default: \fBFalse\fP .sp Open mode is a dangerous security feature. One problem encountered with pki authentication systems is that keys can become "mixed up" and authentication begins to fail. Open mode turns off authentication and tells the master to accept all authentication. This will clean up the pki keys received from the minions. Open mode should not be turned on for general use. Open mode should only be used for a short period of time to clean up pki keys. To turn on open mode set this value to \fBTrue\fP. .sp .nf .ft C open_mode: False .ft P .fi .SS \fBauto_accept\fP .sp Default: \fBFalse\fP .sp Enable auto_accept. This setting will automatically accept all incoming public keys from the minions .sp .nf .ft C auto_accept: False .ft P .fi .SS Master State System Settings .SS \fBstate_top\fP .sp Default: \fBtop.sls\fP .sp The state system uses a "top" file to tell the minions what environment to use and what modules to use. The state_top file is defined relative to the root of the base environment .sp .nf .ft C state_top: top.sls .ft P .fi .SS \fBexternal_nodes\fP .sp Default: None .sp The external_nodes option allows Salt to gather data that would normally be placed in a top file from and external node controller. The external_nodes option is the executable that will return the ENC data. Remember that Salt will look for external nodes AND top files and combine the results if both are enabled and available! .sp .nf .ft C external_nodes: cobbler\-ext\-nodes .ft P .fi .SS \fBrenderer\fP .sp Default: \fByaml_jinja\fP .sp The renderer to use on the minions to render the state data .sp .nf .ft C renderer: yaml_jinja .ft P .fi .sp Default:: \fBFalse\fP .sp Set the global failhard flag, this informs all states to stop running states at the moment a single state fails .sp .nf .ft C failhard: False .ft P .fi .SS Master File Server Settings .SS \fBfile_roots\fP .sp Default: \fBbase: [/srv/salt]\fP .sp Salt runs a lightweight file server written in zeromq to deliver files to minions. This file server is built into the master daemon and does not require a dedicated port. The file server works on environments passed to the master. Each environment can have multiple root directories. The subdirectories in the multiple file roots cannot match, otherwise the downloaded files will not be able to be reliably ensured. A base environment is required to house the top file. Example: .sp .nf .ft C file_roots: base: \- /srv/salt/ dev: \- /srv/salt/dev/services \- /srv/salt/dev/states prod: \- /srv/salt/prod/services \- /srv/salt/prod/states .ft P .fi .sp .nf .ft C base: \- /srv/salt .ft P .fi .SS \fBhash_type\fP .sp Default: \fBmd5\fP .sp The hash_type is the hash to use when discovering the hash of a file on the master server, the default is md5, but sha1, sha224, sha256, sha384 and sha512 are also supported. .sp .nf .ft C hash_type: md5 .ft P .fi .SS \fBfile_buffer_size\fP .sp Default: \fB1048576\fP .sp The buffer size in the file server in bytes .sp .nf .ft C file_buffer_size: 1048576 .ft P .fi .SS Syndic Server Settings .sp A Salt syndic is a Salt master used to pass commands from a higher Salt master to minions below the syndic. Using the syndic is simple. If this is a master that will have syndic servers(s) below it, set the "order_masters" setting to True. If this is a master that will be running a syndic daemon for passthrough the "syndic_master" setting needs to be set to the location of the master server .SS \fBorder_masters\fP .sp Default: \fBFalse\fP .sp Extra data needs to be sent with publications if the master is controlling a lower level master via a syndic minion. If this is the case the order_masters value must be set to True .sp .nf .ft C order_masters: False .ft P .fi .SS \fBsyndic_master\fP .sp Default: \fBNone\fP .sp If this master will be running a salt\-syndic to connect to a higher level master, specify the higher level master with this configuration value .sp .nf .ft C syndic_master: masterofmasters .ft P .fi .SS Peer Publish Settings .sp Salt minions can send commands to other minions, but only if the minion is allowed to. By default "Peer Publication" is disabled, and when enabled it is enabled for specific minions and specific commands. This allows secure compartmentalization of commands based on individual minions. .SS \fBpeer\fP .sp Default: \fB{}\fP .sp The configuration uses regular expressions to match minions and then a list of regular expressions to match functions. The following will allow the minion authenticated as foo.example.com to execute functions from the test and pkg modules .sp .nf .ft C peer: foo.example.com: \- test.* \- pkg.* .ft P .fi .sp This will allow all minions to execute all commands: .sp .nf .ft C peer: .*: \- .* .ft P .fi .sp This is not recommended, since it would allow anyone who gets root on any single minion to instantly have root on all of the minions! .SS Node Groups .sp Default: \fB{}\fP .sp Node groups allow for logical groupings of minion nodes. A group consists of a group name and a compound target. .sp .nf .ft C nodegroups: group1: \(aqL@foo.domain.com,bar.domain.com,baz.domain.com and bl*.domain.com\(aq group2: \(aqG@os:Debian and foo.domain.com\(aq .ft P .fi .SS Master Logging Settings .SS \fBlog_file\fP .sp Default: \fB/var/log/salt/master\fP .sp The location of the master log file .sp .nf .ft C log_file: /var/log/salt/master .ft P .fi .SS \fBlog_level\fP .sp Default: \fBwarning\fP .sp The level of messages to send to the log file. One of \(aqinfo\(aq, \(aqquiet\(aq, \(aqcritical\(aq, \(aqerror\(aq, \(aqdebug\(aq, \(aqwarning\(aq. .sp .nf .ft C log_level: warning .ft P .fi .SS \fBlog_granular_levels\fP .sp Default: \fB{}\fP .sp Logger levels can be used to tweak specific loggers logging levels. Imagine you want to have the salt library at the \(aqwarning\(aq level, but you still wish to have \(aqsalt.modules\(aq at the \(aqdebug\(aq level: .sp .nf .ft C log_granular_levels: \(aqsalt\(aq: \(aqwarning\(aq, \(aqsalt.modules\(aq: \(aqdebug\(aq .ft P .fi .SH CONFIGURING THE SALT MINION .sp The Salt system is amazingly simple and easy to configure, the two components of the Salt system each have a respective configuration file. The \fBsalt\-master\fP is configured via the master configuration file, and the \fBsalt\-minion\fP is configured via the minion configuration file. .IP "See also" .sp \fIexample minion configuration file\fP .RE .sp The Salt Minion configuration is very simple, typically the only value that needs to be set is the master value so the minion can find its master. .SS Minion Primary Configuration .SS \fBmaster\fP .sp Default: \fBsalt\fP .sp The hostname or ipv4 of the master. .sp .nf .ft C master: salt .ft P .fi .SS \fBmaster_port\fP .sp Default: \fB4506\fP .sp The port of the master ret server, this needs to coincide with the ret_port option on the salt master. .sp .nf .ft C master_port: 4506 .ft P .fi .SS \fBuser\fP .sp Default: \fBroot\fP .sp The user to run the Salt processes .sp .nf .ft C user: root .ft P .fi .SS \fBpki_dir\fP .sp Default: \fB/etc/salt/pki\fP .sp The directory used to store the minion\(aqs public and private keys. .sp .nf .ft C pki_dir: /etc/salt/pki .ft P .fi .SS \fBid\fP .sp Default: hostname (as returned by the Python call: \fBsocket.getfqdn()\fP) .sp Explicitly declare the id for this minion to use, if left commented the id will be the hostname as returned by the python call: socket.getfqdn() Since salt uses detached ids it is possible to run multiple minions on the same machine but with different ids, this can be useful for salt compute clusters. .sp .nf .ft C id: foo.bar.com .ft P .fi .SS \fBsub_timeout\fP .sp The minion connection to the master may be interrupted, the minion will verify the connection every so many seconds, to disable connection verification set this value to 0 .sp .nf .ft C sub_timeout: 60 .ft P .fi .SS \fBcachedir\fP .sp Default: \fB/var/cache/salt\fP .sp The location for minion cache data. .sp .nf .ft C cachedir: /var/cache/salt .ft P .fi .SS \fBcache_jobs\fP .sp Default: \fBFalse\fP .sp The minion can locally cache the return data from jobs sent to it, this can be a good way to keep track minion side of the jobs the minion has executed. By default this feature is disabled, to enable set cache_jobs to True .sp .nf .ft C cache_jobs: False .ft P .fi .SS \fBacceptance_wait_time\fP .sp Default: \fB10\fP .sp The number of seconds to wait until attempting to re\-authenticate with the master. .sp .nf .ft C acceptance_wait_time: 10 .ft P .fi .SS Minion Module Management .SS \fBdisable_modules\fP .sp Default: \fB[]\fP (all modules are enabled by default) .sp The event may occur in which the administrator desires that a minion should not be able to execute a certain module. The sys module is built into the minion and cannot be disabled. .sp This setting can also tune the minion, as all modules are loaded into ram disabling modules will lover the minion\(aqs ram footprint. .sp .nf .ft C disable_modules: \- test \- solr .ft P .fi .SS \fBdisable_returners\fP .sp Default: \fB[]\fP (all returners are enabled by default) .sp If certain returners should be disabled, this is the place .sp .nf .ft C disable_returners: \- mongo_return .ft P .fi .SS \fBmodule_dirs\fP .sp Default: \fB[]\fP .sp A list of extra directories to search for salt modules .sp .nf .ft C module_dirs: \- /var/lib/salt/modules .ft P .fi .SS \fBreturner_dirs\fP .sp Default: \fB[]\fP .sp A list of extra directories to search for salt returners .sp .nf .ft C returners_dirs: \- /var/lib/salt/returners .ft P .fi .SS \fBstates_dirs\fP .sp Default: \fB[]\fP .sp A list of extra directories to search for salt states .sp .nf .ft C states_dirs: \- /var/lib/salt/states .ft P .fi .SS \fBrender_dirs\fP .sp Default: \fB[]\fP .sp A list of extra directories to search for salt renderers .sp .nf .ft C render_dirs: \- /var/lib/salt/renderers .ft P .fi .SS \fBcython_enable\fP .sp Default: \fBFalse\fP .sp Set this value to true to enable auto loading and compiling of .pyx modules, This setting requires that gcc and cython are installed on the minion .sp .nf .ft C cython_enable: False .ft P .fi .SS State Management Settings .SS \fBrenderer\fP .sp Default: \fByaml_jinja\fP .sp The default renderer used for local state executions .sp .nf .ft C renderer: yaml_jinja .ft P .fi .SS \fBstate_verbose\fP .sp Default: \fBFalse\fP .sp state_verbose allows for the data returned from the minion to be more verbose. Normally only states that fail or states that have changes are returned, but setting state_verbose to True will return all states that were checked .sp .nf .ft C state_verbose: True .ft P .fi .SS \fBautoload_dynamic_modules\fP .sp Default: \fBTrue\fP .sp autoload_dynamic_modules Turns on automatic loading of modules found in the environments on the master. This is turned on by default, to turn of autoloading modules when states run set this value to False .sp .nf .ft C autoload_dynamic_modules: True .ft P .fi .sp Default: \fBTrue\fP .sp clean_dynamic_modules keeps the dynamic modules on the minion in sync with the dynamic modules on the master, this means that if a dynamic module is not on the master it will be deleted from the minion. By default this is enabled and can be disabled by changing this value to False .sp .nf .ft C clean_dynamic_modules: True .ft P .fi .SS \fBenvironment\fP .sp Default: \fBNone\fP .sp Normally the minion is not isolated to any single environment on the master when running states, but the environment can be isolated on the minion side by statically setting it. Remember that the recommended way to manage environments is to isolate via the top file. .sp .nf .ft C environment: None .ft P .fi .SS Security Settings .SS \fBopen_mode\fP .sp Default: \fBFalse\fP .sp Open mode can be used to clean out the pki key received from the salt master, turn on open mode, restart the minion, then turn off open mode and restart the minion to clean the keys. .sp .nf .ft C open_mode: False .ft P .fi .SS Thread Settings .sp Default: \fBTrue\fP .sp Disable multiprocessing support, by default when a minion receives a publication a new process is spawned and the command is executed therein. .sp .nf .ft C multiprocessing: True .ft P .fi .SS Minion Logging Settings .SS \fBlog_file\fP .sp Default: \fB/var/log/salt/minion\fP .sp The location of the minion log file .sp .nf .ft C log_file: /var/log/salt/minion .ft P .fi .SS \fBlog_level\fP .sp Default: \fBwarning\fP .sp The level of messages to send to the log file. One of \(aqinfo\(aq, \(aqquiet\(aq, \(aqcritical\(aq, \(aqerror\(aq, \(aqdebug\(aq, \(aqwarning\(aq. .sp .nf .ft C log_level: warning .ft P .fi .SS \fBlog_granular_levels\fP .sp Default: \fB{}\fP .sp Logger levels can be used to tweak specific loggers logging levels. Imagine you want to have the salt library at the \(aqwarning\(aq level, but, you still wish to have \(aqsalt.modules\(aq at the \(aqdebug\(aq level: .sp .nf .ft C log_granular_levels: \(aqsalt\(aq: \(aqwarning\(aq, \(aqsalt.modules\(aq: \(aqdebug\(aq .ft P .fi .SH COMMAND LINE REFERENCE .sp Salt can be controlled by a command line client by the root user on the Salt master. The Salt command line client uses the Salt client API to communicate with the Salt master server. The Salt client is straightforward and simple to use. .sp Using the Salt client commands can be easily sent to the minions. .sp Each of these commands accepts an explicit \fI\-\-config\fP option to point to either the master or minion configuration file. If this option is not provided and the default configuration file does not exist then Salt falls back to use the environment variables \fBSALT_MASTER_CONFIG\fP and \fBSALT_MINION_CONFIG\fP. .IP "See also" .sp \fB/topics/configuration\fP .RE .SS Using the Salt Command .sp The Salt command needs a few components to send information to the salt minions. The target minions need to be defined, the function to call and any arguments the function requires. .SS Defining the Target Minions .sp The first argument passed to salt, defines the target minions, the target minions are accessed via their hostname. The default target type is a bash glob: .sp .nf .ft C salt \e*foo.com sys.doc .ft P .fi .sp Salt can also define the target minions with regular expressions: .sp .nf .ft C salt \-E \(aq.*\(aq cmd.run \(aqls \-l | grep foo\(aq .ft P .fi .sp Or to explicitly list hosts, salt can take a list: .sp .nf .ft C salt \-L foo.bar.baz,quo.qux cmd.run \(aqps aux | grep foo\(aq .ft P .fi .SS More Powerful Targets .sp The simple target specifications, glob, regex and list will cover many use cases, and for some will cover all use cases, but more powerful options exist. .SS Targeting with Grains .sp The Grains interface was built into Salt to allow minions to be targeted by system properties. So minions running on a particular operating system can be called to execute a function, or a specific kernel. .sp Calling via a grain is done by passing the \-G option to salt, specifying a grain and a regular expression to match the value of the grain. .sp .nf .ft C salt \-G \(aqos:Fedora\(aq test.ping .ft P .fi .sp Will return True from all of the minions running Fedora. .sp To discover what grains are available and what the values are, execute the grains.item salt function: .sp .nf .ft C salt \(aq*\(aq grains.items .ft P .fi .SS Targeting with Executions .sp As of 0.8.8 targeting with executions is still under heavy development and this documentation is written to reference the behavior of execution matching in the future. .sp Execution matching allows for a primary function to be executed, and then based on the return of the primary function the main function is executed. .sp Execution matching allows for matching minions based on any arbitrary running data on the minions. .SS Compound Targeting .sp New in version 0.9.5. .sp Multiple target interfaces can be used in conjunction to determine the command targets. These targets can then be combined using and or or statements. This is well defined with an example: .sp .nf .ft C salt \-C \(aqG@os:Debian and webser* or E@db.*\(aq test.ping .ft P .fi .sp In this example any minion who\(aqs id starts with \fBwebser\fP and is running Debian, or any minion who\(aqs id starts with db will be matched. .sp The type of matcher defaults to glob, but can be specified with the corresponding letter followed by the \fB@\fP symbol. In the above example a grain is used with \fBG@\fP as well as a regular expression with \fBE@\fP. The \fBwebser*\fP target does not need to be prefaced with a target type specifier because it is a glob. .SS Node Group Targeting .sp New in version 0.9.5. .sp Often the convenience of having a predefined group of minions to execute targets on is desired. This can be accomplished with the new nodegroups feature. Nodegroups allow for predefined compound targets to be declared in the master configuration file: .sp .nf .ft C nodegroups: \ group1: \(aqL@foo.domain.com,bar.domain.com,baz.domain.com and bl*.domain.com\(aq \ group2: \(aqG@os:Debian and foo.domain.com\(aq .ft P .fi .SS Calling the Function .sp The function to call on the specified target is placed after the target specification. .SS Finding available minion functions .sp The Salt functions are self documenting, all of the function documentation can be retried from the minions via the \fBsys.doc()\fP function: .sp .nf .ft C salt \(aq*\(aq sys.doc .ft P .fi .SS Compound Command Execution .sp If a series of commands need to be sent to a single target specification then the multiple commands can be send in a single publish. This can make gathering groups of information faster, and lowers the stress on the network for repeated commands. .sp Compound command execution works by sending a list of functions and arguments instead of sending a single function and argument. The functions are executed on the minion in the order they are defined on the command line, and then the data from all of the commands are returned in a dictionary. This means that the set of commands are called in a predictable way, and the returned data can be easily interpreted. .sp Executing compound commands if done by passing a comma delimited list of functions, followed by a comma delimited list of arguments: .sp .nf .ft C salt \(aq*\(aq cmd.run,test.ping,test.echo \(aqcat /proc/cpuinfo\(aq,,foo .ft P .fi .sp The trick to look out for here, is that if a function is being passed no arguments, then there needs to be a placeholder for the absent arguments. This is why in the above example, there are two commas right next to each other. \fBtest.ping\fP takes no arguments, so we need to add another comma, otherwise Salt would attempt to pass "foo" to \fBtest.ping\fP. .SH SALT .SS Synopsis .INDENT 0.0 .INDENT 3.5 salt \(aq*\(aq [ options ] sys.doc .sp salt \-E \(aq.*\(aq [ options ] sys.doc cmd .sp salt \-G \(aqos:Arch.*\(aq [ options ] test.ping .sp salt \-C \fI\%'G@os\fP:Arch.* and webserv* or \fI\%G@kernel\fP:FreeBSD\(aq [ options ] test.ping .sp salt \-Q test.ping .UNINDENT .UNINDENT .SS Description .sp Salt allows for commands to be executed across a swath of remote systems in parallel. This means that remote systems can be both controlled and queried with ease. .SS Options .INDENT 0.0 .TP .B \-h, \-\-help Print a usage message briefly summarizing these command\-line options .UNINDENT .INDENT 0.0 .TP .B \-t TIMEOUT, \-\-timeout=TIMEOUT The timeout in seconds to wait for replies from the salt minions. .UNINDENT .INDENT 0.0 .TP .B \-s STATIC, \-\-static=STATIC By default as of version 0.9.8 the salt command returns data to the console as it is received from minions, but previous releases would return data only after all data was received. To only return the data with a hard timeout and after all minions have returned then use the static option. .UNINDENT .INDENT 0.0 .TP .B \-b BATCH, \-\-batch\-size=BATCH Instead of executing on all targeted minions at once, execute on a progressive set of minions. This option takes an argument in the form of an explicit number of minions to execute at once, or a percentage of minions to execute on. .UNINDENT .INDENT 0.0 .TP .B \-\-version Print the version of salt that is running. .UNINDENT .INDENT 0.0 .TP .B \-E, \-\-pcre The target expression will be interpreted as a pcre regular expression rather than a shell glob. .UNINDENT .INDENT 0.0 .TP .B \-L, \-\-list The target expression will be interpreted as a comma delimited list, example: server1.foo.bar,server2.foo.bar,example7.quo.qux .UNINDENT .INDENT 0.0 .TP .B \-G, \-\-grain The target expression matches values returned by the salt grains system on the minions. The target expression is in the format of \(aq<grain value>:<glob expression>\(aq; example: \(aqos:Arch*\(aq .sp This was changed in version 0.9.8 to accept glob expressions instead of regular expression. To use regular expression matching with grains use the \-\-grain\-pcre option. .UNINDENT .INDENT 0.0 .TP .B \-\-grain\-pcre The target expression matches values returned by the salt grains system on the minions. The target expression is in the format of \(aq<grain value>:< regular expression>\(aq; example: \(aqos:Arch.*\(aq .UNINDENT .INDENT 0.0 .TP .B \-C, \-\-compound Utilize many target definitions to make the call very granular. This option takes a group of targets separated by and or or. The default matcher is a glob as usual, if something other than a glob is used preface it with the letter denoting the type, example: \(aqwebserv* and \fI\%G@os\fP:Debian or \fI\%E@db*\fP\(aq make sure that the compound target is encapsulated in quotes. .UNINDENT .INDENT 0.0 .TP .B \-X, \-\-exsel Instead of using shell globs use the return code of a function. .UNINDENT .INDENT 0.0 .TP .B \-N, \-\-nodegroup Use a predefined compound target defined in the salt master configuration file .UNINDENT .INDENT 0.0 .TP .B \-R, \-\-range Instead of using shell globs to evaluate the targe use a range expression to identify targets. Range expressions look like %cluster. .sp Using the Range option requires that a range server is set up and the location of the range server is referenced in the master configuration file. .UNINDENT .INDENT 0.0 .TP .B \-\-return Chose an alternative returner to call on the minion, if an alternative returner is used then the return will not come back tot he command line but will be sent to the specified return system. .UNINDENT .INDENT 0.0 .TP .B \-Q, \-\-query The \-Q option is being deprecated and will be removed in version 0.9.9, Use the salt jobs interface instead, for documentation on the salt jobs interface execute the command "salt\-run \-d jobs" .sp Execute a salt command query, this can be used to find the results of a previous function call: \-Q test.echo\(aq) .UNINDENT .INDENT 0.0 .TP .B \-c CONFIG, \-\-config=CONFIG The location of the salt master configuration file, the salt master settings are required to know where the connections are; default=/etc/salt/master .UNINDENT .INDENT 0.0 .TP .B \-\-raw\-out Print the output from the salt command in raw python form, this is suitable for re\-reading the output into an executing python script with eval. .UNINDENT .INDENT 0.0 .TP .B \-\-text\-out Print the output from the salt command in the same form the shell would. .UNINDENT .INDENT 0.0 .TP .B \-\-yaml\-out Print the output from the salt command in yaml. .UNINDENT .INDENT 0.0 .TP .B \-\-json\-out Print the output from the salt command in json. .UNINDENT .INDENT 0.0 .TP .B \-\-no\-color Disable all colored output .UNINDENT .SS See also .sp \fIsalt(7)\fP \fIsalt\-master(1)\fP \fIsalt\-minion(1)\fP .SH SALT-MASTER .sp The salt master daemon, used to control the salt minions .SS Synopsis .sp salt\-master [ options ] .SS Description .sp The master daemon controls the salt minions .SS Options .INDENT 0.0 .TP .B \-h, \-\-help Print a usage message briefly summarizing these command\-line options. .UNINDENT .INDENT 0.0 .TP .B \-d, \-\-daemon Run the salt master as a daemon .UNINDENT .INDENT 0.0 .TP .B \-c CONFIG, \-\-config=CONFIG The master configuration file to use, the default is /etc/salt/master .UNINDENT .INDENT 0.0 .TP .B \-u USER, \-\-user=USER Specify user to run minion .UNINDENT .INDENT 0.0 .TP .B \-\-pid\-file PIDFILE Specify the location of the pidfile. .UNINDENT .INDENT 0.0 .TP .B \-l LOG_LEVEL, \-\-log\-level=LOG_LEVEL Console log level. One of \fBinfo\fP, \fBnone\fP, \fBgarbage\fP, \fBtrace\fP, \fBwarning\fP, \fBerror\fP, \fBdebug\fP. For the logfile settings see the config file. Default: \fBwarning\fP. .UNINDENT .SH SALT-MINION .sp The salt minion daemon, receives commands from a remote salt master. .SS Synopsis .sp salt\-minion [ options ] .SS Description .sp The salt minion receives commands from the central salt master and replies with the results of said commands. .SS Options .INDENT 0.0 .TP .B \-h, \-\-help Print a usage message briefly summarizing these command\-line options. .UNINDENT .INDENT 0.0 .TP .B \-d, \-\-daemon Run the salt minion as a daemon .UNINDENT .INDENT 0.0 .TP .B \-c CONFIG, \-\-config=CONFIG The minion configuration file to use, the default is /etc/salt/minion .UNINDENT .INDENT 0.0 .TP .B \-u USER, \-\-user=USER Specify user to run minion .UNINDENT .INDENT 0.0 .TP .B \-\-pid\-file PIDFILE Specify the location of the pidfile .UNINDENT .INDENT 0.0 .TP .B \-l LOG_LEVEL, \-\-log\-level=LOG_LEVEL Console log level. One of \fBinfo\fP, \fBnone\fP, \fBgarbage\fP, \fBtrace\fP, \fBwarning\fP, \fBerror\fP, \fBdebug\fP. For the logfile settings see the config file. Default: \fBwarning\fP. .UNINDENT .SH SALT-KEY .SS Synopsis .sp salt\-key [ options ] .SS Description .sp Salt\-key executes simple management of salt server public keys used for authentication. .SS Options .INDENT 0.0 .TP .B \-h, \-\-help Print a usage message briefly summarizing these command\-line options. .UNINDENT .INDENT 0.0 .TP .B \-l, \-\-list List the unaccepted minion public keys. .UNINDENT .INDENT 0.0 .TP .B \-L, \-\-list\-all List all public keys on this salt master: accepted, pending, and rejected. .UNINDENT .INDENT 0.0 .TP .B \-a ACCEPT, \-\-accept=ACCEPT Accept the named minion public key for command execution. .UNINDENT .INDENT 0.0 .TP .B \-A, \-\-accept\-all Accepts all pending public keys. .UNINDENT .INDENT 0.0 .TP .B \-r REJECT, \-\-reject=REJECT Reject the named minion public key. .UNINDENT .INDENT 0.0 .TP .B \-R, \-\-reject\-all Rejects all pending public keys. .UNINDENT .INDENT 0.0 .TP .B \-d DELETE, \-\-delete=DELETE Delete the named minion key for command execution. .UNINDENT .INDENT 0.0 .TP .B \-D DELETE_ALL, \-\-delete\-all=DELETE_ALL Deleta all keys .UNINDENT .INDENT 0.0 .TP .B \-c CONFIG, \-\-config=CONFIG The master configuration file needs to be read to determine where the salt keys are stored via the pki_dir configuration value; default=/etc/salt/master .UNINDENT .SH SALT-CP .sp Copy a file to a set of systems .SS Synopsis .sp .nf .ft C salt\-cp \(aq*\(aq [ options ] SOURCE DEST salt\-cp \-E \(aq.*\(aq [ options ] SOURCE DEST salt\-cp \-G \(aqos:Arch.*\(aq [ options ] SOURCE DEST .ft P .fi .SS Description .sp Salt copy copies a local file out to all of the salt minions matched by the given target. .SS Options .INDENT 0.0 .TP .B \-h, \-\-help Print a usage message briefly summarizing these command\-line options .UNINDENT .INDENT 0.0 .TP .B \-t TIMEOUT, \-\-timeout=TIMEOUT The timeout in seconds to wait for replies from the salt minions. .UNINDENT .INDENT 0.0 .TP .B \-E, \-\-pcre The target expression will be interpreted as a pcre regular expression rather than a shell glob. .UNINDENT .INDENT 0.0 .TP .B \-L, \-\-list The target expression will be interpreted as a comma delimited list, example: server1.foo.bar,server2.foo.bar,example7.quo.qux .UNINDENT .INDENT 0.0 .TP .B \-G, \-\-grain The target expression matches values returned by the salt grains system on the minions. The target expression is in the format of \(aq<grain value>:<glob expression>\(aq; example: \(aqos:Arch*\(aq .UNINDENT .INDENT 0.0 .TP .B \-\-grain\-pcre The target expression matches values returned by the salt grains system on the minions. The target expression is in the format of \(aq<grain value>:<pcre regular expression>\(aq; example: \(aqos:Arch.*\(aq .UNINDENT .INDENT 0.0 .TP .B \-R, \-\-range Instead of using shell globs to evaluate the targe use a range expression to identify targets. Range expressions look like %cluster. .sp Using the Range option requires that a range server is set up and the location of the range server is referenced in the master configuration file. .UNINDENT .INDENT 0.0 .TP .B \-C, \-\-compound Utilize many target definitions to make the call very granular. This option takes a group of targets separated by and or or. The default matcher is a glob as usual, if something other than a glob is used preface it with the letter denoting the type, example: \(aqwebserv* and \fI\%G@os\fP:Debian or \fI\%E@db*\fP\(aq make sure that the compound target is encapsulated in quotes. .UNINDENT .INDENT 0.0 .TP .B \-c CONFIG, \-\-config=CONFIG The location of the salt master configuration file, the salt master settings are required to know where the connections are; default=/etc/salt/master .UNINDENT .SH SALT-CALL .SS Synopsis .sp .nf .ft C salt\-call [options] .ft P .fi .SS Options .INDENT 0.0 .TP .B \-h, \-\-help Print a usage message briefly summarizing these command\-line options .UNINDENT .INDENT 0.0 .TP .B \-g, \-\-grains Return the information generated by the salt grains .UNINDENT .INDENT 0.0 .TP .B \-m MODULE_DIRS, \-\-module\-dirs=MODULE_DIRS Specify an additional directories to pull modules from, multiple directories can be delimited by commas .UNINDENT .INDENT 0.0 .TP .B \-d, \-\-doc Return the documentation for the specified module of for all modules if none are specified .UNINDENT .INDENT 0.0 .TP .B \-l LOG_LEVEL, \-\-log\-level=LOG_LEVEL Console log level. One of \fBinfo\fP, \fBnone\fP, \fBgarbage\fP, \fBtrace\fP, \fBwarning\fP, \fBerror\fP, \fBdebug\fP. For the logfile settings see the config file. Default: \fBinfo\fP. .UNINDENT .INDENT 0.0 .TP .B \-\-raw\-out Print the output from the salt command in raw python form, this is suitable for re\-reading the output into an executing python script with eval. .UNINDENT .INDENT 0.0 .TP .B \-\-text\-out Print the output from the salt command in the same form the shell would. .UNINDENT .INDENT 0.0 .TP .B \-\-yaml\-out Print the output from the salt command in yaml. .UNINDENT .INDENT 0.0 .TP .B \-\-json\-out Print the output from the salt command in json. .UNINDENT .INDENT 0.0 .TP .B \-\-no\-color Disable all colored output .UNINDENT .SH SALT-RUN .sp Execute a Salt runner .SS Synopsis .sp .nf .ft C salt\-run RUNNER .ft P .fi .SS Description .sp salt\-run is the frontend command for executing \fBSalt Runners\fP. Salt runners are simple modules used to execute convenience functions on the master .SS Options .INDENT 0.0 .TP .B \-h, \-\-help Print a usage message briefly summarizing these command\-line options .UNINDENT .INDENT 0.0 .TP .B \-c CONFIG, \-\-config=CONFIG The location of the salt master configuration file, the salt master settings are required to know where the connections are; default=/etc/salt/master .UNINDENT .SH SALT-SYNDIC .sp The salt syndic daemon, a special minion that passes through commands from a higher master .SS Synopsis .sp salt\-syndic [ options ] .SS Description .sp The salt syndic daemon, a special minion that passes through commands from a higher master. .SS Options .INDENT 0.0 .TP .B \-h, \-\-help Print a usage message briefly summarizing these command\-line options. .UNINDENT .INDENT 0.0 .TP .B \-d, \-\-daemon Run the salt syndic as a daemon .UNINDENT .INDENT 0.0 .TP .B \-\-pid\-file PIDFILE Specify the location of the pidfile .UNINDENT .INDENT 0.0 .TP .B \-\-master\-config=MASTER_CONFIG The master configuration file to use, the default is /etc/salt/master .UNINDENT .INDENT 0.0 .TP .B \-\-minion\-config=MINION_CONFIG The minion configuration file to use, the default is /etc/salt/minion .UNINDENT .SH ABSTRACT ON SALT AUTHENTICATION AND ENCRYPTION .sp The Salt authentication and encryption system uses Public Key authentication and AES encryption to facilitate both authentication and high speed encryption. .sp The core components of this system can be separated into a few sections, Message Formatting, PubKey Handshake, AES key management, and encryption. .SS Message Formatting .sp All messages passed within Salt are formatted with a clear header and a "load". The header is always clear, and specifies the encryption used by the load. The load can be encrypted with the private key of the sending system, or with the shared, rotating, AES key. .sp The message itself is abstracted as a python dict in this fashion: .sp .nf .ft C {\(aqenc\(aq: \(aqaes\(aq, \(aqload\(aq: <encrypted msgpack binary data>} .ft P .fi .sp When this message is received the load can be decrypted using the shared AES key. The \(aqenc\(aq dict key can also be "pub" for pubkey encryption, or "clear" for passing messages in the clear. .SS PubKey Handshake .sp RSA Public keys are generated on the Salt master and on the Salt minion. When A salt minion establishes an initial connection to the salt master the minion sends its public key in the clear to the salt master, along with the id of the minion, and the command to execute on the master, in this case "_auth": .sp .nf .ft C {\(aqenc\(aq: \(aqclear\(aq, \(aqload\(aq: {\(aqcmd\(aq: \(aq_auth\(aq, \(aqid\(aq: <minion id>, \(aqpub\(aq: <minion public key>}} .ft P .fi .sp If this is the first time this minion has authenticated, then the salt master returns a clear message informing the minion that it is pending authentication. The minion then queries the master every ten seconds awaiting authentication. When the public key of the minion has been approved by the master, then the master\(aqs public key is returned, with the AES key used to encrypt messages and information on how to connect to the salt master publish interface. .sp The returned AES key is encrypted with the minion\(aqs public key, and can therefore only be decrypted by the minion that sent out the public key. .sp Once the minion has authenticated and is in possession of the revolving master AES key (The AES key is regenerated when the master restarts) then it attaches the minion subscriber to the master publisher. .sp All messages sent from the publisher are encrypted using the revolving AES key, in the event that the master restarts the minions will all have an invalid AES key because it has been regenerated on the master. The master will then send out a publication that the minions cannot decrypt. If the minion receives a publication that cannot be decrypted then the minion will re\-authenticate, obtain the correct AES key, and decrypt the message. This means that the AES key on the salt master can safely revolve without interrupting the minion connection. .SS Regular Communication .sp Once the minion has authenticated, then all messages sent between the minion and the master are encrypted using the revolving AES key and the {\(aqenc\(aq: \(aqaes\(aq} header. .SS Source Files Implimenting Components .sp The pubkey authentication is managed via the salt.master module: \fI\%https://github.com/saltstack/salt/blob/v0.9.8/salt/master.py\fP The regular minion authentication is managed via the salt.crypt module: \fI\%https://github.com/saltstack/salt/blob/v0.9.8/salt/crypt.py\fP The salt.crypt module contains a class "SAuth" that can be used for standalone authentication with the Salt master, this is most likely the best place to start when looking into how the authentication mechanism works The encrypted "load" portion of the messages are encrypted and decrypted using the Crypticle class in the crypt module. .SS Conclusion .sp In the end Salt uses formatted messages with clear header data to specify how the message data is encrypted. Asymetric encryption via RSA keys is only used for authentication and to securely retrieve the master AES key. All further communications are are encrypted with 256 bit AES. .SH SALT STACK ROADMAP .sp Salt is the core of a more complete goal, the Salt Stack. The Salt Stack is a complete infrastructure management system which is comprised of many components all functioning on top of Salt. .sp The majority of the functionality of the Salt Stack happens directly inside Salt, but the information derived from Salt needs to be used to create a transparent view of the infrastructure as a whole. .sp The information used in Salt States will be matched via a higher interface and the low salt data will be visualized. This will allow the state data to appear in the web interface. .sp The features listed here are only listed based on major version releases, the plan is to have a clear long term goal but not to overly dictate the flow of development. The project needs to be flexible enough to be able to receive new features at a moment\(aqs notice. This model should spur ideas and make allowing new community developers to join without issue. So just because something is slated for a later reason does not mean that a developer is going to have their code rejected or stalled. .SS 1.0.0 .sp 1.0.0 requires that remote execution is stable and that states are ready to complete. We mostly just need to clean things up for 1.0.0. .SS Clean up code base .sp Go through the code, clean up PEP 8 violations and make sure we have Python 3 compatible code. .SS Module Cross Calls .sp Many instances of using functions when we should be using module cross calls exist in the code. Mostly from modules which were written before cross calls were around. The big thing to look for are subprocess calls, since they should all be running with the cmd module. .SS State Return Data Cleanup .sp The return structures in the state modules need to be uniform in how they are declared, before we get too much of a following we should have as consistent modules as possible. We want to hit the gate with very clean code! .SS States and Modules .sp More states need to be available. .SS User State .sp The user state needs to be expanded to support password setting and managing the finger component .SS Clean up Bugs .sp We are finding a number of bugs in the new state system as we get more testers there are a few bugs that been attention: .sp #66 .sp We need to keep pushing through testing states on live systems and find as many bugs as possible before 1.0, we have found too many 0 day bugs. .SS Documentation .sp The documentation has gotten a LOT better, but we still need more work in a few places .SS Clean up formatting .sp The 1.0 PDF needs to be a document that we can publish to the world with pride .SS Expand the State Tutorial .sp We are learning a lot about how to teach states, we need to take this knowledge and improve the states tutorial. We want people to be able to get going with states in no time at all .SS Module Built in Docs .sp Double check all of the module built in docs for consistency. Make sure things are clear and accurate. .SS Proposal System .sp I would like to have a proposal system in place for Salt, so that community members can submit proposals for feature development for review. Using Github\(aqs new issue system with support for tags (blocker, feature...) seems like a good choice. .SS Workflow .sp Gitflow not only makes for a good branching model everybody can understand and work with but also scales well and just works (tm). Let\(aqs start using it! .SS 2.0.0 .sp 2.0.0 will require a number of serious additions and overhauls. We wand to make the transport layer much cleaner and clean up the crypto dependencies. Figure out how to get more speed out of Salt and make it more memory efficient. The security system needs some additions to make it more secure. .sp There are also a number of features that should be pulled out of their classes and made to stand alone. Also we want to MASSIVELY improve platform support and module/state penetration. .sp This is only a subset of what we can expect 2.0.0 to be! .sp With 1.0.0 salt is a great option, with 2.0.0, using anything else is just plain dumb! .SS Python 3 Support .sp The goal so far has been to write Salt with 3.0 in mind, but with 2.0 we want it to be a reality. This will mostly require that the requirements are met. .SS Refine Security .SS Only One Crypt Backend .sp Right now we have pycrypto and m2crypto, we need to pick just one. So far the plan is to dump m2crypto and use just pycrypto. .SS Make the iv explicit .sp Right now the iv is implied by the length of the AES key, we want the iv to be randomly applied and sent with the AES key. .SS Master Signatures .sp There is a theoretical vulnerability in the validation of transit messages, they need to have a master private key signature somewhere. .SS Change Network Serialization .sp Right now it is pickle, this needs to be changed to something more standard like JSON or maybe even something simpler/faster such as tnetstrings as used by Mongrel2. We also need to change how messages are formatted to speed up the serialization and lower network usage more. A new model will be proposed. .SS State Generator .sp Since the state system is based on data structures we can generate them from a uniform API, this needs to be available in renderer modules. .SS Separate out the File Server .sp Te built in file server should be less built in. We will make a standalone file server from the existing built in one that is more powerful and can be used with and without encryption and authentication. The updated file server should also be faster, so that large files can be downloaded more quickly. .sp The salt\-cp command needs to be moved to use the file server as well, so that it can be used to copy large files as well. .SS Support for more Platforms .sp Platform support means a few things, primarily that we have support for the major modules pertinent to the platforms and that Salt will run on these platforms at least as a minion. .sp Solaris Gentoo Suse Slackware OpenBSD NetBSD AIX HPUX Windows .SS Language Library Modules and States .sp Modules and States that support installing programming language packages. Here is the list to start with: .sp pypi rubygem cpan lua haskell? .SS Firewall Support .sp This is going to be rather serious, this is a collection of modules for iptables, pf, and the subsequent subsystems for other platforms. But in the end, we want seamless firewall support for at least opening up ports for services. .SS Advanced Grains .sp The grains system still needs an overhaul, the problem is that grains should have access to each other, but they should still only be run once. Some plans are in place to pull this off, but they need to be implemented. .SS More Renderers! .sp The renderer system needs to support more templating engines and language bindings. Adding support for XML, Cheetah, Tenjin etc. will be simple. But the main goal here is to allow sls files to be written in Ruby, Lua, Perl or basically anything. .SS Unit Tests .sp Need unit tests in place for everything, we are planning on using Unittest2 and pytest. .SH RELEASE NOTES AND UPGRADE INSTRUCTIONS .SS Salt 0.6.0 release notes .sp The Salt remote execution manager has reached initial functionality! Salt is a management application which can be used to execute commands on remote sets of servers. .sp The whole idea behind Salt is to create a system where a group of servers can be remotely controlled from a single master, not only can commands be executed on remote systems, but salt can also be used to gather information about your server environment. .sp Unlike similar systems, like Func and MCollective, Salt is extremely simple to setup and use, the entire application is contained in a single package, and the master and minion daemons require no running dependencies in the way that Func requires Certmaster and MCollective requires activeMQ. .sp Salt also manages authentication and encryption. Rather than using ssl for encryption, salt manages encryption on a payload level, so the data sent across the network is encrypted with fast aes encryption, and authentication uses RSA keys. This means that Salt is fast, secure, and very efficient. .sp Messaging in Salt is executed with zeromq, so the message passing interface is built into salt and does not require an external MQ server. This also adds speed to Salt since there is no additional bloat on the networking layer, and zeromq has already proven itself as a very fast networking system. .sp The remote execution in Salt is "Lazy Execution", in that once the command is sent the requesting network connection is closed. This makes it easier to detach the execution from the calling process on the master, it also means that replies are cached, so that information gathered from historic commands can be queried in the future. .sp Salt also allows users to make execution modules in python. Writers of these modules should also be pleased to know that they have access to the impressive information gathered from PuppetLabs\(aq Facter application, making Salt module more flexible. In the future I hope to also allow Salt to group servers based on facter information as well. .sp All in all Salt is fast, efficient and clean, can be used from a simple command line client or through an api, uses message queue technology to make network execution extremely fast, and encryption is handled in a very fast and efficient manner. Salt is also VERY easy to use and VERY easy to extend. .sp You can find the source code for Salt on my github page, I have also set up a few wiki pages explaining how to use and set up Salt. If you are using Arch Linux there is a package available in the Arch Linux AUR. .sp Salt 0.6.0 Source: \fI\%https://github.com/downloads/saltstack/salt/salt-0.6.0.tar.gz\fP .sp Github page: \fI\%https://github.com/saltstack/salt\fP .sp Wiki: \fI\%https://github.com/saltstack/salt/wiki\fP .sp Arch Linux Package: \fI\%https://aur.archlinux.org/packages.php?ID=47512\fP .sp I am very open to contributions, for instance I need packages for more Linux distributions as well as BSD packages and testers. .sp Give Salt a try, this is the initial release and is not a 1.0 quality release, but it has been working well for me! I am eager to get your feedback! .SS Salt 0.7.0 release notes .sp I am pleased to announce the release of Salt 0.7.0! .sp This release marks what is the first stable release of salt, 0.7.0 should be suitable for general use. .sp 0.7.0 Brings the following new features to Salt: .INDENT 0.0 .IP \(bu 2 Integration with facter data from puppet labs .IP \(bu 2 Allow for matching minions from the salt client via facter information .IP \(bu 2 Minion job threading, many jobs can be executed from the master at once .IP \(bu 2 Preview of master clustering support \- Still experimental .IP \(bu 2 Introduce new minion modules for stats, virtualization, service management and more .IP \(bu 2 Add extensive logging to the master and minion daemons .IP \(bu 2 Add sys.reload_functions for dynamic function reloading .IP \(bu 2 Greatly improve authentication .IP \(bu 2 Introduce the saltkey command for managing public keys .IP \(bu 2 Begin backend development preparatory to introducing butter .IP \(bu 2 Addition of man pages for the core commands .IP \(bu 2 Extended and cleaned configuration .UNINDENT .sp 0.7.0 Fixes the following major bugs: .INDENT 0.0 .IP \(bu 2 Fix crash in minions when matching failed .IP \(bu 2 Fix configuration file lookups for the local client .IP \(bu 2 Repair communication bugs in encryption .IP \(bu 2 Numerous fixes in the minion modules .UNINDENT .sp The next release of Salt should see the following features: .INDENT 0.0 .IP \(bu 2 Stabilize the cluster support .IP \(bu 2 Introduce a remote client for salt command tiers .IP \(bu 2 salt\-ftp system for distributed file copies .IP \(bu 2 Initial support for "butter" .UNINDENT .sp Coming up next is a higher level management framework for salt called Butter. I want salt to stay as a simple and effective communication framework, and allow for more complicated executions to be managed via Butter. .sp Right now Butter is being developed to act as a cloud controller using salt as the communication layer, but features like system monitoring and advanced configuration control (a puppet manager) are also in the pipe. .sp Special thanks to Joseph Hall for the status and network modules, and thanks to Matthias Teege for tracking down some configuration bugs! .sp Salt can be downloaded from the following locations; .sp Source Tarball: .sp \fI\%https://github.com/downloads/saltstack/salt/salt-0.7.0.tar.gz\fP .sp Arch Linux Package: .sp \fI\%https://aur.archlinux.org/packages.php?ID=47512\fP .sp Please enjoy the latest Salt release! .SS Salt 0.8.0 release notes .sp Salt 0.8.0 is ready for general consumption! The source tarball is available on github for download: .sp \fI\%https://github.com/downloads/saltstack/salt/salt-0.8.0.tar.gz\fP .sp A lot of work has gone into salt since the last release just 2 weeks ago, and salt has improved a great deal. A swath of new features are here along with performance and threading improvements! .sp The main new features of salt 0.8.0 are: .sp Salt\-cp .sp Cython minion modules .sp Dynamic returners .sp Faster return handling .sp Lowered required python version to 2.6 .sp Advanced minion threading .sp Configurable minion modules .SS Salt\-cp \- .sp The salt\-cp command introduces the ability to copy simple files via salt to targeted servers. Using salt\-cp is very simple, just call salt\-cp with a target specification, the source file(s) and where to copy the files on the minions. For instance: .sp # salt\-cp ‘*’ /etc/hosts /etc/hosts .sp Will copy the local /etc/hosts file to all of the minions. .sp Salt\-cp is very young, in the future more advanced features will be added, and the functionality will much more closely resemble the cp command. .SS Cython minion modules \- .sp Cython is an amazing tool used to compile python modules down to c. This is arguably the fastest way to run python code, and since pyzmq requires cython, adding support to salt for cython adds no new dependencies. .sp Cython minion modules allow minion modules to be written in cython and therefore executed in compiled c. Simply write the salt module in cython and use the file extension “.pyx” and the minion module will be compiled when the minion is started. An example cython module is included in the main distribution called cytest.pyx: .sp \fI\%https://github.com/saltstack/salt/blob/v0.9.8/salt/modules/cytest.pyx\fP .SS Dynamic Returners \- .sp By default salt returns command data back to the salt master, but now salt can return command data to any system. This is enabled via the new returners modules feature for salt. The returners modules take the return data and sends it to a specific module. The returner modules work like minion modules, so any returner can be added to the minions. .sp This means that a custom data returner can be added to communicate the return data so anything from MySQL, redis, mongodb and more! .sp There are 2 simple stock returners in the returners directory: .sp \fI\%https://github.com/saltstack/salt/blob/v0.9.8/salt/returners\fP .sp The documentation on writing returners will be added to the wiki shortly, and returners can be written in pure python, or in cython. .SS Configurable Minion Modules \- .sp Minion modules may need to be configured, now the options passed to the minion configuration file can be accessed inside of the minion modules via the __opt__ dict. .sp Information on how to use this simple addition has been added to the wiki: \fI\%https://github.com/thatch45/salt/wiki/Writing-Salt-Modules\fP .sp The test module has an example of using the __opts__ dict, and how to set default options: .sp \fI\%https://github.com/saltstack/salt/blob/v0.9.8/salt/modules/test.py\fP .SS Advanced Minion Threading: .sp In 0.7.0 the minion would block after receiving a command from the master, now the minion will spawn a thread or multiprocess. By default python threads are used because for general use they have proved to be faster, but the minion can now be configured to use the python multiprocessing module instead. Using multiprocessing will cause executions that are cpu bound or would otherwise exploit the negative aspects of the Python GIL to run faster and more reliably, but simple calls will still be faster with python threading. The configuration option can be found in the minion configuration file: .sp \fI\%https://github.com/saltstack/salt/blob/v0.9.8/conf/minion\fP .sp Lowered Supported Python to 2.6 \- .sp The requirement for python 2.7 has been removed to support python 2.6. I have received requests to take the minimum python version back to 2.4, but unfortunately this will not be possible, since the zeromq python bindings do not support python 2.4. .sp Salt 0.8.0 is a very major update, it also changes the network protocol slightly which makes communication with older salt daemons impossible, your master and minions need to be upgraded together! I could use some help bringing salt to the people! Right now I only have packages for Arch Linux, Fedora 14 and Gentoo. We need packages for Debian and people willing to help test on more platforms. We also need help writing more minion modules and returner modules. If you want to contribute to salt please hop on the mailing list and send in patches, make a fork on github and send in pull requests! If you want to help but are not sure where you can, please email me directly or post tot he mailing list! .sp I hope you enjoy salt, while it is not yet 1.0 salt is completely viable and usable! .sp \-Thomas S. Hatch .SS Salt 0.8.7 release notes .sp It has been a month since salt 0.8.0, and it has been a long month! But Salt is still coming along strong. 0.8.7 has a lot of changes and a lot of updates. This update makes Salt’s ZeroMQ back end better, strips facter from the dependencies, and introduces interfaces to handle more capabilities. .sp Many of the major updates are in the background, but the changes should shine through to the surface. A number of the new features are still a little thin, but the back end to support expansion is in place. .sp I also recently gave a presentation to the Utah Python users group in Salt Lake City, the slides from this presentation are available here: \fI\%https://github.com/downloads/saltstack/salt/Salt.pdf\fP .sp The video from this presentation will be available shortly. .sp The major new features and changes in Salt 0.8.7 are: .INDENT 0.0 .IP \(bu 2 Revamp ZeroMQ topology on the master for better scalability .IP \(bu 2 State enforcement .IP \(bu 2 Dynamic state enforcement managers .IP \(bu 2 Extract the module loader into salt.loader .IP \(bu 2 Make Job ids more granular .IP \(bu 2 Replace facter functionality with the new salt grains interface .IP \(bu 2 Support for “virtual” salt modules .IP \(bu 2 Introduce the salt\-call command .IP \(bu 2 Better debugging for minion modules .UNINDENT .sp The new ZeroMQ topology allows for better scalability, this will be required by the need to execute massive file transfers to multiple machines in parallel and state management. The new ZeroMQ topology is available in the aforementioned presentation. .sp 0.8.7 introduces the capability to declare states, this is similar to the capabilities of Puppet. States in salt are declared via state data structures. This system is very young, but the core feature set is available. Salt states work around rendering files which represent Salt high data. More on the Salt state system will be documented in the near future. .sp The system for loading salt modules has been pulled out of the minion class to be a standalone module, this has enabled more dynamic loading of Salt modules and enables many of the updates in 0.8.7 – .sp \fI\%https://github.com/saltstack/salt/blob/v0.9.8/salt/loader.py\fP .sp Salt Job ids are now microsecond precise, this was needed to repair a race condition unveiled by the speed improvements in the new ZeroMQ topology. .sp The new grains interface replaces the functionality of Facter, the idea behind grains differs from Facter in that the grains are only used for static system data, dynamic data needs to be derived from a call to a salt module. This makes grains much faster to use, since the grains data is generated when the minion starts. .sp Virtual salt modules allows for a salt module to be presented as something other than its module name. The idea here is that based on information from the minion decisions about which module should be presented can be made. The best example is the pacman module. The pacman module will only load on Arch Linux minions, and will be called pkg. Similarly the yum module will be presented as pkg when the minion starts on a Fedora/RedHat system. .sp The new salt\-call command allows for minion modules to be executed from the minion. This means that on the minion a salt module can be executed, this is a great tool for testing Salt modules. The salt\-call command can also be used to view the grains data. .sp In previous releases when a minion module threw an exception very little data was returned to the master. Now the stack trace from the failure is returned making debugging of minion modules MUCH easier. .sp Salt is nearing the goal of 1.0, where the core feature set and capability is complete! .sp Salt 0.8.7 can be downloaded from github here: \fI\%https://github.com/downloads/saltstack/salt/salt-0.8.7.tar.gz\fP .sp \-Thomas S Hatch .SS Salt 0.8.8 release notes .sp Salt 0.8.8 is here! This release adds a great deal of code and some serious new features. The latest release can be downloaded here: \fI\%https://github.com/downloads/saltstack/salt/salt-0.8.8.tar.gz\fP .sp Improved Documentation has been set up for salt using sphinx thanks to the efforts of Seth House. This new documentation system will act as the back end to the salt website which is still under heavy development. The new sphinx documentation system has also been used to greatly clean up the salt manpages. The salt 7 manpage in particular now contains extensive information which was previously only in the wiki. The new documentation can be found at: \fI\%http://thatch45.github.com/salt-www/\fP We still have a lot to add, and when the domain is set up I will post another announcement. .sp More additions have been made to the ZeroMQ setup, particularly in the realm of file transfers. Salt 0.8.8 introduces a built in, stateless, encrypted file server which allows salt minions to download files from the salt master using the same encryption system used for all other salt communications. The main motivation for the salt file server has been to facilitate the new salt state system. .sp Much of the salt code has been cleaned up and a new cleaner logging system has been introduced thanks to the efforts of Pedro Algarvio. These additions will allow for much more flexible logging to be executed by salt, and fixed a great deal of my poor spelling in the salt docstrings! Pedro Algarvio has also cleaned up the api, making it easier to embed salt into another application. .sp The biggest addition to salt found in 0.8.8 is the new state system. The salt module system has received a new front end which allows salt to be used as a configuration management system. The configuration management system allows for system configuration to be defined in data structures. The configuration management system, or as it is called in salt, the “salt state system” supports many of the features found in other configuration managers, but allows for system states to be written in a far simpler format, executes at blazing speeds, and operates via the salt minion matching system. The state system also operates within the normal scope of salt, and requires no additional configuration to use. .sp The salt state system can enforce the following states with many more to come: Packages Files Services Executing commands Hosts .sp The system used to define the salt states is based on a data structure, the data structure used to define the salt states has been made to be as easy to use as possible. The data structure is defined by default using a yaml file rendered via a jinja template. This means that the state definition language supports all of the data structures that yaml supports, and all of the programming constructs and logic that jinja supports. If the user does not like yaml or jinja the states can be defined in yaml\-mako, json\-jinja, or json\-mako. The system used to render the states is completely dynamic, and any rendering system can be added to the capabilities of Salt, this means that a rendering system that renders xml data in a cheetah template, or whatever you can imagine, can be easily added to the capabilities of salt. .sp The salt state system also supports isolated environments, as well as matching code from several environments to a single salt minion. .sp The feature base for Salt has grown quite a bit since my last serious documentation push. As we approach 0.9.0 the goals are becoming very clear, and the documentation needs a lot of work. The main goals for 0.9.0 are to further refine the state system, fix any bugs we find, get Salt running on as many platforms as we can, and get the documentation filled out. There is a lot more to come as Salt moves forward to encapsulate a much larger scope, while maintaining supreme usability and simplicity. .sp If you would like a more complete overview of Salt please watch the Salt presentation: Flash Video: \fI\%http://blip.tv/thomas-s-hatch/salt-0-8-7-presentation-5180182\fP OGV Video Download: \fI\%http://blip.tv/file/get/Thatch45-Salt087Presentation416.ogv\fP Slides: \fI\%https://github.com/downloads/saltstack/salt/Salt.pdf\fP .sp \-Thomas S Hatch .SS Salt 0.8.9 Release Notes .sp Salt 0.8.9 has finally arrived! Unfortunately this is much later than I had hoped to release 0.8.9, life has been very crazy over the last month. But despite challenges, Salt has moved forward! .sp This release, as expected, adds few new features and many refinements. One of the most exciting aspect of this release is that the development community for salt has grown a great deal and much of the code is from contributors. .sp Also, I have filled out the documentation a great deal. So information on States is properly documented, and much of the documentation that was out of date has been filled in. .SS Download! .sp The Salt source can be downloaded from the salt github site: .sp \fI\%https://github.com/downloads/saltstack/salt/salt-0.8.9.tar.gz\fP .sp Or from PiPy: .sp \fI\%http://pypi.python.org/packages/source/s/salt/salt-0.8.9.tar.gz\fP .sp Here s the md5sum: .sp 7d5aca4633bc22f59045f59e82f43b56 .sp For instructions on how to set up Salt please see the \fI\%installation\fP instructions. .SS New Features .SS Salt Run .sp A big feature is the addition of Salt run, the \fBsalt\-run\fP command allows for master side execution modules to be made that gather specific information or execute custom routines from the master. .sp Documentation for salt\-run can be found here: .sp \fI\%http://saltstack.org/ref/runners.html\fP .SS Refined Outputters .sp One problem often complained about in salt was the fact that the output was so messy. Thanks to help from Jeff Schroeder a cleaner interface for the command output for the Salt cli has been made. This new interface makes adding new printout formats easy and additions to the capabilities of minion modules makes it possible to set the printout mode or \fBoutputter\fP for functions in minion modules. .SS Cross Calling Salt Modules .sp Salt modules can now call each other, the \fB__salt__\fP dict has been added to the predefined references in minion modules. This new feature is documented in the modules documentation: .sp \fI\%http://saltstack.org/ref/modules/index.html\fP .SS Watch Option Added to Salt State System .sp Now in Salt states you can set the watch option, this will allow watch enabled states to change based on a change in the other defined states. This is similar to subscribe and notify statements in puppet. .SS Root Dir Option .sp Travis Cline has added the ability to define the option \fBroot_dir\fP which allows the salt minion to operate in a subdir. This is a strong move in supporting the minion running as an unprivileged user .SS Config Files Defined in Variables .sp Thanks again to Travis Cline, the master and minion configuration file locations can be defined in environment variables now. .SS New Modules .sp Quite a few new modules, states, returners and runners have been made. .SS New Minion Modules .SS apt .sp Support for apt\-get has been added, this adds greatly improved Debian and Ubuntu support to Salt! .SS useradd and groupadd .sp Support for manipulating users and groups on Unix\-like systems. .SS moosefs .sp Initial support for reporting on aspects of the distributed file system, MooseFS. For more information on MooseFS please see: \fI\%http://moosefs.org\fP .sp Thanks to Joseph Hall for his work on MooseFS support. .SS mount .sp Manage mounts and the fstab. .SS puppet .sp Execute puppet on remote systems. .SS shadow .sp Manipulate and manage the user password file. .SS ssh .sp Interact with ssh keys. .SS New States .SS user and group .sp Support for managing users and groups in Salt States. .SS mount .sp Enforce mounts and the fstab. .SS New Returners .SS mongo_return .sp Send the return information to a mongodb server. .SS New Runners .SS manage .sp Display minions that are up or down. .SS Salt 0.9.0 Release Notes .sp Salt 0.9.0 is here. This is an exciting release, 0.9.0 includes the new network topology features allowing peer salt commands and masters of masters via the syndic interface. .sp 0.9.0 also introduces many more modules, improvements to the api and improvements to the ZeroMQ systems. .SS Download! .sp The Salt source can be downloaded from the salt github site: .sp \fI\%https://github.com/downloads/saltstack/salt/salt-0.9.0.tar.gz\fP .sp Or from PiPy: .sp \fI\%http://pypi.python.org/packages/source/s/salt/salt-0.9.0.tar.gz\fP .sp Here is the md5sum: .sp 9a925da04981e65a0f237f2e77ddab37 .sp For instructions on how to set up Salt please see the \fI\%installation\fP instructions. .SS New Features .SS Salt Syndic .sp The new Syndic interface allows a master to be commanded via another higher level salt master. This is a powerful solution allowing a master control structure to exist, allowing salt to scale to much larger levels then before. .sp \fI\%http://saltstack.org/ref/syndic.html\fP .SS Peer Communication .sp 0.9.0 introduces the capability for a minion to call a publication on the master and receive the return from another set of minions. This allows salt to act as a communication channel between minions and as a general infrastructure message bus. .sp Peer communication is turned off by default but can be enabled via the \fBpeer\fP option in the master configuration file. Documentation on the new peer interface can be found here: .sp \fI\%http://saltstack.org/ref/peer.html\fP .SS Easily Extensible API .sp The minion and master classes have been redesigned to allow for specialized minion and master servers to be easily created. An example on how this is done for the master can be found in the \fBmaster.py\fP salt module: .sp \fI\%https://github.com/saltstack/salt/blob/v0.9.8/salt/master.py\fP .sp The \fBMaster\fP class extends the \fBSMaster\fP class and set up the main master server. .sp The minion functions can now also be easily added to another application via the \fBSMinion\fP class, this class can be found in the \fBminion.py\fP module: .sp \fI\%https://github.com/saltstack/salt/blob/v0.9.8/salt/minion.py\fP .SS Cleaner Key Management .sp This release changes some of the key naming to allow for multiple master keys to be held based on the type of minion gathering the master key. .sp The \-d option has also been added to the salt\-key command allowing for easy removal of accepted public keys. .sp The \-\-gen\-keys option is now available as well for salt\-key, this allows for a salt specific RSA key pair to be easily generated from the command line. .SS Improved 0MQ Master Workers .sp The 0MQ worker system has been further refined to be faster and more robust. This new system has been able to handle a much larger load than the previous setup. The new system uses the ipc protocol in 0MQ instead of tcp. .SS New Modules .sp Quite a few new modules have been made. .SS New Minion Modules .SS apache .sp Work directly with apache servers, great for managing balanced web servers .SS cron .sp Read out the contents of a systems crontabs .SS mdadm .sp Module to manage raid devices in Linux, appears as the \fBraid\fP module .SS mysql .sp Gather simple data from MySQL databases .SS ps .sp Extensive utilities for managing processes .SS publish .sp Used by the peer interface to allow minions to make publications .SS Salt 0.9.2 Release Notes .sp Salt 0.9.2 has arrived! 0.9.2 is primarily a bugfix release, the exciting component in 0.9.2 is greatly improved support for salt states. All of the salt states interfaces have been more thoroughly tested and the new salt\-states git repo is growing with example of how to use states. .sp This release introduces salt states for early developers and testers to start helping us clean up the states interface and make it ready for the world! .sp 0.9.2 also fixes a number of bugs found on python 2.6. .SS Download! .sp The Salt source can be downloaded from the salt github site: .sp \fI\%https://github.com/downloads/saltstack/salt/salt-0.9.2.tar.gz\fP .sp Or from PiPy: .sp \fI\%http://pypi.python.org/packages/source/s/salt/salt-0.9.2.tar.gz\fP .sp For instructions on how to set up Salt please see the \fI\%installation\fP instructions. .SS New Features .SS Salt\-Call Additions .sp The salt\-call command has received an overhaul, it now hooks into the outputter system so command output looks clean, and the logging system has been hooked into salt\-call, so the \-l option allows the logging output from salt minion functions to be displayed. .sp The end result is that the salt\-call command can execute the state system and return clean output: .sp .nf .ft C # salt\-call state.highstate .ft P .fi .SS State System Fixes .sp The state system has been tested and better refined. As of this release the state system is ready for early testers to start playing with. If you are interested in working with the state system please check out the (still very small) salt\-states github repo: .sp \fI\%https://github.com/thatch45/salt-states\fP .sp This git repo is the active development branch for determining how a clean salt\-state database should look and act. Since the salt state system is still very young a lot of help is still needed here. Please fork the salt\-states repo and help us develop a truly large and scalable system for configuration management! .SS Notable Bug Fixes .SS Python 2.6 String Formatting .sp Python 2.6 does not support format strings without an index identifier, all of them have been repaired. .SS Cython Loading Disabled by Default .sp Cython loading requires a development tool chain to be installed on the minion, requiring this by default can cause problems for most Salt deployments. If Cython auto loading is desired it will need to be turned on in the minion config. .SS Salt 0.9.3 Release Notes .sp Salt 0.9.3 is finally arrived. This is another big step forward for Salt, new features range from proper FreeBSD support to fixing issues seen when attaching a minion to a master over the Internet. .sp The biggest improvements in 0.9.3 though can be found in the state system, it has progressed from something ready for early testers to a system ready to compete with platforms such as Puppet and Chef. The backbone of the state system has been greatly refined and many new features are available. .SS Download! .sp The Salt source can be downloaded from the salt github site: .sp \fI\%https://github.com/downloads/saltstack/salt/salt-0.9.3.tar.gz\fP .sp Or from PiPy: .sp \fI\%http://pypi.python.org/packages/source/s/salt/salt-0.9.3.tar.gz\fP .sp For instructions on how to set up Salt please see the \fI\%installation\fP instructions. .SS New Features .SS WAN Support .sp Recently more people have been testing Salt minions connecting to Salt Masters over the Internet. It was found that Minions would commonly loose their connection to the master when working over the internet. The minions can now detect if the connection has been lost and reconnect to the master, making WAN connections much more reliable. .SS State System Fixes .sp Substantial testing has gone into the state system and it is ready for real world usage. A great deal has been added to the documentation for states and the modules and functions available to states have been cleanly documented. .sp A number of State System bugs have also been founds and repaired, the output from the state system has also been refined to be extremely clear and concise. .sp Error reporting has also been introduced, issues found in sls files will now be clearly reported when executing Salt States. .SS Extend Declaration .sp The Salt States have also gained the \fBextend\fP declaration. This declaration allows for states to be cleanly modified in a post environment. Simply said, if there is an apache.sls file that declares the apache service, then another sls can include apache and then extend it: .sp .nf .ft C include: \- apache extend: apache: service: \- require: \- pkg: mod_python mod_python: pkg: \- installed .ft P .fi .sp The notable behavior with the extend functionality is that it literally extends or overwrites a declaration set up in another sls module. This means that Salt will behave as though the modifications were made directly to the apache sls. This ensures that the apache service in this example is directly tied to all requirements. .SS Highstate Structure Specification .sp This release comes with a clear specification of the Highstate data structure that is used to declare Salt States. This specification explains everything that can be declared in the Salt SLS modules. .sp The specification is extremely simple, and illustrates how Salt has been able to fulfill the requirements of a central configuration manager within a simple and easy to understand format and specification. .SS SheBang Renderer Switch .sp It came to our attention that having many renderers means that there may be a situation where more than one State Renderer should be available within a single State Tree. .sp The method chosen to accomplish this was something already familiar to developers and systems administrators, a SheBang. The Python State Renderer displays this new capability. .SS Python State Renderer .sp Until now Salt States could only be declared in yaml or json using jinja or mako. A new, very powerful, renderer has been added, making it possible to write Salt States in pure python: .sp .nf .ft C #!py def run(): \(aq\(aq\(aq Install the python\-mako package \(aq\(aq\(aq return {\(aqinclude\(aq: [\(aqpython\(aq], \(aqpython\-mako\(aq: {\(aqpkg\(aq: [\(aqinstalled\(aq]}} .ft P .fi .sp This renderer is used by making a run function that returns the Highstate data structure. Any capabilities of python can be used in pure python sls modules. .sp This example of a pure python sls module is the same as this example in yaml: .sp .nf .ft C include: \- python python\-mako: pkg: \- installed .ft P .fi .SS FreeBSD Support .sp Additional support has been added for FreeBSD, this is Salt\(aqs first branch out of the Linux world and proves the viability of Salt on non\-Linux platforms. .sp Salt remote execution already worked on FreeBSD, and should work without issue on any Unix\-like platform. But this support comes in the form of package management and user support, so Salt States also work on FreeBSD now. .sp The new freebsdpkg module provides package management support for FreeBSD and the new pw_user and pw_group provide user and group management. .SS Module and State Additions .SS Cron Support .sp Support for managing the system crontab has been added, declaring a cron state can be done easily: .sp .nf .ft C date > /tmp/datestamp: cron: \- present \- user: fred \- minute: 5 \- hour: 3 .ft P .fi .SS File State Additions .sp The file state has been given a number of new features, primarily the directory, recurse, symlink and absent functions. .INDENT 0.0 .TP .B file.directory Make sure that a directory exists and has the right permissions. .sp .nf .ft C /srv/foo: file: \- directory \- user: root \- group: root \- mode: 1755 .ft P .fi .TP .B file.symlink Make a symlink. .sp .nf .ft C /var/lib/www: file: \- symlink \- target: /srv/www \- force: True .ft P .fi .TP .B file.recurse The recurse state function will recursively download a directory on the master file server and place it on the minion. Any change in the files on the master will be pushed to the minion. The recuse function is very powerful and has been tested by pushing out the full Linux kernel source. .sp .nf .ft C /opt/code: file: \- recurse \- source: salt://linux .ft P .fi .TP .B file.absent Make sure that the file is not on the system, recursively delets directories, files and symlinks. .sp .nf .ft C /etc/httpd/conf.d/somebogusfile.conf: file: \- absent .ft P .fi .UNINDENT .SS Sysctl Module and State .sp The sysctl module and state allows for sysctl components in the kernel to be managed easily. the sysctl module contains the following functions: .INDENT 0.0 .TP .B sysctl.show Return a list of sysctl parameters for this minion .TP .B sysctl.get Return a single sysctl parameter for this minion .TP .B sysctl.assign Assign a single sysctl parameter for this minion .TP .B sysctl.persist Assign and persist a simple sysctl parameter for this minion .UNINDENT .sp The sysctl state allows for sysctl parameters to be assigned: .sp .nf .ft C vm.swappiness: sysctl: \- present \- value: 20 .ft P .fi .SS Kernel Module Management .sp A module for managing Linux kernel modules has been added. The new functions are as follows: .INDENT 0.0 .TP .B kmod.available Return a list of all available kernel modules .TP .B kmod.check_available Check to see if the specified kernel module is available .TP .B kmod.lsmod Return a dict containing information about currently loaded modules .TP .B kmod.load Load the specified kernel module .TP .B kmod.remove Unload the specified kernel module .UNINDENT .sp The kmod state can enforce modules be either present or absent: .sp .nf .ft C kvm_intel: kmod: \- present .ft P .fi .SS Ssh Authorized Keys .sp The ssh_auth state can distribute ssh authorized keys out to minions. Ssh authorized keys can be present or absent. .sp .nf .ft C AAAAB3NzaC1kc3MAAACBAL0sQ9fJ5bYTEyYvlRBsJdDOo49CNfhlWHWXQRqul6rwL4KIuPrhY7hBw0tV7UNC7J9IZRNO4iGod9C+OYutuWGJ2x5YNf7P4uGhH9AhBQGQ4LKOLxhDyT1OrDKXVFw3wgY3rHiJYAbd1PXNuclJHOKL27QZCRFjWSEaSrUOoczvAAAAFQD9d4jp2dCJSIseSkk4Lez3LqFcqQAAAIAmovHIVSrbLbXAXQE8eyPoL9x5C+x2GRpEcA7AeMH6bGx/xw6NtnQZVMcmZIre5Elrw3OKgxcDNomjYFNHuOYaQLBBMosyO++tJe1KTAr3A2zGj2xbWO9JhEzu8xvSdF8jRu0N5SRXPpzSyU4o1WGIPLVZSeSq1VFTHRT4lXB7PQAAAIBXUz6ZO0bregF5xtJRuxUN583HlfQkXvxLqHAGY8WSEVlTnuG/x75wolBDbVzeTlxWxgxhafj7P6Ncdv25Wz9wvc6ko/puww0b3rcLNqK+XCNJlsM/7lB8Q26iK5mRZzNsGeGwGTyzNIMBekGYQ5MRdIcPv5dBIP/1M6fQDEsAXQ==: ssh_auth: \- present \- user: frank \- enc: dsa \- comment: \(aqFrank\(aqs key\(aq .ft P .fi .SS Salt 0.9.4 Release Notes .sp Salt 0.9.4 has arrived. This is a critical update that repairs a number of key bugs found in 0.9.3. But this update is not without feature additions as well! 0.9.4 adds support for Gentoo portage to the pkg module and state system. Also there are 2 major new state additions, the failhard option and the ability to set up finite state ordering with the \fBorder\fP option. .sp This release also sees our largest increase in community contributions. These contributors have and continue to be the life blood of the Salt project, and the team continues to grow. I want to put out a big thanks to our new and existing contributors. .SS Download! .sp The Salt source can be downloaded from the salt github site: .sp \fI\%https://github.com/downloads/saltstack/salt/salt-0.9.4.tar.gz\fP .sp Or from PiPy: .sp \fI\%http://pypi.python.org/packages/source/s/salt/salt-0.9.4.tar.gz\fP .sp For instructions on how to set up Salt please see the \fI\%installation\fP instructions. .SS New Features .SS Failhard State Option .sp Normally, when a state fails Salt continues to execute the remainder of the defined states and will only refuse to execute states that require the failed state. .sp But the situation may exist, where you would want all state execution to stop if a single state execution fails. The capability to do this is called \fBfailing hard\fP. .SS State Level Failhard .sp A single state can have a failhard set, this means that if this individual state fails that all state execution will immediately stop. This is a great thing to do if there is a state that sets up a critical config file and setting a require for each state that reads the config would be cumbersome. A good example of this would be setting up a package manager early on: .sp .nf .ft C /etc/yum.repos.d/company.repo: file: \- managed \- source: salt://company/yumrepo.conf \- user: root \- group: root \- mode: 644 \- order: 1 \- failhard: True .ft P .fi .sp In this situation, the yum repo is going to be configured before other states, and if it fails to lay down the config file, than no other states will be executed. .SS Global Failhard .sp It may be desired to have failhard be applied to every state that is executed, if this is the case, then failhard can be set in the master configuration file. Setting failhard in the master configuration file will result in failing hard when any minion gathering states from the master have a state fail. .sp This is NOT the default behavior, normally Salt will only fail states that require a failed state. .sp Using the global failhard is generally not recommended, since it can result in states not being executed or even checked. It can also be confusing to see states failhard if an admin is not actively aware that the failhard has been set. .sp To use the global failhard set failhard: True in the master configuration .SS Finite Ordering of State Execution .sp When creating salt sls files, it is often important to ensure that they run in a specific order. While states will always execute in the same order, that order is not necessarily defined the way you want it. .sp A few tools exist in Salt to set up the correct state ordering, these tools consist of requisite declarations and order options. .SS The Order Option .sp Before using the order option, remember that the majority of state ordering should be done with requisite statements, and that a requisite statement will override an order option. .sp The order option is used by adding an order number to a state declaration with the option \fIorder\fP: .sp .nf .ft C vim: pkg: \- installed \- order: 1 .ft P .fi .sp By adding the order option to \fI1\fP this ensures that the vim package will be installed in tandem with any other state declaration set to the order \fI1\fP. .sp Any state declared without an order option will be executed after all states with order options are executed. .sp But this construct can only handle ordering states from the beginning. Sometimes you may want to send a state to the end of the line, to do this set the order to last: .sp .nf .ft C vim: pkg: \- installed \- order: last .ft P .fi .sp Substantial testing has gone into the state system and it is ready for real world usage. A great deal has been added to the documentation for states and the modules and functions available to states have been cleanly documented. .sp A number of State System bugs have also been founds and repaired, the output from the state system has also been refined to be extremely clear and concise. .sp Error reporting has also been introduced, issues found in sls files will now be clearly reported when executing Salt States. .SS Gentoo Support .sp Additional experimental support has been added for Gentoo. This is found in the contribution from Doug Renn, aka nestegg. .SS Salt 0.9.5 Release Notes .sp Salt 0.9.5 is one of the largest steps forward in the development of Salt. .sp 0.9.5 comes with many milestones, this release has seen the community of developers grow out to an international team of 46 code contributors and has many feature additions, feature enhancements, bug fixes and speed improvements. .IP Warning Be sure to \fIread the upgrade instructions\fP about the switch to msgpack before upgrading! .RE .SS Community .sp Nothing has proven to have more value to the development of Salt that the outstanding community that has been growing at such a great pace around Salt. This has proven not only that Salt has great value, but also the expandability of Salt is as exponential as I originally intended. .sp 0.9.5 has received over 600 additional commits since 0.9.4 with a swath of new commiters. The following individuals have contributed to the development of 0.9.5: .INDENT 0.0 .IP \(bu 2 Aaron Bull Schaefer .IP \(bu 2 Antti Kaihola .IP \(bu 2 Bas Tichelaar .IP \(bu 2 Brad Barden .IP \(bu 2 Brian Wagner .IP \(bu 2 Byron Clark .IP \(bu 2 Chris Scheller .IP \(bu 2 Christer Edwards .IP \(bu 2 Clint Savage .IP \(bu 2 Corey Quinn .IP \(bu 2 David Boucha .IP \(bu 2 Eivind Uggedal .IP \(bu 2 Eric Poelke .IP \(bu 2 Evan Borgstrom .IP \(bu 2 Jed Glazner .IP \(bu 2 Jeff Schroeder .IP \(bu 2 Jeffrey C. Ollie .IP \(bu 2 Jonas Buckner .IP \(bu 2 Kent Tenney .IP \(bu 2 Martin Schnabel .IP \(bu 2 Maxim Burgerhout .IP \(bu 2 Mitch Anderson .IP \(bu 2 Nathaniel Whiteinge .IP \(bu 2 Seth House .IP \(bu 2 Thomas S Hatch .IP \(bu 2 Thomas Schreiber .IP \(bu 2 Tor Hveem .IP \(bu 2 lzyeval .IP \(bu 2 syphernl .UNINDENT .sp This makes 21 new developers since 0.9.4 was released! .sp To keep up with the growing community follow Salt on Ohloh (\fI\%http://www.ohloh.net/p/salt\fP), to join the Salt development community, fork Salt on Github, and get coding (\fI\%https://github.com/saltstack/salt\fP)! .SS Major Features .SS SPEED! Pickle to msgpack .sp For a few months now we have been talking about moving away from python pickles for network serialization, but a preferred serialization format had not yet been found. After an extensive performance testing period involving everything from JSON to protocol buffers, a clear winner emerged. Message Pack (\fI\%http://msgpack.org/\fP) proved to not only be the fastest and most compact, but also the most "salt like". Message Pack is simple, and the code involved is very small. The msgpack library for python has been added directly to Salt. .sp This move introduces a few changes to Salt. First off, Salt is no longer a "noarch" package, since the msgpack lib is written in C. Salt 0.9.5 will also have compatibility issues with 0.9.4 with the default configuration. .sp We have gone through great lengths to avoid backwards compatibility issues with Salt, but changing the serialization medium was going to create issues regardless. Salt 0.9.5 is somewhat backwards compatible with earlier minions. A 0.9.5 master can command older minions, but only if the \fBserial\fP config value in the master is set to \fBpickle\fP. This will tell the master to publish messages in pickle format and will allow the master to receive messages in both msgpack and pickle formats. .sp Therefore \fBthe suggested methods for upgrading\fP are either to just upgrade everything at once, or: .INDENT 0.0 .IP 1. 3 Upgrade the master to 0.9.5 .IP 2. 3 Set \fBserial\fP to \fBpickle\fP in the master config .IP 3. 3 Upgrade the minions .IP 4. 3 Remove the \fBserial\fP option from the master config .UNINDENT .sp Since pickles can be used as a security exploit the ability for a master to accept pickles from minions at all will be removed in a future release. .SS C Bindings for YAML .sp All of the YAML rendering is now done with the YAML C bindings. This speeds up all of the sls files when running states. .SS Experimental Windows Support .sp David Boucha has worked tirelessly to bring initial support to Salt for Microsoft Windows operating systems. Right now the Salt Minion can run as a native Windows service and accept commands. .sp In the weeks and months to come Windows will receive the full treatment and will have support for Salt States and more robust support for managing Windows systems. This is a big step forward for Salt to move entirely outside of the Unix world, and proves Salt is a viable cross platform solution. Big Thanks to Dave for his contribution here! .SS Dynamic Module Distribution .sp Many Salt users have expressed the desire to have Salt distribute in\-house modules, states, renderers, returners, and grains. This support has been added in a number of ways: .SS Modules via States .sp Now when salt modules are deployed to a minion via the state system as a file, then the modules will be automatically loaded into the active running minion \- no restart required \- and into the active running state. So custom state modules can be deployed and used in the same state run. .SS Modules via Module Environment Directories .sp Under the file_roots each environment can now have directories that are used to deploy large groups of modules. These directories sync modules at the beginning of a state run on the minion, or can be manually synced via the Salt module \fBsalt.modules.saltutil.sync_all\fP. .sp The directories are named: .INDENT 0.0 .IP \(bu 2 \fB_modules\fP .IP \(bu 2 \fB_states\fP .IP \(bu 2 \fB_grains\fP .IP \(bu 2 \fB_renderers\fP .IP \(bu 2 \fB_returners\fP .UNINDENT .sp The modules are pushed to their respective scopes on the minions. .SS Module Reloading .sp Modules can now be reloaded without restarting the minion, this is done by calling the \fBsalt.modules.sys.reload_modules\fP function. .sp But wait, there\(aqs more! Now when a salt module of any type is added via states the modules will be automatically reloaded, allowing for modules to be laid down with states and then immediately used. .sp Finally, all modules are reloaded when modules are dynamically distributed from the salt master. .SS Enable / Disable Added to Service .sp A great deal of demand has existed for adding the capability to set services to be started at boot in the service module. This feature also comes with an overhaul of the service modules and initial systemd support. .sp This means that the \fBservice state\fP can now accept \fB\- enable: True\fP to make sure a service is enabled at boot, and \fB\- enable: False\fP to make sure it is disabled. .SS Compound Target .sp A new target type has been added to the lineup, the compound target. In previous versions the desired minions could only be targeted via a single specific target type, but now many target specifications can be declared. .sp These targets can also be separated by and/or operators, so certain properties can be used to omit a node: .sp .nf .ft C salt \-C \(aqwebserv* and G@os:Debian or E@db.*\(aq test.ping .ft P .fi .sp will match all minions with ids starting with webserv via a glob and minions matching the \fBos:Debian\fP grain. Or minions that match the \fBdb.*\fP regular expression. .SS Node Groups .sp Often the convenience of having a predefined group of minions to execute targets on is desired. This can be accomplished with the new nodegroups feature. Nodegroups allow for predefined compound targets to be declared in the master configuration file: .sp .nf .ft C nodegroups: group1: \(aqL@foo.domain.com,bar.domain.com,baz.domain.com and bl*.domain.com\(aq group2: \(aqG@os:Debian and foo.domain.com\(aq .ft P .fi .sp And then used via the \fB\-N\fP option: .sp .nf .ft C salt \-N group1 test.ping .ft P .fi .SS Minion Side Data Store .sp The data module introduces the initial approach into storing persistent data on the minions, specific to the minions. This allows for data to be stored on minions that can be accessed from the master or from the minion. .sp The Minion datastore is young, and will eventually provide an interface similar to a more mature key/value pair server. .SS Major Grains Improvement .sp The Salt grains have been overhauled to include a massive amount of extra data. this includes hardware data, os data and salt specific data. .SS Salt \-Q is Useful Now .sp In the past the salt query system, which would display the data from recent executions would be displayed in pure python, and it was unreadable. .sp 0.9.5 has added the outputter system to the \fB\-Q\fP option, thus enabling the salt query system to return readable output. .SS Packaging Updates .sp Huge strides have been made in packaging Salt for distributions. These additions are thanks to our wonderful community where the work to set up packages has proceeded tirelessly. .SS FreeBSD .sp Salt on FreeBSD? There a port for that: .sp \fI\%http://www.freebsd.org/cgi/cvsweb.cgi/ports/sysutils/salt/pkg-descr\fP .sp This port was developed and added by Christer Edwards. This also marks the first time Salt has been included in an upstream packaging system! .SS Fedora and Red Hat Enterprise .sp Salt packages have been prepared for inclusion in the Fedora Project and in EPEL for Red Hat Enterprise 5 and 6. These packages are the result of the efforts made by Clint Savage (herlo). .SS Debian/Ubuntu .sp A team of many contributors have assisted in developing packages for Debian and Ubuntu. Salt is still actively seeking inclusion in upstream Debian and Ubuntu and the package data that has been prepared is being pushed through the needed channels for inclusion. .sp These packages have been prepared with the help of: .INDENT 0.0 .IP \(bu 2 Corey .IP \(bu 2 Aaron Toponce .IP \(bu 2 and\(ga .UNINDENT .SS More to Come .sp We are actively seeking inclusion in more distributions. Primarily getting Salt into Gentoo, Suse, OpenBSD and preparing Solaris support are all turning into higher priorities. .SS Refinement .sp Salt continues to be refined into a faster, more stable and more usable application. 0.9.5 comes with more debug logging, more bug fixes and more complete support. .SS More Testing, More BugFixes .sp 0.9.5 comes with more bugfixes due to more testing than any previous release. The growing community and the introduction a a dedicated QA environment have unearthed many issues that were hiding under the covers. This has further refined and cleaned the state interface, taking care of things from minor visual issues to repairing misleading data. .SS Custom Exceptions .sp A custom exception module has been added to throw salt specific exceptions. This allows Salt to give much more granular error information. .SS New Modules .SS \fBdata\fP .sp The new data module manages a persistent datastore on the minion. Big thanks to bastichelaar for his help refining this module .SS \fBfreebsdkmod\fP .sp FreeBSD kernel modules can now be managed in the same way Salt handles Linux kernel modules. .sp This module was contributed thanks to the efforts of Christer Edwards .SS \fBgentoo_service\fP .sp Support has been added for managing services in Gentoo. Now Gentoo services can be started, stopped, restarted, enabled, disabled and viewed. .SS \fBpip\fP .sp The pip module introduces management for pip installed applications. Thanks goes to whitinge for the addition of the pip module .SS \fBrh_service\fP .sp The rh_service module enables Red Hat and Fedora specific service management. Now Red Hat like systems come with extensive management of the classic init system used by Red Hat .SS \fBsaltutil\fP .sp The saltutil module has been added as a place to hold functions used in the maintenance and management of salt itself. Saltutil is used to salt the salt minion. The saltutil module is presently used only to sync extension modules from the master server. .SS \fBsystemd\fP .sp Systemd support has been added to Salt, now systems using this next generation init system are supported on systems running systemd. .SS \fBvirtualenv\fP .sp The virtualenv module has been added to allow salt to create virtual python environments. Thanks goes to whitinge for the addition of the virtualenv module .SS \fBwin_disk\fP .sp Support for gathering disk information on Microsoft Windows minions The windows modules come courtesy of Utah_Dave .SS \fBwin_service\fP .sp The win_service module adds service support to Salt for Microsoft Windows services .SS \fBwin_useradd\fP .sp Salt can now manage local users on Microsoft Windows Systems .SS \fByumpkg5\fP .sp The yumpkg module introduces in 0.9.4 uses the yum api to interact with the yum package manager. Unfortunately, on Red Hat 5 systems salt does not have access to the yum api because the yum api is running under python 2.4 and Salt needs to run under python 2.6. .sp The yumpkg5 module bypasses this issue by shelling out to yum on systems where the yum api is not available. .SS New States .SS \fBmysql_database\fP .sp The new mysql_database state adds the ability to systems running a mysql server to manage the existence of mysql databases. .sp The mysql states are thanks to syphernl .SS \fBmysql_user\fP .sp The mysql_user state enables mysql user management. .SS \fBvirtualenv\fP .sp The virtualenv state can manage the state of python virtual environments. Thanks to Whitinge for the virtualenv state .SS New Returners .SS \fBcassandra_returner\fP .sp A returner allowing Salt to send data to a cassandra server. Thanks to Byron Clark for contributing this returner .SS Salt 0.9.6 Release Notes .sp Salt 0.9.6 is a release targeting a few bugs and changes. This is primarily targeting an issue found in the names declaration in the state system. But a few other bugs were also repaired, like missing support for grains in extmods. .sp Due to a conflict in distribution packaging msgpack will no longer be bundled with Salt, and is required as a dependency. .SS New Features .SS http and ftp support in files.managed .sp Now under the source option in the file.managed state a http or ftp address can be used instead of a file located on the salt master. .SS Allow Multiple Returners .sp Now the returner interface can define multiple returners, and will also return data back to the master, making the process less ambiguous. .SS Minion Memory Improvements .sp A number of modules have been taken out of the minion if the underlying systems required by said modules are not present on the minion system. A number of other modules need to be stripped out in this same way which should continue to make the minion more efficient. .SS Minions Can Locally Cache Return Data .sp A new option, cache_jobs, has been added to the minion to allow for all of the historically run jobs to cache on the minion, allowing for looking up historic returns. By default cache_jobs is set to False. .SS Pure Python Template Support For file.managed .sp Templates in the file.managed state can now be defined in a python script. This script needs to have a run function that returns the string that needs to be in the named file. .SS Salt 0.9.7 Release Notes .sp Salt 0.9.7 is here! The latest iteration of Salt brings more features and many fixes. This release is a great refinement over 0.9.6, adding many conveniences under the hood, as well as some features that make working with Salt much better. .sp A few highlights include the new Job system, refinements to the requisite system in states, the \fBmod_init\fP interface for states, external node classification, search path to managed files in the file state, and refinements and additions to dynamic module loading. .sp 0.9.7 also introduces the long developed (and oft changed) unit test framework and the initial unit tests. .SS Major Features .SS Salt Jobs Interface .sp The new jobs interface makes the management of running executions much cleaner and more transparent. Building on the existing execution framework the jobs system allows clear introspection into the active running state of the running Salt interface. .sp The Jobs interface is centered in the new minion side proc system. The minions now store msgpack serialized files under \fB/var/cache/salt/proc\fP. These files keep track of the active state of processes on the minion. .SS Functions in the saltutil Module .sp A number of functions have been added to the saltutil module to manage and view the jobs: .sp \fBrunning\fP \- Returns the data of all running jobs that are found in the proc directory. .sp \fBfind_job\fP \- Returns specific data about a certain job based on job id. .sp \fBsignal_job\fP \- Allows for a given jid to be sent a signal. .sp \fBterm_job\fP \- Sends a termination signal (\fBSIGTERM, 15\fP) to the process controlling the specified job. .sp \fBkill_job\fP Sends a kill signal (\fBSIGKILL, 9\fP) to the process controlling the specified job. .SS The jobs Runner .sp A convenience runner front end and reporting system has been added as well. The jobs runner contains functions to make viewing data easier and cleaner. .sp The jobs runner contains a number of functions... .SS active .sp The active function runs \fBsaltutil.running\fP on all minions and formats the return data about all running jobs in a much more usable and compact format. The active function will also compare jobs that have returned and jobs that are still running, making it easier to see what systems have completed a job and what systems are still being waited on. .SS lookup_jid .sp When jobs are executed the return data is sent back to the master and cached. By default is is cached for 24 hours, but this can be configured via the \fBkeep_jobs\fP option in the master configuration. .sp Using the \fBlookup_jid\fP runner will display the same return data that the initial job invocation with the salt command would display. .SS list_jobs .sp Before finding a historic job, it may be required to find the job id. \fBlist_jobs\fP will parse the cached execution data and display all of the job data for jobs that have already, or partially returned. .SS External Node Classification .sp Salt can now use external node classifiers like Cobbler\(aqs \fBcobbler\-ext\-nodes\fP. .sp Salt uses specific data from the external node classifier. In particular the classes value denotes which sls modules to run, and the environment value sets to another environment. .sp An external node classification can be set in the master configuration file via the \fBexternal_nodes\fP option: \fI\%http://salt.readthedocs.org/en/latest/ref/configuration/master.html#external-nodes\fP .sp External nodes are loaded in addition to the top files. If it is intended to only use external nodes, do not deploy any top files. .SS State Mod Init System .sp An issue arose with the pkg state. Every time a package was run Salt would need to refresh the package database. This made systems with slower package metadata refresh speeds much slower to work with. To alleviate this issue the \fBmod_init\fP interface has been added to salt states. .sp The \fBmod_init\fP interface is a function that can be added to a state file. This function is called with the first state called. In the case of the pkg state, the \fBmod_init\fP function sets up a tag which makes the package database only refresh on the first attempt to install a package. .sp In a nutshell, the \fBmod_init\fP interface allows a state to run any command that only needs to be run once, or can be used to set up an environment for working with the state. .SS Source File Search Path .sp The file state continues to be refined, adding speed and capabilities. This release adds the ability to pass a list to the source option. This list is then iterated over until the source file is found, and the first found file is used. .sp The new syntax looks like this: .sp .nf .ft C /etc/httpd/conf/httpd.conf: file: \- managed \- source: \- salt://httpd/httpd.conf \- http://myserver/httpd.conf: md5=8c1fe119e6f1fd96bc06614473509bf1 .ft P .fi .sp The source option can take sources in the list from the salt file server as well as an arbitrary web source. If using an arbitrary web source the checksum needs to be passed as well for file verification. .SS Refinements to the Requisite System .sp A few discrepancies were still lingering in the requisite system, in particular, it was not possible to have a \fBrequire\fP and a \fBwatch\fP requisite declared in the same state declaration. .sp This issue has been alleviated, as well as making the requisite system run more quickly. .SS Initial Unit Testing Framework .sp Because of the module system, and the need to test real scenarios, the development of a viable unit testing system has been difficult, but unit testing has finally arrived. Only a small amount of unit testing coverage has been developed, much more coverage will be in place soon. .sp A huge thanks goes out to those who have helped with unit testing, and the contributions that have been made to get us where we are. Without these contributions unit tests would still be in the dark. .SS Compound Targets Expanded .sp Originally only support for \fBand\fP and \fBor\fP were available in the compound target. 0.9.7 adds the capability to negate compound targets with \fBnot\fP. .SS Nodegroups in the Top File .sp Previously the nodegroups defined in the master configuration file could not be used to match nodes for states. The nodegroups support has been expanded and the nodegroups defined in the master configuration can now be used to match minions in the top file. .SS Salt 0.9.8 Release Notes .sp Salt 0.9.8 is a big step forward, with many additions and enhancements, as well as a number of precursors to advanced future developments. .sp This version of Salt adds much more power to the command line, making the old hard timeout issues a thing of the past and adds keyword argument support. These additions are also available in the salt client api, making the available api tools much more powerful. .sp The new pillar system allows for data to be stored on the master and assigned to minions in a granular way similar to the state system. It also allows flexibility for users who want to keep data out of their state tree similar to \(aqexternal lookup\(aq functionality in other tools. .sp Additions to requisites making them much more powerful have been added and improved error checking for sls files in the state system. A new provider system has been added to allow for redirecting what modules run in the background for individual states. .sp Support for OpenSUSE has been added and support for Solaris has begun serious development. Windows support has been significantly enhanced as well. .sp The matcher and target systems have received a great deal of attention. The default behavior of grain matching has changed slightly to reflect the rest of salt and the compound matcher system has been refined. .sp A number of impressive features with keyword arguments have been added to both the cli and to the state system. This makes states much more powerful and flexible while maintaining the simple configuration everyone loves. .sp The new batch size capability allows for executions to be rolled through a group of targeted minions a percentage or specific number at a time. This was added to prevent the "thundering herd" problem when targeting large numbers of minions for things like service restarts or file downloads. .SS Upgrade Considerations .SS Upgrade Issues .sp There was a previously missed oversight which could cause a newer minion to crash an older master. That oversight has been resolved so the version incompatibility issue will no longer occur. When upgrading to 0.9.8 make sure to upgrade the master first, followed by the minions. .SS Debian/Ubuntu Packages .sp The original Debian/Ubuntu packages were called salt and included all salt applications. New packages in the ppa are split by function. If an old salt package is installed then it should be manually removed and the new split packages need to be freshly installed. .sp On the master: .sp .nf .ft C # apt\-get purge salt # apt\-get install salt\-{master,minion} .ft P .fi .sp On the minions: .sp .nf .ft C # apt\-get purge salt # apt\-get install salt\-minion .ft P .fi .sp And on any Syndics: .sp .nf .ft C # apt\-get install salt\-syndic .ft P .fi .sp The official salt stack ppa for Ubuntu is located at: \fI\%https://launchpad.net/~saltstack/+archive/salt\fP .SS Major Features .SS Pillar .sp \fBPillar\fP offers an interface to declare variable data on the master that is then assigned to the minions. The pillar data is made available to all modules, states, sls files etc. It is compiled on the master and is declared using the existing renderer system. This means that learning pillar should be fairly trivial to those already familiar with salt states. .SS CLI Additions .sp The \fBsalt\fP command has received a serious overhaul and is more powerful than ever. Data is returned to the terminal as it is received, and the salt command will now wait for all running minions to return data before stopping. This makes adding very large \fI\-\-timeout\fP arguments completely unnecessary and gets rid of long running operations returning empty \fB{}\fP when the timeout is exceeded. .sp When calling salt via sudo, the user originally running salt is saved to the log for auditing purposes. This makes it easy to see who ran what by just looking through the minion logs. .sp The \fIsalt\-key\fP command gained the \fI\-D\fP and \fI\-\-delete\-all\fP arguments for removing all keys. Be careful with this one! .SS Keyword Arguments and States .sp State modules now accept the \fB**kwargs\fP argument. This results in all data in a sls file assigned to a state will be made available to the state function. .sp This passes data in a transparent way back to the modules executing the logic. In particular, this allows adding arguments to the \fBpkg.install\fP module that enable more advanced and granular controls with respect to what the state is capable of. .sp An example of this along with the new debconf module for installing ldap client packages on Debian: .sp .nf .ft C ldap\-client\-packages: pkg: \- debconf: salt://debconf/ldap\-client.ans \- installed \- names: \- nslcd \- libpam\-ldapd \- libnss\-ldapd .ft P .fi .SS Keyword Arguments and the CLI .sp In the past it was required that all arguments be passed in the proper order to the \fIsalt\fP and \fIsalt\-call\fP commands. As of 0.9.8, keyword arguments can be passed in the form of \fBkwarg=argument\fP. .sp .nf .ft C # salt \-G \(aqtype:dev\(aq git.clone \e repository=https://github.com/saltstack/salt.git cwd=/tmp/salt user=jeff .ft P .fi .SS Matcher Refinements and Changes .sp A number of fixes and changes have been applied to the Matcher system. The most noteworthy is the change in the grain matcher. The grain matcher used a regular expression to match the passed data to a grain, but now defaults to a shell glob like the majority of match interfaces in Salt. A new option is available that still uses the old style regex matching to grain data called grain\-pcre. To use regex matching in compound matches use the letter \fIP\fP. .sp For example, this would match any ArchLinux or Fedora minions: .sp .nf .ft C # salt \-\-grain\-pcre \(aqos:(Arch:Fed).*\(aq test.ping .ft P .fi .sp And the associated compound matcher suitable for \fBtop.sls\fP is \fIP\fP: .sp .nf .ft C P@os:(Arch|Fed).* .ft P .fi .sp \fBNOTE\fP: Changing the grains matcher from pcre to glob is backwards incompatible. .sp Support has been added for matching minions with Yahoo\(aqs range library. This is handled by passing range syntax with \fI\-R\fP or \fI\-\-range\fP arguments to salt. .sp More information at: \fI\%https://github.com/grierj/range/wiki/Introduction-to-Range-with-YAML-files\fP .SS Providers .sp Salt predetermines what modules should be mapped to what uses based on the properties of a system. These determinations are generally made for modules that provide things like package and service management. The apt module maps to pkg on Debian and the yum module maps to pkg on Fedora for instance. .sp Sometimes in states, it may be necessary for a non\-default module to be used for the desired functionality. For instance, an Arch Linux system may have been set up with systemd support. Instead of using the default service module detected for Arch Linux, the systemd module can be used: .sp .nf .ft C http: service: \- running \- enable: True \- provider: systemd .ft P .fi .SS Requisite Glob Matching .sp Requisites can now be defined with glob expansion. This means that if there are many requisites, they can be defined on a single line. .sp To watch all files in a directory: .sp .nf .ft C http: service: \- running \- enable: True \- watch: \- file: /etc/http/conf.d/* .ft P .fi .sp This example will watch all defined files that match the glob \fB/etc/http/conf.d/*\fP .SS Batch Size .sp The new batch size option allows commands to be executed while maintaining that only so many hosts are executing the command at one time. This option can take a percentage or a finite number: .sp .nf .ft C salt \e* \-b 10 test.ping salt \-G \(aqos:RedHat\(aq \-\-batch\-size 25% apache.signal restart .ft P .fi .sp This will only run test.ping on 10 of the targeted minions at a time and then restart apache on 25% of the minions matching \fBos:RedHat\fP at a time and work through them all until the task is complete. This makes jobs like rolling web server restarts behind a load balancer or doing maintenance on BSD firewalls using carp much easier with salt. .SS Module Updates .sp This is a list of notable, but non\-exhaustive updates with new and existing modules. .sp Windows support has seen a flurry of support this release cycle. We\(aqve gained all new \fBfile\fP, \fBnetwork\fP, and \fBshadow\fP modules. Please note that these are still a work in progress. .sp For our ruby users, new \fBrvm\fP and \fBgem\fP modules have been added along with the \fBassociated\fP \fBstates\fP .sp The \fBvirt\fP module gained basic Xen support. .sp The \fByum\fP \fBpkg\fP modules gained Scientific Linux support. .sp The \fBpkg\fP module on Debian, Ubuntu, and derivatives force apt to run in a non\-interactive mode. This prevents issues when package installation waits for confirmation. .sp A \fBpkg\fP module for OpenSUSE\(aqs zypper was added. .sp The \fBservice\fP module on ubuntu natively supports upstart. .sp A new \fBdebconf\fP module was contributed by our community for more advanced control over deb package deployments on Debian based distributions. .sp The \fBmysql.user\fP state and \fBmysql\fP module gained a \fIpassword_hash\fP argument. .sp The \fBcmd\fP module and state gained a \fIshell\fP keyword argument for specifying a shell other than \fB/bin/sh\fP on Linux / Unix systems. .sp New \fBgit\fP and \fBmercurial\fP modules have been added for fans of distributed version control. .SS In Progress Development .SS Master Side State Compiling .sp While we feel strongly that the advantages gained with minion side state compiling are very critical, it does prevent certain features what may be desired. 0.9.8 has support for initial master side state compiling, but many more components still need to be developed, it is hoped that these can be finished for 0.9.9. .sp The goal is that states can be compiled on both the master and the minion allowing for compilation to be split between master and minion. Why will this be great? It will allow storing sensitive data on the master and sending it to some minions without all minions having access to it. This will be good for handling ssl certificates on front\-end web servers. .SS New File Client .sp The file client code has been re\-factored to allow local \fBsalt://\fP uris. This will eventually allow for running salt\(aqs configuration management via \fBsalt\-call state.highstate\fP to run without a salt\-minion daemon running. .SS Solaris Support .sp Salt 0.9.8 sees the introduction of basic Solaris support. The daemon runs well, but grains and more of the modules need updating and testing. .SS Windows Support .sp Salt states on windows are now much more viable thanks to contributions from our community! States for file, user, and group management are more fully fleshed out along with a network module. Windows users can also now manage registry entries using the new "reg" module. .SH AUTHOR Thomas S. Hatch <thatch@gmail.com> and many others, please see the Authors file .SH COPYRIGHT 2012, Thomas S. Hatch .\" Generated by docutils manpage writer. .\" .