diff --git a/doc/man/salt-call.1 b/doc/man/salt-call.1 index 792fe5975b6f..57db8150fe73 100644 --- a/doc/man/salt-call.1 +++ b/doc/man/salt-call.1 @@ -1,4 +1,4 @@ -.TH "SALT-CALL" "1" "May 11, 2012" "0.9.9" "Salt" +.TH "SALT-CALL" "1" "June 16, 2012" "0.10.0" "Salt" .SH NAME salt-call \- salt-call Documentation . @@ -28,7 +28,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. -.\" Man page generated from reStructeredText. +.\" Man page generated from reStructuredText. . .SH SYNOPSIS .sp @@ -46,7 +46,7 @@ Print a usage message briefly summarizing these command\-line options .INDENT 0.0 .TP .B \-g, \-\-grains -Return the information generated by the salt grains +Return the information generated by the Salt grains .UNINDENT .INDENT 0.0 .TP @@ -57,7 +57,7 @@ directories can be delimited by commas .INDENT 0.0 .TP .B \-d, \-\-doc -Return the documentation for the specified module of for all modules if +Return the documentation for the specified module or for all modules if none are specified .UNINDENT .INDENT 0.0 @@ -70,9 +70,9 @@ settings see the config file. Default: \fBinfo\fP. .INDENT 0.0 .TP .B \-\-raw\-out -Print the output from the salt command in raw python +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. +an executing Python script with eval. .UNINDENT .INDENT 0.0 .TP @@ -83,12 +83,12 @@ form the shell would. .INDENT 0.0 .TP .B \-\-yaml\-out -Print the output from the salt command in yaml. +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. +Print the output from the salt command in JSON. .UNINDENT .INDENT 0.0 .TP @@ -105,5 +105,4 @@ Thomas S. Hatch and many others, please see the Authors file .SH COPYRIGHT 2012, Thomas S. Hatch .\" Generated by docutils manpage writer. -.\" . diff --git a/doc/man/salt-cp.1 b/doc/man/salt-cp.1 index b947773847bd..16135db1be92 100644 --- a/doc/man/salt-cp.1 +++ b/doc/man/salt-cp.1 @@ -1,4 +1,4 @@ -.TH "SALT-CP" "1" "May 11, 2012" "0.9.9" "Salt" +.TH "SALT-CP" "1" "June 16, 2012" "0.10.0" "Salt" .SH NAME salt-cp \- salt-cp Documentation . @@ -28,7 +28,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. -.\" Man page generated from reStructeredText. +.\" Man page generated from reStructuredText. . .sp Copy a file to a set of systems @@ -45,7 +45,7 @@ salt\-cp \-G \(aqos:Arch.*\(aq [ options ] SOURCE DEST .fi .SH DESCRIPTION .sp -Salt copy copies a local file out to all of the salt minions matched by the +Salt copy copies a local file out to all of the Salt minions matched by the given target. .SH OPTIONS .INDENT 0.0 @@ -56,12 +56,12 @@ Print a usage message briefly summarizing these command\-line options .INDENT 0.0 .TP .B \-t TIMEOUT, \-\-timeout=TIMEOUT -The timeout in seconds to wait for replies from the salt minions. +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 +The target expression will be interpreted as a PCRE regular expression rather than a shell glob. .UNINDENT .INDENT 0.0 @@ -73,14 +73,14 @@ example: server1.foo.bar,server2.foo.bar,example7.quo.qux .INDENT 0.0 .TP .B \-G, \-\-grain -The target expression matches values returned by the salt grains system on +The target expression matches values returned by the Salt grains system on the minions. The target expression is in the format of \(aq:\(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 target expression matches values returned by the Salt grains system on the minions. The target expression is in the format of \(aq:\(aq; example: \(aqos:Arch.*\(aq .UNINDENT @@ -106,7 +106,7 @@ make sure that the compound target is encapsulated in quotes. .INDENT 0.0 .TP .B \-c CONFIG, \-\-config=CONFIG -The location of the salt master configuration file, the salt master +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 @@ -120,5 +120,4 @@ Thomas S. Hatch and many others, please see the Authors file .SH COPYRIGHT 2012, Thomas S. Hatch .\" Generated by docutils manpage writer. -.\" . diff --git a/doc/man/salt-key.1 b/doc/man/salt-key.1 index 2cbceff0aa9c..d1e72056a91a 100644 --- a/doc/man/salt-key.1 +++ b/doc/man/salt-key.1 @@ -1,4 +1,4 @@ -.TH "SALT-KEY" "1" "May 11, 2012" "0.9.9" "Salt" +.TH "SALT-KEY" "1" "June 16, 2012" "0.10.0" "Salt" .SH NAME salt-key \- salt-key Documentation . @@ -28,7 +28,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. -.\" Man page generated from reStructeredText. +.\" Man page generated from reStructuredText. . .SH SYNOPSIS .sp @@ -96,5 +96,4 @@ Thomas S. Hatch and many others, please see the Authors file .SH COPYRIGHT 2012, Thomas S. Hatch .\" Generated by docutils manpage writer. -.\" . diff --git a/doc/man/salt-master.1 b/doc/man/salt-master.1 index 978c3ce18a2c..1c7e4389badc 100644 --- a/doc/man/salt-master.1 +++ b/doc/man/salt-master.1 @@ -1,4 +1,4 @@ -.TH "SALT-MASTER" "1" "May 11, 2012" "0.9.9" "Salt" +.TH "SALT-MASTER" "1" "June 16, 2012" "0.10.0" "Salt" .SH NAME salt-master \- salt-master Documentation . @@ -28,13 +28,13 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. -.\" Man page generated from reStructeredText. +.\" Man page generated from reStructuredText. . .sp The Salt master daemon, used to control the Salt minions .SH SYNOPSIS .sp -Salt\-master [ options ] +salt\-master [ options ] .SH DESCRIPTION .sp The master daemon controls the Salt minions @@ -81,5 +81,4 @@ Thomas S. Hatch and many others, please see the Authors file .SH COPYRIGHT 2012, Thomas S. Hatch .\" Generated by docutils manpage writer. -.\" . diff --git a/doc/man/salt-minion.1 b/doc/man/salt-minion.1 index 843b498ceb95..20f5d3eb4ccb 100644 --- a/doc/man/salt-minion.1 +++ b/doc/man/salt-minion.1 @@ -1,4 +1,4 @@ -.TH "SALT-MINION" "1" "May 11, 2012" "0.9.9" "Salt" +.TH "SALT-MINION" "1" "June 16, 2012" "0.10.0" "Salt" .SH NAME salt-minion \- salt-minion Documentation . @@ -28,7 +28,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. -.\" Man page generated from reStructeredText. +.\" Man page generated from reStructuredText. . .sp The Salt minion daemon, receives commands from a remote Salt master. @@ -82,5 +82,4 @@ Thomas S. Hatch and many others, please see the Authors file .SH COPYRIGHT 2012, Thomas S. Hatch .\" Generated by docutils manpage writer. -.\" . diff --git a/doc/man/salt-run.1 b/doc/man/salt-run.1 index 9ff23cec73f9..a5f594982241 100644 --- a/doc/man/salt-run.1 +++ b/doc/man/salt-run.1 @@ -1,4 +1,4 @@ -.TH "SALT-RUN" "1" "May 11, 2012" "0.9.9" "Salt" +.TH "SALT-RUN" "1" "June 16, 2012" "0.10.0" "Salt" .SH NAME salt-run \- salt-run Documentation . @@ -28,7 +28,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. -.\" Man page generated from reStructeredText. +.\" Man page generated from reStructuredText. . .sp Execute a Salt runner @@ -67,5 +67,4 @@ Thomas S. Hatch and many others, please see the Authors file .SH COPYRIGHT 2012, Thomas S. Hatch .\" Generated by docutils manpage writer. -.\" . diff --git a/doc/man/salt-syndic.1 b/doc/man/salt-syndic.1 index aac8a6dcbd56..9eb666458bac 100644 --- a/doc/man/salt-syndic.1 +++ b/doc/man/salt-syndic.1 @@ -1,4 +1,4 @@ -.TH "SALT-SYNDIC" "1" "May 11, 2012" "0.9.9" "Salt" +.TH "SALT-SYNDIC" "1" "June 16, 2012" "0.10.0" "Salt" .SH NAME salt-syndic \- salt-syndic Documentation . @@ -28,7 +28,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. -.\" Man page generated from reStructeredText. +.\" Man page generated from reStructuredText. . .sp The Salt syndic daemon, a special minion that passes through commands from a @@ -76,5 +76,4 @@ Thomas S. Hatch and many others, please see the Authors file .SH COPYRIGHT 2012, Thomas S. Hatch .\" Generated by docutils manpage writer. -.\" . diff --git a/doc/man/salt.1 b/doc/man/salt.1 index d4dce9899815..fa9c87a5709c 100644 --- a/doc/man/salt.1 +++ b/doc/man/salt.1 @@ -1,4 +1,4 @@ -.TH "SALT" "1" "May 11, 2012" "0.9.9" "Salt" +.TH "SALT" "1" "June 16, 2012" "0.10.0" "Salt" .SH NAME salt \- salt . @@ -28,7 +28,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. -.\" Man page generated from reStructeredText. +.\" Man page generated from reStructuredText. . .SH SYNOPSIS .INDENT 0.0 @@ -58,7 +58,7 @@ Print a usage message briefly summarizing these command\-line options .INDENT 0.0 .TP .B \-t TIMEOUT, \-\-timeout=TIMEOUT -The timeout in seconds to wait for replies from the salt minions. +The timeout in seconds to wait for replies from the Salt minions. .UNINDENT .INDENT 0.0 .TP @@ -79,7 +79,7 @@ minions to execute on. .INDENT 0.0 .TP .B \-\-version -Print the version of salt that is running. +Print the version of Salt that is running. .UNINDENT .INDENT 0.0 .TP @@ -96,7 +96,7 @@ example: server1.foo.bar,server2.foo.bar,example7.quo.qux .INDENT 0.0 .TP .B \-G, \-\-grain -The target expression matches values returned by the salt grains system on +The target expression matches values returned by the Salt grains system on the minions. The target expression is in the format of \(aq:\(aq; example: \(aqos:Arch*\(aq .sp @@ -107,7 +107,7 @@ the \-\-grain\-pcre option. .INDENT 0.0 .TP .B \-\-grain\-pcre -The target expression matches values returned by the salt grains system on +The target expression matches values returned by the Salt grains system on the minions. The target expression is in the format of \(aq:< regular expression>\(aq; example: \(aqos:Arch.*\(aq .UNINDENT @@ -128,7 +128,7 @@ Instead of using shell globs use the return code of a function. .INDENT 0.0 .TP .B \-N, \-\-nodegroup -Use a predefined compound target defined in the salt master configuration +Use a predefined compound target defined in the Salt master configuration file .UNINDENT .INDENT 0.0 @@ -152,7 +152,7 @@ but will be sent to the specified return system. .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 +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 @@ -161,16 +161,16 @@ previous function call: \-Q test.echo\(aq) .INDENT 0.0 .TP .B \-c CONFIG, \-\-config=CONFIG -The location of the salt master configuration file, the salt master +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 +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. +an executing Python script with eval. .UNINDENT .INDENT 0.0 .TP @@ -181,12 +181,12 @@ form the shell would. .INDENT 0.0 .TP .B \-\-yaml\-out -Print the output from the salt command in yaml. +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. +Print the output from the salt command in JSON. .UNINDENT .INDENT 0.0 .TP @@ -203,5 +203,4 @@ Thomas S. Hatch and many others, please see the Authors file .SH COPYRIGHT 2012, Thomas S. Hatch .\" Generated by docutils manpage writer. -.\" . diff --git a/doc/man/salt.7 b/doc/man/salt.7 index e6e4a07e7194..5eaac9ccd5d0 100644 --- a/doc/man/salt.7 +++ b/doc/man/salt.7 @@ -1,4 +1,4 @@ -.TH "SALT" "7" "May 11, 2012" "0.9.9" "Salt" +.TH "SALT" "7" "June 16, 2012" "0.10.0" "Salt" .SH NAME salt \- Salt Documentation . @@ -28,24 +28,24 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. -.\" Man page generated from reStructeredText. +.\" Man page generated from reStructuredText. . .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. +world of remote execution together and make them better, faster, and more +malleable. Salt accomplishes this through its ability to handle large loads of +information, and not just dozens but hundreds and even thousands of individual +servers quickly 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 +deployments across different 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. @@ -62,7 +62,7 @@ based on more than just hostname, but by system properties. 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 +public keys for authentication with the master daemon, then uses faster \fI\%AES\fP 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. @@ -235,7 +235,7 @@ configuration paths. .sp \fBInterface\fP .sp -By default the Salt master listens on ports 4505 and 4506 on all interfaces +By default the Salt master listens on TCP 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 @@ -248,7 +248,7 @@ By default the Salt master listens on ports 4505 and 4506 on all interfaces .sp \fBrc.conf\fP .sp -You\(aqll need to activate the Salt Master in your rc.conf file. Using your +You\(aqll need to activate the Salt Master in your \fIrc.conf\fP file. Using your favorite editor, open \fB/etc/rc.conf\fP and add the salt\-master. .sp .nf @@ -404,20 +404,161 @@ may either want to visit the section regarding Salt States, or the section on Modules. .SS Debian & Ubuntu .SS Ubuntu +.SS Installation +.sp +To install Salt on Ubuntu, use the following command: +.sp +.nf +.ft C +sudo apt\-get install python\-software\-properties +sudo add\-apt\-repository ppa:saltstack/salt +sudo apt\-get update +sudo apt\-get install salt\-master +sudo apt\-get install salt\-minion +.ft P +.fi +.IP "Installing on Ubuntu 11.04" +.sp +There is a conflict with \fImsgpack\-python\fP on Ubuntu 11.04 and the current +saltstack PPA. You can work around the conflict by installing +\fImsgpack\-python\fP from Oneiric: +.sp +.nf +.ft C +sudo add\-apt\-repository \(aqdeb http://us.archive.ubuntu.com/ubuntu/ oneiric universe\(aq +sudo add\-apt\-repository ppa:saltstack/salt +sudo apt\-get update +sudo apt\-get install msgpack\-python +sudo apt\-get install salt\-master +sudo apt\-get install salt\-minion +sudo add\-apt\-repository \-\-remove \(aqdeb http://us.archive.ubuntu.com/ubuntu/ oneiric universe\(aq +.ft P +.fi +.RE +.sp +After installation you\(aqll need to make a few changes to the configuration files. +.SS Configuration +.sp +To configure your Salt files we must modify both master and minion +configuration files. We need to set where the master binds, by default salt +listens on all interfaces. If you have a need to bind to a specific local IP, +make the change as needed. To edit the master type in the following command: +.sp +.nf +.ft C +sudo vim /etc/salt/master +.ft P +.fi +.sp +From here make the following changes: +.sp +.nf +.ft C +\- interface: 0.0.0.0 ++ interface: 192.168.0.10 +.ft P +.fi +.sp +To configure the minion type in the following command: +.sp +.nf +.ft C +sudo vim /etc/salt/minion +.ft P +.fi +.sp +Once inside the editor make the following changes: +.sp +.nf +.ft C +\- master: salt ++ master: 192.168.0.10 +.ft P +.fi +.sp +After making the following changes you need to restart both the master and the +minion. To do so type in the following commands: +.sp +.nf +.ft C +sudo /etc/init.d/salt\-master restart +sudo /etc/inti.d/salt\-minion restart +.ft P +.fi +.SS Test +.sp +To test Salt we must first sign the key of the minion to the master. To see the +pending keys type in the following command: +.sp +.nf +.ft C +sudo salt\-key \-L +.ft P +.fi +.sp +From here you will should see a key name underneath the Unaccepted Keys +portion. To sign the minion key to the master type in the following command: +.sp +.nf +.ft C +sudo salt\-key \-a $minion +.ft P +.fi +.sp +Where \fB$minion\fP is the unaccepted key. +.sp +Now that you have signed the key we need to see if the key was accepted and +that we can ping the minion and get a response. To do this you can type in one +of the previous commands \fBsudo salt\-key \-L\fP and see if the key has been +accepted, then also ping the minion to see if it\(aqs working by typing in the +following command: +.sp +.nf +.ft C +sudo salt \e* test.ping +.ft P +.fi +.sp +If it is working properly you should see this result: +.sp +.nf +.ft C +{\(aq$minion\(aq: True} +.ft P +.fi +.SS Troubleshooting .sp -We are working to get Salt into apt. In the meantime we have a PPA available -for Lucid: +To see if the Salt master is running properly type in the following command: .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 +netstat \-natp | grep 450 .ft P .fi +.sp +This should return \fB192.168.0.10:4505\fP and \fB192.168.0.10:4506\fP if the master was +configured properly. If this does not return those values recheck your master +and minion config files for mistakes. +.sp +To see if both master and minion are running properly type in the following +command: +.sp +.nf +.ft C +ps \-efH | grep sal[t] +.ft P +.fi +.sp +This should return 8 Salt masters and 1 Salt minion if both are configured +properly. If you are still having issues with your Salt configuration please +reference the trouble shooting page \fBTroubleshooting\fP. +.SS What Now? +.sp +Congratulations you have just successfully installed Salt on your Ubuntu machine +and configured both the master and the minion. From this point you are now +able to send remote commands. 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 .sp \fI\%A deb package is currently in testing\fP for inclusion in apt. Until that is @@ -438,7 +579,7 @@ pip install pyzmq salt .SS Fedora & CentOS / Enterprise Linux .sp Beginning with version 0.9.4, Salt has been available in the primary Fedora -repositories and EPEL. It is installable using yum. Fedora will have more +repositories and \fI\%EPEL\fP. It is installable 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 / RHEL 5" @@ -485,7 +626,7 @@ configuration paths. .sp \fBInterface\fP .sp -By default the Salt master listens on ports \fB4505\fP and \fB4506\fP on all interfaces +By default the Salt master listens on TCP ports \fB4505\fP and \fB4506\fP 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 @@ -498,7 +639,7 @@ By default the Salt master listens on ports \fB4505\fP and \fB4506\fP on all int .sp \fBEnable the Master\fP .sp -You\(aqll also likely want to activate the Salt Master in systemd, configuring the +You\(aqll also likely want to activate the Salt Master in \fIsystemd\fP, configuring the Salt Master to start automatically at boot. .sp .nf @@ -792,7 +933,7 @@ file. Using your favorite editor open \fB/etc/rc.conf\fP or .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 +Minion. The Salt port installs an \fIrc\fP 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 @@ -922,7 +1063,7 @@ Work is under way to create a Windows installer for Salt, but for now one must install each dependency separately and configure Salt to run on your Windows host. .sp -Rather than send you on a wild goose chase across the internet, we\(aqve +Rather than send you on a wild goose chase across the Internet, we\(aqve collected some of the more difficult to find installers in our github repo for you. .SS Install on Windows XP 32bit .INDENT 0.0 @@ -987,7 +1128,7 @@ python get\-pip.py .IP 13. 4 Add c:\epython27\escripts to your path .IP 14. 4 -Close terminal window and open a new terminal window (cmd) +Close terminal window and open a new terminal window (\fIcmd\fP) .IP 15. 4 Install jinja2 .UNINDENT @@ -1154,7 +1295,7 @@ 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: +List the accepted and unaccepted Salt keys: .sp .nf .ft C @@ -1195,7 +1336,7 @@ 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 +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 @@ -1228,7 +1369,7 @@ the minion was a new host. .RE .SS Globbing .sp -The default matching that Salt utilizes is shell\-style globbing around the +The default matching that Salt utilizes is \fI\%shell-style globbing\fP 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 @@ -1276,9 +1417,9 @@ Match the \fBweb\-x\fP, \fBweb\-y\fP, and \fBweb\-z\fP minions: salt \(aqweb\-[x\-z]\(aq test.ping .ft P .fi -.SS Regex +.SS Regular Expressions .sp -Minions can be matched using Perl\-compatible regular expressions (which is +Minions can be matched using Perl\-compatible \fI\%regular expressions\fP (which is globbing on steroids and a ton of caffeine). .sp Match both \fBweb1\-prod\fP and \fBweb1\-devel\fP minions: @@ -1289,8 +1430,8 @@ 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 +When using regular expressions in a State\(aqs \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 @@ -1303,7 +1444,7 @@ base: .fi .SS Lists .sp -At the most basic you can specify a flat list of minion ids: +At the most basic level, you can specify a flat list of minion IDs: .sp .nf .ft C @@ -1334,7 +1475,7 @@ salt \-G \(aqos:CentOS\(aq test.ping .ft P .fi .sp -Match all minions with 64 bit CPUs and return number of available cores: +Match all minions with 64\-bit CPUs and return number of available cores: .sp .nf .ft C @@ -1359,25 +1500,25 @@ grains: .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 +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 +the grains must return a Python \fI\%dict\fP, 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 +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: +the Salt minion and provides the principal example of how to write grains: .sp -\fI\%https://github.com/saltstack/salt/blob/v0.9.9/salt/grains/core.py\fP +\fI\%https://github.com/saltstack/salt/blob/v0.10.0/salt/grains/core.py\fP .SS Syncing Grains .sp Syncing grains can be done a number of ways, they are automatically synced when @@ -1388,7 +1529,7 @@ the saltutil.sync_grains or saltutil.sync_all functions. .TP .B Node group A predefined group of minions declared in the master configuration file -\fBnodegroups\fP setting as a \fIcompound target\fP. +\fBnodegroups\fP setting as a compound target. .UNINDENT .sp For example, in the master config file \fBnodegroups\fP setting: @@ -1428,7 +1569,7 @@ 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. For +previously discussed matchers. The default matcher is a \fI\%glob\fP, as usual. For matching via anything other than glob, preface it with the letter denoting the match type. The currently implemented "letters" are: .TS @@ -1462,7 +1603,7 @@ _ T{ P T} T{ -Grains pcre match +Grains PCRE match T} T{ \fBP@os:(RedHat|Fedora|CentOS)\fP T} @@ -1475,13 +1616,21 @@ T} T{ \fBL@minion1.example.com,minion3.domain.com and bl*.domain.com\fP T} _ +T{ +I +T} T{ +Pillar glob match +T} T{ +\fBI@pdata:foobar\fP +T} +_ .TE .sp 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 +minions that have a hostname that matches the \fI\%regular expression\fP \fBweb\-dc1\-srv.*\fP: .sp .nf @@ -1500,7 +1649,35 @@ base: \- webserver .ft P .fi +.SS Batch Size +.sp +The 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. +.sp +The batch system maintains a window of running minions, so, if there are a +total of 150 minions targeted and the batch size is 10, then the command is +sent to 10 minions, when one minion returns then the command is sent to one +additional minion, so that the job is constantly running on 10 minions. .SH REMOTE EXECUTION TUTORIAL +.INDENT 0.0 +.TP +.B orphan +.UNINDENT .sp \fBBefore continuing\fP make sure you have a working Salt installation by following the \fI\%installation\fP and the \fBconfiguration\fP instructions. @@ -1528,7 +1705,7 @@ salt \(aq\(aq [arguments] .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.: +following function. The default filter is a glob on the minion id. For example: .sp .nf .ft C @@ -1537,7 +1714,7 @@ salt \(aq*.example.org\(aq test.ping .ft P .fi .sp -Targets can be based on minion system information using the grains system: +Targets can be based on minion system information using the Grains system: .sp .nf .ft C @@ -1623,18 +1800,18 @@ 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. +SLS files are therefore, in reality, just \fI\%dictionaries\fP, \fI\%lists\fP, +\fI\%strings\fP, and \fI\%numbers\fP. 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. +serialization formats available \- \fI\%YAML\fP. .sp A typical SLS file will often look like this in YAML: .sp @@ -1670,8 +1847,8 @@ 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, +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 @@ -1713,9 +1890,9 @@ 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 +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 +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 @@ -1735,10 +1912,10 @@ 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. +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 +The Apache example would be laid out in the root of the Salt file server like this: .sp .nf @@ -1752,7 +1929,7 @@ 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: +toolkit, consider this SSH example: .sp \fB/ssh/init.sls:\fP .sp @@ -1895,26 +2072,26 @@ 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 +\fByaml_jinja\fP renderer will first pass the template through the \fI\%Jinja2\fP 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 +Other renderers available are \fByaml_mako\fP which uses the \fI\%Mako\fP 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 +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: +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: +the case of templating engine based renderers, three critical components are +available, \fBsalt\fP, \fBgrains\fP, and \fBpillar\fP. The \fBsalt\fP object allows for +any Salt function to be called from within the template, and \fBgrains\fP allows for +the Grains to be accessed from within the template. A few examples: .sp \fB/apache/init.sls:\fP .sp @@ -1960,7 +2137,7 @@ the grains to be accessed from within the template. A few examples: .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. +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: @@ -2034,11 +2211,11 @@ 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, +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: +This example shows a very basic Python SLS file: .sp \fB/python/django.sls:\fP .sp @@ -2061,7 +2238,7 @@ 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: +This Python example would look like this if it were written in YAML: .sp .nf .ft C @@ -2076,7 +2253,7 @@ This python example would look like this if it were written in YAML: .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. +needed by using a pure Python SLS. .sp Now onto the \fBStates tutorial, part 1\fP. .SH STATES TUTORIAL, PART 1 @@ -2087,6 +2264,10 @@ 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. +.INDENT 0.0 +.TP +.B orphan +.UNINDENT .sp \fBBefore continuing\fP make sure you have a working Salt installation by following the \fI\%installation\fP and the \fBconfiguration\fP instructions. @@ -2128,8 +2309,9 @@ Restart the Salt master in order to pick up this change: .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: +On the master in the directory you uncommented in the previous step +(\fB/srv/salt\fP by default), create a new file called +\fBtop.sls\fP and add the following: .sp .nf .ft C @@ -2159,7 +2341,7 @@ base: .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 +\fISLS module\fP, named \fBwebserver.sls\fP. Type the following and save the file: .sp .nf @@ -2287,7 +2469,7 @@ 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 +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 @@ -2646,7 +2828,7 @@ refer to the master only.\fP .RE .SS iptables .sp -Different Linux distributions store their iptables rules in different places, +Different Linux distributions store their \fI\%iptables\fP 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 @@ -2694,7 +2876,7 @@ ports=4505,4506/tcp .fi .SS pf.conf .sp -The BSD\-family of operating systems uses packet filter (pf). The following +The BSD\-family of operating systems uses \fI\%packet filter (pf)\fP. The following example describes the additions to \fBpf.conf\fP needed to access the Salt master. .sp @@ -2713,15 +2895,15 @@ new rules with the new additions. This can be done using the \fBpfctl\fP command pfctl \-vf /etc/pf.conf .ft P .fi -.SH BOOSTRAPPING SALT ON LINUX EC2 WITH CLOUD-INIT +.SH BOOTSTRAPPING 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. +custom \fI\%AMI\fP, 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 +during an \fI\%EC2 Instance\fP 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 @@ -2753,7 +2935,7 @@ salt\-minion \-d 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. +that resolves to your Salt master. .SS Used With Boto .sp \fI\%Boto\fP will accept a string for user data @@ -2775,16 +2957,17 @@ reservation = conn.run_instances(image_id=, .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. +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 +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 +Pillar is an interface for Salt designed to offer global values that can be distributed to all minions. Pillar data is managed in a similar way to -the salt state tree. +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 @@ -2796,8 +2979,8 @@ 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: +The configuration for the \fBpillar_roots\fP in the master config is identical in +behavior and function as the \fBfile_roots\fP configuration: .sp .nf .ft C @@ -2808,19 +2991,27 @@ pillar_roots: .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: +in the \fB/srv/pillar\fP directory. The top file used matches the name of the top file +used for States, and has the same structure: +.sp +\fB/srv/pillar/top.sls\fP .sp .nf .ft C base: \(aq*\(aq: \- packages + \(aqsomeminion\(aq: + \- someminion\-specials .ft P .fi .sp This simple pillar top file declares that information for all minions can be -found in the package\(aqs sls file: +found in the \fBpackages.sls\fP file [1], while +\fBsomeminion\-specials.sls\fP contains overriding or additional information just +for one special minion. +.sp +\fB/srv/pillar/packages.sls\fP .sp .nf .ft C @@ -2831,11 +3022,20 @@ git: git apache: apache2 git: git\-core {% endif %} +somekey: globalvalue +.ft P +.fi +.sp +\fB/srv/pillar/someminion\-specials.sls\fP +.sp +.nf +.ft C +somekey: specialvalue .ft P .fi .sp -Now this data can be used from within modules, renderers, state sls files and -more via the shared pillar dict: +Now this data can be used from within modules, renderers, State SLS files, and +more via the shared pillar \fI\%dict\fP: .sp .nf .ft C @@ -2854,6 +3054,44 @@ git: \- name: {{ pillar[\(aqgit\(aq] }} .ft P .fi +.sp +To use pillar data in a file that is managed on a minion, use a file state like +this: +.sp +\fB/srv/salt/top.sls\fP +.sp +.nf +.ft C +base: + \(aq*\(aq: + \- managed_files +.ft P +.fi +.sp +\fB/srv/salt/managed_files.sls\fP +.sp +.nf +.ft C +/tmp/some\-managed\-file.txt: + file: + \- managed + \- template: jinja + \- source: salt://files/some\-managed\-file.txt +.ft P +.fi +.sp +\fB/srv/salt/files/some\-managed\-file.txt\fP +.sp +.nf +.ft C +This will yield \(aqglobalvalue\(aq on all minions but will yield \(aqspecialvalue\(aq +on \(aqsomeminion\(aq: +somekey has value: {{ pillar[\(aqsomekey\(aq] }} +.ft P +.fi +.SS Footnotes +.IP [1] 5 +Note that you cannot just list key/value\-information in \fBtop.sls\fP. .SS Refreshing Pillar Data .sp When pillar data is changed on the master the minions need to refresh the data @@ -2864,20 +3102,30 @@ locally. This is done with the \fBsaltutil.refresh_pillar\fP function. salt \(aq*\(aq saltutil.refresh_pillar .ft P .fi +.SS Targeting with Pillar +.sp +Pillar data can be used when targeting minions. This allows for ultimate +control and flexibility when targeting minions. +.sp +.nf +.ft C +salt \-I \(aqsomekey:specialvalue\(aq test.ping +.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 +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 Salt Minions now maintain a \fIproc\fP directory in the Salt cachedir, the \fIproc\fP +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. +jobs to be looked up. This is located in the \fIproc\fP directory under the +cachedir, with a default configuration it is under \fI/var/cache/salt/proc\fP. .SS Functions in the saltutil Module .sp Salt 0.9.7 introduced a few new functions to the @@ -2886,7 +3134,7 @@ 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. +Returns the data of all running jobs that are found in the \fIproc\fP directory. .IP 2. 3 \fBfind_job\fP Returns specific data about a certain job based on job id. @@ -2918,6 +3166,12 @@ 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. +.sp +.nf +.ft C +# salt\-run jobs.active +.ft P +.fi .SS lookup_jid .sp When jobs are executed the return data is sent back to the master and cached. @@ -2925,16 +3179,47 @@ 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. +.sp +.nf +.ft C +# salt\-run jobs.lookup_jid +.ft P +.fi .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. +.sp +.nf +.ft C +# salt\-run jobs.list_jobs +.ft P +.fi +.SH RUNNING THE SALT MASTER AS UNPRIVILEGED USER +.sp +While the default setup runs the Salt Master as the root user, it is generally +wise to run servers as an unprivileged user. In Salt 0.9.10 the management +of the running user was greatly improved, the only change needed is to alter +the option \fBuser\fP in the master configuration file and all salt system +components will be updated to function under the new user when the master +is started. +.sp +If running a version older that 0.9.10 then a number of files need to be +owned by the user intended to run the master: +.sp +.nf +.ft C +# chown \-R /var/cache/salt +# chown \-R /var/log/salt +# chown \-R /etc/salt/pki +.ft P +.fi .SH TROUBLESHOOTING .sp -The intent of the troubleshooting section is to introduce solutions to a +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. +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 @@ -2948,13 +3233,13 @@ master in the foreground: .ft P .fi .sp -Anyone wanting to run salt daemons via a process supervisor such as monit, -runit, or supervisord, should omit the \fB\-d\fP argument to the daemons and +Anyone wanting to run Salt daemons via a process supervisor such as \fI\%monit\fP, +\fI\%runit\fP, or \fI\%supervisord\fP, should omit the \fB\-d\fP argument to the daemons and run them in the foreground. .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 +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 both your Salt master and minion in debug mode and don\(aqt see an acknowledgement that your minion has connected, it could very well be a firewall. .sp @@ -2970,20 +3255,21 @@ You can check port connectivity from the minion with the nc command: There is also a \fBfirewall configuration\fP document that might help as well. .sp -If you\(aqve enabled the right ports on your operating system or Linux +If you\(aqve enabled the right TCP ports on your operating system or Linux distribution\(aqs firewall and still aren\(aqt seeing connections, check that no -additional access control such as SELinux or AppArmor are blocking salt. +additional access control system such as \fI\%SELinux\fP or \fI\%AppArmor\fP is blocking +Salt. .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 running any -salt module locally on a minion. These range from the original intent of -salt\-call, development assistance, to gathering more verbose output from 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. For even more +of new Salt modules. Since then, many applications have been developed for +running any Salt module locally on a minion. These range from the original +intent of salt\-call, development assistance, to gathering more verbose output +from calls like \fBstate.highstate\fP. +.sp +When developing the State Tree it is generally recommended to invoke +state.highstate with salt\-call. This displays far more information +about the highstate execution than calling it remotely. For even more verbosity, increase the loglevel with the same argument as \fBsalt\-minion\fP: .sp .nf @@ -2994,7 +3280,7 @@ salt\-call \-l debug state.highstate .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 +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 @@ -3022,10 +3308,10 @@ and activated upon new a login of the specified user. 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 +There are known bugs with ZeroMQ versions less than 2.1.11 which can cause the +Salt master to not respond properly. If you\(aqre running a ZeroMQ version 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: @@ -3039,7 +3325,7 @@ You can do it manually with something like: .ft P .fi .sp -Or with the following salt state: +Or with the following Salt state: .sp .nf .ft C @@ -3064,43 +3350,66 @@ net.ipv4.tcp_wmem: \- value: 4096 87380 16777216 .ft P .fi +.SS Salt and SELinux +.sp +Currently there are no SELinux policies for Salt. For the most part Salt runs +without issue when SELinux is running in Enforcing mode. This is because when +the minion executes as a daemon the type context is changed to \fBinitrc_t\fP. +The problem with SELinux arises when using salt\-call or running the minion in +the foreground, since the type context stays \fBunconfined_t\fP. +.sp +This problem is generally manifest in the rpm install scripts when using the +pkg module. Until a full SELinux Policy is available for Salt the solution +to this issue is to set the execution context of \fBsalt\-call\fP and +\fBsalt\-minion\fP to rpm_exec_t: +.sp +.nf +.ft C +# chcon \-t system_u:system_r:rpm_exec_t:s0 /usr/bin/salt\-minion +# chcon \-t system_u:system_r:rpm_exec_t:s0 /usr/bin/salt\-call +.ft P +.fi +.sp +This works well, because the \fBrpm_exec_t\fP context has very broad control over +other types. .SS Red Hat Enterprise Linux 5 .sp -Salt requires Python 2.6 or 2.7. RHEL 5 and variants come with python 2.4 by -default, when installing on RHEL 5 from the EPEL repository this is handled -for you. But if running Salt from git, be advised that the deps needs to be -installed from EPEL and salt needs to be run with the \fBpython26\fP executable. +Salt requires Python 2.6 or 2.7. Red Hat Enterprise Linux 5 and its variants +come with Python 2.4 installed by default. When installing on RHEL 5 from the +\fI\%EPEL repository\fP this is handled for you. But, if you run Salt from git, be +advised that its dependencies need to be installed from EPEL and that Salt +needs to be run with the \fBpython26\fP executable. .SS Common YAML Gotchas .sp An extensive list of -\fByaml idiosyncrasies\fP +\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 +representing SLS data, can also backfire. \fI\%YAML\fP 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 +\fI\%YAML uses spaces\fP, 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 +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: +When \fI\%dicts\fP: 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 @@ -3144,7 +3453,10 @@ is not desirable, then a deeply nested dict can be declared with curly braces: .fi .SS Integers are Parsed as Integers .sp -When passing integers into an sls file, they are passed as integers. This means +NOTE: This has been fixed in salt 0.9.10, as of this release passing an +integer that is preceded by a 0 will be correctly parsed +.sp +When passing \fI\%integers\fP 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 @@ -3178,9 +3490,9 @@ preceded by a 0 then it needs to be passed as a string: \- mode: \(aq0644\(aq .ft P .fi -.SS Yaml does not like "Double Short Decs" +.SS YAML does not like "Double Short Decs" .sp -If I can find a way to make yaml accept "Double Short Decs" then I will, since +If I can find a way to make YAML accept "Double Short Decs" then I will, since I think that double short decs would be awesome. So what is a "Double Short Dec"? It is when you declare a multiple short decs in one ID. Here is a standard short dec, it works great: @@ -3195,7 +3507,7 @@ vim: The short dec means that there are no arguments to pass, so it is not required to add any arguments, and it can save space. .sp -Yaml though, gets upset when declaring multiple short decs, for the record... +YAML though, gets upset when declaring multiple short decs, for the record... .sp THIS DOES NOT WORK: .sp @@ -3256,7 +3568,7 @@ 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 +\fI\%https://groups.google.com/forum/#!forum/salt-users\fP .SS IRC .sp The \fB#salt\fP IRC channel is hosted on the popular \fI\%Freenode\fP network. You @@ -3280,8 +3592,17 @@ News and thoughts on Salt and related projects is often posted on Thomas\(aq blo 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: +A few examples of salt states from the community: +.INDENT 0.0 +.IP \(bu 2 \fI\%https://github.com/blast-hardcheese/blast-salt-states\fP +.IP \(bu 2 +\fI\%https://github.com/kevingranade/kevingranade-salt-state\fP +.IP \(bu 2 +\fI\%https://github.com/uggedal/states\fP +.IP \(bu 2 +\fI\%https://github.com/mattmcclean/salt-openstack/tree/master/salt\fP +.UNINDENT .SS Follow on ohloh .sp \fI\%https://www.ohloh.net/p/salt\fP @@ -3306,6 +3627,161 @@ fork, commit your changes to the fork, and then open up a pull request. 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! +.sp +The \fI\%Open Comparison Contributing Docs\fP has some good suggestions and tips for +those who are looking forward to contribute. +.SH STANDALONE MINION +.sp +Since the Salt minion contains such extensive functionality it can be useful +to run it standalone. A standalone minion can be used to do a number of +things: +.INDENT 0.0 +.IP \(bu 2 +Stand up a master server via States (Salting a Salt Master) +.IP \(bu 2 +Use salt\-call commands on a system without connectivity to a master +.IP \(bu 2 +Masterless States, run states entirely from files local to the minion +.UNINDENT +.SS Telling Salt Call to Run Masterless +.sp +The salt\-call command is used to run module functions locally on a minion +instead of executing them from the master. Normally the salt\-call command +checks into the master to retrieve file server and pillar data, but when running +standalone salt\-call needs to be instructed to not check the master for this +data. To instruct the minion to not look for a master when running salt\-call +the \fBfile_client\fP configuration option needs to be set. By default the +\fBfile_client\fP is set to \fBremote\fP so that the minion knows that file server +and pillar data are to be gathered from the master. When setting the +\fBfile_client\fP option to \fBlocal\fP the minion is configured to not gather +this data from the master. +.sp +.nf +.ft C +file_client: local +.ft P +.fi +.sp +Now the salt\-call command will not look for a master and will assume that the +local system has all of the file ad pillar resources. +.SS Running States Masterless +.sp +The state system can be easily run without a Salt master, with all needed files +local to the minion. To do this the minion configuration file needs to be set +up to know how to return file_roots information like the master. The file_roots +setting defaults to /srv/salt for the base environment just like on the master: +.sp +.nf +.ft C +file_roots: + base: + \- /srv/salt +.ft P +.fi +.sp +Now set up the Salt State Tree, top file, and SLS modules in the same way that +they would be set up on a master. Now, with the \fBfile_client\fP option set to +\fBlocal\fP and an available state tree then calls to functions in the state +module will use the information in the file_roots on the minion instead of +checking in with the master. +.sp +Remember that when creating a state tree on a minion there are no syntax or +path changes needed, SLS modules written to be used from a master do not need +to be modified in any way to work with a minion. +.sp +This makes it easy to "script" deployments with Salt states without having to +set up a master, and allows for these SLS modules to be easily moved into a +Salt master as the deployment grows. +.SH SALT BASED PROJECTS +.sp +A number of unofficial open source projects, based on Salt, or written to +enhance Salt have been created. +.SS Salt Sandbox +.sp +Created by Aaron Bull Schaefer, aka "elasticdog". +.sp +\fI\%https://github.com/elasticdog/salt-sandbox\fP +.sp +Salt Sandbox is a multi\-VM Vagrant\-based Salt development environment used +for creating and testing new Salt state modules outside of your production +environment. It\(aqs also a great way to learn firsthand about Salt and its +remote execution capabilities. +.sp +Salt Sandbox will set up three separate virtual machines: +.INDENT 0.0 +.IP \(bu 2 +salt.example.com \- the Salt master server +.IP \(bu 2 +minion1.example.com \- the first Salt minion machine +.IP \(bu 2 +minion2.example.com \- the second Salt minion machine +.UNINDENT +.sp +These VMs can be used in conjunction to segregate and test your modules based +on node groups, top file environments, grain values, etc. You can even test +modules on different Linux distributions or release versions to better match +your production infrastructure. +.SH SALT EVENT SYSTEM +.sp +Salt 0.9.10 introduced the Salt Event System. This system is used to fire +off events enabling third party applications or external processes to react +to behavior within Salt. +.sp +The event system is comprised of a few components, the event sockets which +publish events, and the event library which can listen to events and send +events into the salt system. +.SS Listening for Events +.sp +The event system is accessed via the event library and can only be accessed +by the same system user that Salt is running as. To listen to events a +SaltEvent object needs to be created and then the get_event function needs to +be run. The SaltEvent object needs to know the location that the Salt unix +sockets are kept. In the configuration this is the \fBsock_dir\fP option. The +\fBsock_dir\fP option defaults to "/tmp/.salt\-unix" on most systems. +.sp +The following code will check for a single event: +.sp +.nf +.ft C +import salt.utils.event + +event = salt.utils.event.MasterEvent(\(aq/tmp/.salt\-unix\(aq) + +data = event.get_event() +.ft P +.fi +.sp +Events will also use a "tag". A "tag" allows for events to be filtered. By +default all events will be returned, but if only authentication events are +desired, then pass the tag "auth". Also, the get_event method has a default +poll time assigned of 5 seconds, to change this time set the "wait" option. +This example will only listen for auth events and will wait for 10 seconds +instead of the default 5. +.sp +.nf +.ft C +import salt.utils.event + +event = salt.utils.event.MasterEvent(\(aq/tmp/.salt\-unix\(aq) + +data = event.get_event(wait=10, tag=\(aqauth\(aq) +.ft P +.fi +.sp +Instead of looking for a single event, the iter_event method can be used to +make a generator which will continually yield salt events. The iter_event +method also accepts a tag, but not a wait time: +.sp +.nf +.ft C +import salt.utils.event + +event = salt.utils.event.MasterEvent(\(aq/tmp/.salt\-unix\(aq) + +for data in event.iter_event(tag=\(aqauth\(aq): + print(data) +.ft P +.fi .SH INTRODUCTION TO EXTENDING SALT .sp Salt is made to be used, and made to be extended. The primary goal of Salt is @@ -3318,13 +3794,13 @@ 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 +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 +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 @@ -3332,14 +3808,14 @@ 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 +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.9/salt/modules\fP +\fI\%https://github.com/saltstack/salt/blob/v0.10.0/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. +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 +\fImodules\fP directory and restarting the minion. .SS Grains .sp Salt grains, or "grains of truth" are bits of static information that are @@ -3348,11 +3824,11 @@ 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. +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.9/salt/grains\fP +\fI\%https://github.com/saltstack/salt/blob/v0.10.0/salt/grains\fP .SS States .sp Salt supports state enforcement, this makes Salt a high speed and very efficient @@ -3360,7 +3836,7 @@ 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.9/salt/states\fP +\fI\%https://github.com/saltstack/salt/blob/v0.10.0/salt/states\fP .SS Renderers .sp Salt states are controlled by simple data structures, these structures can be @@ -3371,27 +3847,27 @@ it. .sp The existing renderers can be found here: .sp -\fI\%https://github.com/saltstack/salt/blob/v0.9.9/salt/renderers\fP +\fI\%https://github.com/saltstack/salt/blob/v0.10.0/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 +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. +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.9/salt/returners\fP +\fI\%https://github.com/saltstack/salt/blob/v0.10.0/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 +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.9/salt/runners\fP +\fI\%https://github.com/saltstack/salt/blob/v0.10.0/salt/runners\fP .SH MODULES .sp Salt modules are the functions called by the \fBsalt\fP command. @@ -3403,14 +3879,14 @@ 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 +Salt modules are amazingly simple to write. Just write a regular Python module +or a regular \fI\%Cython\fP 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. +Since Salt modules are just Python/Cython modules, there are no restraints on +what you can put inside of a Salt module. If a Salt module has errors and +cannot be imported, the Salt minion will continue to load without issue and 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 @@ -3418,13 +3894,13 @@ 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 +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 that 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 +the Salt minion. This variable is a \fI\%Python dictionary\fP 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 @@ -3437,7 +3913,7 @@ def foo(bar): .ft P .fi .sp -This code will call the Salt cmd module\(aqs run function and pass the argument +This code will call the Salt cmd module\(aqs \fBrun\fP function and pass the argument \fBbar\fP. .SS Preloaded Modules Data .sp @@ -3450,13 +3926,13 @@ system and from the minion configuration file. .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 +and operating system. 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 Salt 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 values detected by the Salt Grains on the minion are available in a \fI\%dict\fP +named \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 @@ -3477,7 +3953,7 @@ 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 +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 @@ -3513,24 +3989,24 @@ This will ensure that the text outputter is used. .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 +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 +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 +The \fB__virtual__\fP function is used to return either a \fI\%string\fP or \fI\%False\fP. 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 +This means that the package manager modules can be presented as the \fBpkg\fP 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.9/salt/modules/pacman.py\fP -\fI\%https://github.com/saltstack/salt/blob/v0.9.9/salt/modules/yumpkg.py\fP -\fI\%https://github.com/saltstack/salt/blob/v0.9.9/salt/modules/apt.py\fP +\fI\%https://github.com/saltstack/salt/blob/v0.10.0/salt/modules/pacman.py\fP +\fI\%https://github.com/saltstack/salt/blob/v0.10.0/salt/modules/yumpkg.py\fP +\fI\%https://github.com/saltstack/salt/blob/v0.10.0/salt/modules/apt.py\fP .SS Documentation .sp Salt modules are self documenting, the \fBsys.doc()\fP function will return the @@ -3543,7 +4019,7 @@ salt \(aq*\(aq sys.doc .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 +writing Salt modules, please follow the formating conventions for docstrings as they appear in the other modules. .SS Adding Documentation to Salt Modules .sp @@ -3552,7 +4028,7 @@ 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. +Documenting Salt modules is easy! Just add a \fI\%Python docstring\fP to the function. .sp .nf .ft C @@ -3560,8 +4036,9 @@ def spam(eggs): \(aq\(aq\(aq A function to make some spam with eggs! - CLI Example: - salt \(aq*\(aq test.spam eggs + CLI Example:: + + salt \(aq*\(aq test.spam eggs \(aq\(aq\(aq return eggs .ft P @@ -3571,7 +4048,7 @@ 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 +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 @@ -3583,7 +4060,7 @@ def foo(bar): class baz: def __init__(self, quo): - return quo + pass .ft P .fi .SS Objects NOT Loaded into the Salt Minion @@ -3593,21 +4070,21 @@ class baz: def _foobar(baz): # Preceded with an _ return baz -cheese = {} # Not a callable python object +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 +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.9/salt/modules\fP +\fI\%https://github.com/saltstack/salt/blob/v0.10.0/salt/modules\fP .sp -The most simple module is the test module, it contains the simplest salt -function, test.ping: +The most simple module is the test module, it contains the simplest Salt +function, \fBtest.ping\fP: .sp .nf .ft C @@ -3616,8 +4093,9 @@ def ping(): Just used to make sure the minion is up and responding Return True - CLI Example: - salt \(aq*\(aq test.ping + CLI Example:: + + salt \(aq*\(aq test.ping \(aq\(aq\(aq return True .ft P @@ -3642,7 +4120,11 @@ def ping(): \fBsalt.modules.yumpkg5\fP .IP \(bu 2 \fBsalt.modules.zypper\fP -.UNINDENT +.IP \(bu 2 +\fBsalt.modules.brew\fP +.IP \(bu 2 +\fBsalt.modules.win_pkg\fP +.UNINDENT .SS salt.modules.sys .sp The regular salt modules execute in a separate context from the salt minion @@ -3682,6 +4164,12 @@ center; |l|l|. _ T{ +\fBaliases\fP +T} T{ +Manage the information in the aliases file +T} +_ +T{ \fBapache\fP T} T{ Support for Apache @@ -3700,6 +4188,11 @@ A module to wrap archive calls T} _ T{ +\fBbrew\fP +T} T{ +T} +_ +T{ \fBbutterkvm\fP T} T{ Specialized routines used by the butter cloud component @@ -3766,6 +4259,12 @@ Manage information about files on the minion, set/read user, group, and mode T} _ T{ +\fBfreebsdjail\fP +T} T{ +The jail module for FreeBSD +T} +_ +T{ \fBfreebsdkmod\fP T} T{ Module to manage FreeBSD kernel modules @@ -3814,6 +4313,12 @@ Manage groups on Linux T} _ T{ +\fBgrub\fP +T} T{ +Support for GRUB +T} +_ +T{ \fBhg\fP T} T{ Support for the Mercurial SCM @@ -3838,6 +4343,12 @@ Provide the hyper module for kvm hypervisors. T} _ T{ +\fBlaunchctl\fP +T} T{ +Module for the management of MacOS systems that use launchd/launchctl +T} +_ +T{ \fBlinux_sysctl\fP T} T{ Module for viewing and modifying sysctl parameters @@ -3880,6 +4391,12 @@ Support for nginx T} _ T{ +\fBosxdesktop\fP +T} T{ +Mac OS X implementations of various commands in the "desktop" interface +T} +_ +T{ \fBpacman\fP T} T{ A module to wrap pacman calls, since Arch is the best @@ -3898,6 +4415,12 @@ Install Python packages with pip to either the system or a virtualenv T} _ T{ +\fBpostgres\fP +T} T{ +Module to provide Postgres compatibility to salt. +T} +_ +T{ \fBps\fP T} T{ A salt interface to psutil, a system and process library. @@ -3918,7 +4441,7 @@ _ T{ \fBpw_group\fP T} T{ -Manage groups on Linux +Manage groups on FreeBSD T} _ T{ @@ -3928,6 +4451,18 @@ Manage users with the useradd command T} _ T{ +\fBrabbitmq_server\fP +T} T{ +Module to provide rabbitMQ compatibility to salt. +T} +_ +T{ +\fBreg\fP +T} T{ +Manage the registry on Windows +T} +_ +T{ \fBrh_ip\fP T} T{ The networking module for RHEL/Fedora based distros @@ -3976,6 +4511,12 @@ Apache Solr Salt Module T} _ T{ +\fBsqlite3\fP +T} T{ +Support for SQLite3 +T} +_ +T{ \fBssh\fP T} T{ Manage client ssh components @@ -4048,12 +4589,24 @@ Manage information about files on the minion, set/read user, group T} _ T{ +\fBwin_groupadd\fP +T} T{ +Manage groups on Windows +T} +_ +T{ \fBwin_network\fP T} T{ Module for gathering and managing network information T} _ T{ +\fBwin_pkg\fP +T} T{ +A module to manage software on Windows +T} +_ +T{ \fBwin_service\fP T} T{ Windows Service module. @@ -4090,6 +4643,82 @@ Package support for openSUSE via the zypper package manager T} _ .TE +.SS salt.modules.aliases +.sp +Manage the information in the aliases file +.INDENT 0.0 +.TP +.B salt.modules.aliases.get_target(alias) +Return the target associated with an alias +.sp +CLI Example: +.sp +.nf +.ft C +salt \(aq*\(aq aliases.get_target +.ft P +.fi +.UNINDENT +.INDENT 0.0 +.TP +.B salt.modules.aliases.has_target(alias, target) +Return true if the alias/target is set +.sp +CLI Example: +.sp +.nf +.ft C +salt \(aq*\(aq aliases.has_target +.ft P +.fi +.UNINDENT +.INDENT 0.0 +.TP +.B salt.modules.aliases.list_aliases() +Return the aliases found in the aliases file in this format: +.sp +.nf +.ft C +{\(aq\(aq: \(aq\(aq} +.ft P +.fi +.sp +CLI Example: +.sp +.nf +.ft C +salt \(aq*\(aq aliases.list_aliases +.ft P +.fi +.UNINDENT +.INDENT 0.0 +.TP +.B salt.modules.aliases.rm_alias(alias) +Remove an entry from the aliases file +.sp +CLI Example: +.sp +.nf +.ft C +salt \(aq*\(aq aliases.rm_alias +.ft P +.fi +.UNINDENT +.INDENT 0.0 +.TP +.B salt.modules.aliases.set_target(alias, target) +Set the entry in the aliases file for the given alias, this will overwrite +any previous entry for the given alias or create a new one if it does not +exist. +.sp +CLI Example: +.sp +.nf +.ft C +salt \(aq*\(aq aliases.set_target +.ft P +.fi +.UNINDENT .SS salt.modules.apache .sp Support for Apache @@ -4287,11 +4916,14 @@ salt \(aq*\(aq pkg.list_pkgs httpd .TP .B salt.modules.apt.list_upgrades() List all available package upgrades. -.INDENT 7.0 -.TP -.B CLI Example:: +.sp +CLI Example: +.sp +.nf +.ft C salt \(aq*\(aq pkg.list_upgrades -.UNINDENT +.ft P +.fi .UNINDENT .INDENT 0.0 .TP @@ -4347,7 +4979,7 @@ salt \(aq*\(aq pkg.remove .UNINDENT .INDENT 0.0 .TP -.B salt.modules.apt.upgrade(refresh=True) +.B salt.modules.apt.upgrade(refresh=True, **kwargs) Upgrades all packages via \fBapt\-get dist\-upgrade\fP .sp Returns a list of dicts containing the package names, and the new and old @@ -4495,6 +5127,107 @@ salt \(aq*\(aq archive.zip /tmp/zipfile.zip /tmp/sourcefile1 /tmp/sourcefile2 .ft P .fi .UNINDENT +.SS salt.modules.brew +.INDENT 0.0 +.TP +.B salt.modules.brew.install(pkgs) +Install the passed package(s) with \fBbrew install\fP +.INDENT 7.0 +.TP +.B pkgs +The names of the packages to be installed +.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 \(aqpackage package package\(aq +.ft P +.fi +.UNINDENT +.INDENT 0.0 +.TP +.B salt.modules.brew.list_pkgs(*args) +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.brew.list_upgrades() +Check whether or not an upgrade is available for all packages +.sp +CLI Example: +.sp +.nf +.ft C +salt \(aq*\(aq pkg.list_upgrades +.ft P +.fi +.UNINDENT +.INDENT 0.0 +.TP +.B salt.modules.brew.remove(pkgs) +Removes packages with \fBbrew uninstall\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.brew.upgrade_available(pkg) +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.brew.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.butterkvm .sp Specialized routines used by the butter cloud component @@ -4622,7 +5355,7 @@ salt \(aq*\(aq cmd.has_exec cat .UNINDENT .INDENT 0.0 .TP -.B salt.modules.cmdmod.retcode(cmd, cwd=None, runas=None, shell=\(aq/bin/sh\(aq, env=()) +.B salt.modules.cmdmod.retcode(cmd, cwd=None, runas=None, shell=\(aq/bin/bash\(aq, env=()) Execute a shell command and return the command\(aqs return code. .sp CLI Example: @@ -4635,7 +5368,7 @@ salt \(aq*\(aq cmd.retcode "file /bin/bash" .UNINDENT .INDENT 0.0 .TP -.B salt.modules.cmdmod.run(cmd, cwd=None, runas=None, shell=\(aq/bin/sh\(aq, env=()) +.B salt.modules.cmdmod.run(cmd, cwd=None, runas=None, shell=\(aq/bin/bash\(aq, env=()) Execute the passed command and return the output as a string .sp CLI Example: @@ -4648,7 +5381,7 @@ salt \(aq*\(aq cmd.run "ls \-l | awk \(aq/foo/{print $2}\(aq" .UNINDENT .INDENT 0.0 .TP -.B salt.modules.cmdmod.run_all(cmd, cwd=None, runas=None, shell=\(aq/bin/sh\(aq, env=()) +.B salt.modules.cmdmod.run_all(cmd, cwd=None, runas=None, shell=\(aq/bin/bash\(aq, env=()) Execute the passed command and return a dict of return data .sp CLI Example: @@ -4661,7 +5394,7 @@ salt \(aq*\(aq cmd.run_all "ls \-l | awk \(aq/foo/{print $2}\(aq" .UNINDENT .INDENT 0.0 .TP -.B salt.modules.cmdmod.run_stderr(cmd, cwd=None, runas=None, shell=\(aq/bin/sh\(aq, env=()) +.B salt.modules.cmdmod.run_stderr(cmd, cwd=None, runas=None, shell=\(aq/bin/bash\(aq, env=()) Execute a command and only return the standard error .sp CLI Example: @@ -4674,7 +5407,7 @@ salt \(aq*\(aq cmd.run_stderr "ls \-l | awk \(aq/foo/{print $2}\(aq" .UNINDENT .INDENT 0.0 .TP -.B salt.modules.cmdmod.run_stdout(cmd, cwd=None, runas=None, shell=\(aq/bin/sh\(aq, env=()) +.B salt.modules.cmdmod.run_stdout(cmd, cwd=None, runas=None, shell=\(aq/bin/bash\(aq, env=()) Execute a command, and only return the standard out .sp CLI Example: @@ -4716,7 +5449,7 @@ salt \(aq*\(aq cmd.which_bin \(aq[pip2, pip, pip\-python]\(aq Minion side functions for salt\-cp .INDENT 0.0 .TP -.B salt.modules.cp.cache_dir(path, env=\(aqbase\(aq) +.B salt.modules.cp.cache_dir(path, env=\(aqbase\(aq, include_empty=False) Download and cache everything under a directory from the master .sp CLI Example: @@ -4966,6 +5699,19 @@ salt \(aq*\(aq cron.rm_job root \e* \e* \e* \e* 1 /usr/local/weekly .UNINDENT .INDENT 0.0 .TP +.B salt.modules.cron.rm_env(user, name) +Remove cron environment variable for a specified user. +.sp +CLI Example: +.sp +.nf +.ft C +salt \(aq*\(aq cron.rm_env root MAILTO +.ft P +.fi +.UNINDENT +.INDENT 0.0 +.TP .B salt.modules.cron.rm_job(user, minute, hour, dom, month, dow, cmd) Remove a cron job for a specified user. .sp @@ -4979,6 +5725,19 @@ salt \(aq*\(aq cron.rm_job root \e* \e* \e* \e* 1 /usr/local/weekly .UNINDENT .INDENT 0.0 .TP +.B salt.modules.cron.set_env(user, name, value=None) +Set up an environment variable in the crontab. +.sp +CLI Example: +.sp +.nf +.ft C +salt \(aq*\(aq cron.set_env root MAILTO user@example.com +.ft P +.fi +.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. .sp @@ -5030,7 +5789,7 @@ CLI Example: .sp .nf .ft C -salt \(aq*\(aq data.dump \(aq{\(aqeggs\(aq: \(aqspam\(aq}\(aq +salt \(aq*\(aq data.dump \(aq{\(aqeggs\(aq: \(aqspam\(aq}\(aq .ft P .fi .UNINDENT @@ -5189,6 +5948,20 @@ salt \(aq*\(aq disk.usage Manage Django sites .INDENT 0.0 .TP +.B salt.modules.django.collectstatic(settings_module, bin_env=None, no_post_process=False, ignore=None, dry_run=False, clear=False, link=False, no_default_ignore=False, pythonpath=None) +Collect static files from each of your applications into a single location +that can easily be served in production. +.sp +CLI Example: +.sp +.nf +.ft C +salt \(aq*\(aq django.collectstatic settings.py +.ft P +.fi +.UNINDENT +.INDENT 0.0 +.TP .B salt.modules.django.command(settings_module, command, bin_env=None, pythonpath=None, *args, **kwargs) Run arbitrary django management command .UNINDENT @@ -5196,8 +5969,16 @@ Run arbitrary django management command .TP .B salt.modules.django.createsuperuser(settings_module, username, email, bin_env=None, database=None, pythonpath=None) Create a super user for the database. -this defaults to use the \fB\-\-noinput\fP flag which will -not create a password for the superuser. +This function defaults to use the \fB\-\-noinput\fP flag which prevents the +creation of a password for the superuser. +.sp +CLI Example: +.sp +.nf +.ft C +salt \(aq*\(aq django.createsuperuser settings.py user user@example.com +.ft P +.fi .UNINDENT .INDENT 0.0 .TP @@ -5208,19 +5989,35 @@ Load fixture data .B Fixtures: comma separated list of fixtures to load .UNINDENT +.sp +CLI Example: +.sp +.nf +.ft C +salt \(aq*\(aq django.loaddata settings.py +.ft P +.fi .UNINDENT .INDENT 0.0 .TP -.B salt.modules.django.syncdb(settings_module, bin_env=None, migrate=False, database=None, pythonpath=None) +.B salt.modules.django.syncdb(settings_module, bin_env=None, migrate=False, database=None, pythonpath=None, noinput=True) Run syncdb .sp -If you have south installed, you can pass in the optional -\fBmigrate\fP kwarg and run the migrations after the syncdb -finishes. -.UNINDENT -.SS salt.modules.ebuild +Execute the Django\-Admin syncdb command, if South is available on the +minion the \fBmigrate\fP option can be passed as \fBTrue\fP calling the +migrations to run after the syncdb completes .sp -Support for Portage +CLI Example: +.sp +.nf +.ft C +salt \(aq*\(aq django.syncdb settings.py +.ft P +.fi +.UNINDENT +.SS salt.modules.ebuild +.sp +Support for Portage .INDENT 0.0 .TP .B salt.modules.ebuild.available_version(name) @@ -5828,11 +6625,16 @@ Access time in Unix epoch time .TP .B mtime: Last modification in Unix epoch time -.TP -.B CLI Example:: -salt \(aq*\(aq file.touch /var/log/emptyfile .UNINDENT .sp +CLI Example: +.sp +.nf +.ft C +salt \(aq*\(aq file.touch /var/log/emptyfile +.ft P +.fi +.sp New in version 0.9.5. .UNINDENT .INDENT 0.0 @@ -5898,6 +6700,103 @@ salt \(aq*\(aq file.user_to_uid root .ft P .fi .UNINDENT +.SS salt.modules.freebsdjail +.sp +The jail module for FreeBSD +.INDENT 0.0 +.TP +.B salt.modules.freebsdjail.fstab(jail) +Display contents of a fstab(5) file defined in specified +jail\(aqs configuration. If no file defined return False. +.sp +CLI Example: +.sp +.nf +.ft C +salt \(aq*\(aq jail.fstab +.ft P +.fi +.UNINDENT +.INDENT 0.0 +.TP +.B salt.modules.freebsdjail.get_enabled() +Return which jails are set to be run +.UNINDENT +.INDENT 0.0 +.TP +.B salt.modules.freebsdjail.is_enabled() +See if jail service is actually enabled on boot +.UNINDENT +.INDENT 0.0 +.TP +.B salt.modules.freebsdjail.restart(jail=\(aq\(aq) +Restart the specified jail or all, if none specified +.sp +CLI Example: +.sp +.nf +.ft C +salt \(aq*\(aq jail.restart [] +.ft P +.fi +.UNINDENT +.INDENT 0.0 +.TP +.B salt.modules.freebsdjail.show_config(jail) +Display specified jail\(aqs configuration +.sp +CLI Example: +.sp +.nf +.ft C +salt \(aq*\(aq jail.show_config +.ft P +.fi +.UNINDENT +.INDENT 0.0 +.TP +.B salt.modules.freebsdjail.start(jail=\(aq\(aq) +Start the specified jail or all, if none specified +.sp +CLI Example: +.sp +.nf +.ft C +salt \(aq*\(aq jail.start [] +.ft P +.fi +.UNINDENT +.INDENT 0.0 +.TP +.B salt.modules.freebsdjail.status(jail) +See if specified jail is currently running +.sp +CLI Example: +.sp +.nf +.ft C +salt \(aq*\(aq jail.status +.ft P +.fi +.UNINDENT +.INDENT 0.0 +.TP +.B salt.modules.freebsdjail.stop(jail=\(aq\(aq) +Stop the specified jail or all, if none specified +.sp +CLI Example: +.sp +.nf +.ft C +salt \(aq*\(aq jail.stop [] +.ft P +.fi +.UNINDENT +.INDENT 0.0 +.TP +.B salt.modules.freebsdjail.sysctl() +Dump all jail related kernel states (sysctl) +.UNINDENT .SS salt.modules.freebsdkmod .sp Module to manage FreeBSD kernel modules @@ -6084,6 +6983,19 @@ salt \(aq*\(aq pkg.remove .UNINDENT .INDENT 0.0 .TP +.B salt.modules.freebsdpkg.search(pkg_name) +Use \fIpkg search\fP if pkg is being used. +.sp +CLI Example: +.sp +.nf +.ft C +salt \(aq*\(aq pkg.pkgng_search \(aqmysql\-server\(aq +.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 @@ -6863,7 +7775,7 @@ salt \(aq*\(aq grains.ls Manage groups on Linux .INDENT 0.0 .TP -.B salt.modules.groupadd.add(name, gid=None) +.B salt.modules.groupadd.add(name, gid=None, system=False) Add the specified group .sp CLI Example: @@ -6926,6 +7838,35 @@ salt \(aq*\(aq group.info foo .ft P .fi .UNINDENT +.SS salt.modules.grub +.sp +Support for GRUB +.INDENT 0.0 +.TP +.B salt.modules.grub.conf() +Parse GRUB conf file +.sp +CLI Example: +.sp +.nf +.ft C +salt \(aq*\(aq grub.conf +.ft P +.fi +.UNINDENT +.INDENT 0.0 +.TP +.B salt.modules.grub.version() +Return server version from grub \-\-version +.sp +CLI Example: +.sp +.nf +.ft C +salt \(aq*\(aq grub.version +.ft P +.fi +.UNINDENT .SS salt.modules.hg .sp Support for the Mercurial SCM @@ -7113,41 +8054,53 @@ Manage the information in the hosts file .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:: +.sp +CLI Example: +.sp +.nf +.ft C salt \(aq*\(aq hosts.add_host -.UNINDENT +.ft P +.fi .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:: +.sp +CLI Example: +.sp +.nf +.ft C salt \(aq*\(aq hosts.get_alias -.UNINDENT +.ft P +.fi .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:: +.sp +CLI Example: +.sp +.nf +.ft C salt \(aq*\(aq hosts.get_ip -.UNINDENT +.ft P +.fi .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:: +.sp +CLI Example: +.sp +.nf +.ft C salt \(aq*\(aq hosts.has_pair -.UNINDENT +.ft P +.fi .UNINDENT .INDENT 0.0 .TP @@ -7172,22 +8125,28 @@ salt \(aq*\(aq hosts.list_hosts .TP .B salt.modules.hosts.rm_host(ip, alias) Remove a host entry from the hosts file -.INDENT 7.0 -.TP -.B CLI Example:: +.sp +CLI Example: +.sp +.nf +.ft C salt \(aq*\(aq hosts.rm_host -.UNINDENT +.ft P +.fi .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:: +.sp +CLI Example: +.sp +.nf +.ft C salt \(aq*\(aq hosts.set_host -.UNINDENT +.ft P +.fi .UNINDENT .SS salt.modules.kmod .sp @@ -7471,6 +8430,79 @@ salt \(aq*\(aq hyper.virt_info .ft P .fi .UNINDENT +.SS salt.modules.launchctl +.sp +Module for the management of MacOS systems that use launchd/launchctl +.INDENT 0.0 +.TP +.B salt.modules.launchctl.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.launchctl.get_launchctl_data(job_label, runas=None) +.UNINDENT +.INDENT 0.0 +.TP +.B salt.modules.launchctl.restart(job_label, runas=None) +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.launchctl.start(job_label, runas=None) +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.launchctl.status(job_label, runas=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.launchctl.stop(job_label, runas=None) +Stop the specified service +.sp +CLI Example: +.sp +.nf +.ft C +salt \(aq*\(aq service.stop +.ft P +.fi +.UNINDENT .SS salt.modules.linux_sysctl .sp Module for viewing and modifying sysctl parameters @@ -7864,6 +8896,10 @@ salt \(aq*\(aq mysql.grant_add \(aqSELECT|INSERT|UPDATE|...\(aq \(aqdatabase.*\( .UNINDENT .INDENT 0.0 .TP +.B salt.modules.mysql.grant_exists(grant, database, user, host=\(aqlocalhost\(aq, grant_option=False, escape=True) +.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 @@ -8203,26 +9239,81 @@ salt \(aq*\(aq nginx.version .ft P .fi .UNINDENT -.SS salt.modules.pacman +.SS salt.modules.osxdesktop .sp -A module to wrap pacman calls, since Arch is the best -(\fI\%https://wiki.archlinux.org/index.php/Arch_is_the_best\fP) +Mac OS X implementations of various commands in the "desktop" interface .INDENT 0.0 .TP -.B salt.modules.pacman.available_version(name) -The available version of the package in the repository +.B salt.modules.osxdesktop.get_output_volume() +Get the output volume (range 0 to 100) .sp CLI Example: .sp .nf .ft C -salt \(aq*\(aq pkg.available_version +salt \(aq*\(aq desktop.get_output_volume .ft P .fi .UNINDENT .INDENT 0.0 .TP -.B salt.modules.pacman.install(name, refresh=False, **kwargs) +.B salt.modules.osxdesktop.lock() +Lock the desktop session +.sp +CLI Example: +.sp +.nf +.ft C +salt \(aq*\(aq desktop.lock +.ft P +.fi +.UNINDENT +.INDENT 0.0 +.TP +.B salt.modules.osxdesktop.screensaver() +Launch the screensaver +.sp +CLI Example: +.sp +.nf +.ft C +salt \(aq*\(aq desktop.screensaver +.ft P +.fi +.UNINDENT +.INDENT 0.0 +.TP +.B salt.modules.osxdesktop.set_output_volume(volume) +Set the volume of sound (range 0 to 100) +.sp +CLI Example: +.sp +.nf +.ft C +salt \(aq*\(aq desktop.set_output_volume +.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: @@ -8621,6 +9712,105 @@ salt \(aq*\(aq pip.uninstall bin_env=/path/to/pip_bin .ft P .fi .UNINDENT +.SS salt.modules.postgres +.sp +Module to provide Postgres compatibility to salt. +.sp +In order to connect to Postgres, certain configuration is required +in /etc/salt/minion on the relevant minions. Some sample configs +might look like: +.sp +.nf +.ft C +postgres.host: \(aqlocalhost\(aq +postgres.port: \(aq5432\(aq +postgres.user: \(aqpostgres\(aq +postgres.pass: \(aq\(aq +postgres.db: \(aqpostgres\(aq +.ft P +.fi +.INDENT 0.0 +.TP +.B salt.modules.postgres.db_create(name, user=None, host=None, port=None, tablespace=None, encoding=None, local=None, lc_collate=None, lc_ctype=None, owner=None, template=None) +Adds a databases to the Postgres server. +.sp +CLI Example: +.sp +.nf +.ft C +salt \(aq*\(aq postgres.db_create \(aqdbname\(aq + +salt \(aq*\(aq postgres.db_create \(aqdbname\(aq template=template_postgis +.ft P +.fi +.UNINDENT +.INDENT 0.0 +.TP +.B salt.modules.postgres.db_exists(name, user=None, host=None, port=None) +Checks if a database exists on the Postgres server. +.sp +CLI Example: +.sp +.nf +.ft C +salt \(aq*\(aq postgres.db_exists \(aqdbname\(aq +.ft P +.fi +.UNINDENT +.INDENT 0.0 +.TP +.B salt.modules.postgres.db_list(user=None, host=None, port=None) +Return a list of databases of a Postgres server using the output +from the \fBpsql \-l\fP query. +.sp +CLI Example: +.sp +.nf +.ft C +salt \(aq*\(aq postgres.db_list +.ft P +.fi +.UNINDENT +.INDENT 0.0 +.TP +.B salt.modules.postgres.db_remove(name, user=None, host=None, port=None) +Removes a databases from the Postgres server. +.sp +CLI Example: +.sp +.nf +.ft C +salt \(aq*\(aq postgres.db_remove \(aqdbname\(aq +.ft P +.fi +.UNINDENT +.INDENT 0.0 +.TP +.B salt.modules.postgres.user_create(username, user=None, host=None, port=None, createdb=False, createuser=False, encrypted=False, password=None) +Creates a Postgres user. +.sp +CLI Examples: +.sp +.nf +.ft C +salt \(aq*\(aq postgres.user_create \(aqusername\(aq user=\(aquser\(aq host=\(aqhostname\(aq port=\(aqport\(aq password=\(aqpassword\(aq +.ft P +.fi +.UNINDENT +.INDENT 0.0 +.TP +.B salt.modules.postgres.version() +Return the version of a Postgres server using the output +from the \fBpsql \-\-version\fP cmd. +.sp +CLI Example: +.sp +.nf +.ft C +salt \(aq*\(aq postgres.version +.ft P +.fi +.UNINDENT .SS salt.modules.ps .sp A salt interface to psutil, a system and process library. @@ -8655,7 +9845,7 @@ salt \(aq*\(aq ps.cached_physical_memory .UNINDENT .INDENT 0.0 .TP -.B salt.modules.ps.cpu_percent(interval=0.10000000000000001, per_cpu=False) +.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 @@ -8909,6 +10099,20 @@ salt system.example.com publish.publish \(aq*\(aq cmd.run \(aqls \-la /tmp\(aq .ft P .fi .UNINDENT +.INDENT 0.0 +.TP +.B salt.modules.publish.runner(fun, arg=None) +Execute a runner on the master and return the data from the runner +function +.sp +CLI Example: +.sp +.nf +.ft C +salt publish.runner manage.down +.ft P +.fi +.UNINDENT .SS salt.modules.puppet .sp Execute puppet routines @@ -8921,258 +10125,430 @@ CLI Example: .sp .nf .ft C -salt \(aq*\(aq puppet.fact kernel +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 FreeBSD +.INDENT 0.0 +.TP +.B salt.modules.pw_group.add(name, gid=None, system=False) +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, system=False, **kwargs) +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.puppet.facts() -Run facter and return the results +.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 puppet.facts +salt \(aq*\(aq user.chshell foo /bin/zsh .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 +.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 puppet.noop - -salt \(aq*\(aq puppet.noop web::server,django::base +salt \(aq*\(aq user.chuid foo 4376 .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 +.B salt.modules.pw_user.delete(name, remove=False, force=False) +Remove a user from the minion .sp -CLI Examples: +CLI Example: .sp .nf .ft C -salt \(aq*\(aq puppet.run - -salt \(aq*\(aq puppet.run basefiles::edit,apache::server +salt \(aq*\(aq user.delete name True True .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 +.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 group.add foo 3456 +salt \(aq*\(aq user.getent .ft P .fi .UNINDENT .INDENT 0.0 .TP -.B salt.modules.pw_group.chgid(name, gid) -Change the gid for a named group +.B salt.modules.pw_user.info(name) +Return user information .sp CLI Example: .sp .nf .ft C -salt \(aq*\(aq group.chgid foo 4376 +salt \(aq*\(aq user.info root .ft P .fi .UNINDENT .INDENT 0.0 .TP -.B salt.modules.pw_group.delete(name) -Remove the named group +.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 group.delete foo +salt \(aq*\(aq user.list_groups foo .ft P .fi .UNINDENT +.SS salt.modules.rabbitmq_server +.sp +Module to provide rabbitMQ compatibility to salt. +Todo: Alot, need to add cluster support, logging, and minion configuration data. .INDENT 0.0 .TP -.B salt.modules.pw_group.getent() -Return info on all groups +.B salt.modules.rabbitmq_server.add_user(name, password) +Add a rabbitMQ user via rabbitmqctl user_add .sp CLI Example: .sp .nf .ft C -salt \(aq*\(aq group.getent +salt \(aq*\(aq rabbitmq\-server.add_user \(aqmeow\(aq \(aqmix\(aq .ft P .fi .UNINDENT .INDENT 0.0 .TP -.B salt.modules.pw_group.info(name) -Return information about a group +.B salt.modules.rabbitmq_server.add_vhost(vhost) +Adds a vhost via rabbitmqctl add_vhost. .sp CLI Example: .sp .nf .ft C -salt \(aq*\(aq group.info foo +salt \(aq*\(aq rabbitmq\-server add_vhost \(aq\(aq .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, **kwargs) -Add a user to the minion +.B salt.modules.rabbitmq_server.delete_user(name) +Deletes a user via rabbitmqctl delete_user. .sp CLI Example: .sp .nf .ft C -salt \(aq*\(aq user.add name +salt \(aq*\(aq rabbitmq\-server.delete_user \(aqmeow\(aq .ft P .fi .UNINDENT .INDENT 0.0 .TP -.B salt.modules.pw_user.chgid(name, gid) -Change the default group of the user +.B salt.modules.rabbitmq_server.delete_vhost(vhost) +Deletes a vhost rabbitmqctl delete_vhost. .sp CLI Example: .sp .nf .ft C -salt \(aq*\(aq user.chgid foo 4376 +salt \(aq*\(aq rabbitmq\-server.delete_vhost \(aq\(aq .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 +.B salt.modules.rabbitmq_server.list_user_permissions(name) +List permissions for a user via rabbitmqctl list_user_permissions .sp -CLI Example: +Example: .sp .nf .ft C -salt \(aq*\(aq user.chgroups foo wheel,root True +salt \(aq*\(aq rabbitmq\-server.list_user_permissions \(aquser\(aq. .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 +.B salt.modules.rabbitmq_server.list_users() +Return a list of users based off of rabbitmqctl user_list. .sp CLI Example: .sp .nf .ft C -salt \(aq*\(aq user.chhome foo /home/users/foo True +salt \(aq*\(aq rabbitmq\-server.list_users .ft P .fi .UNINDENT .INDENT 0.0 .TP -.B salt.modules.pw_user.chshell(name, shell) -Change the default shell of the user +.B salt.modules.rabbitmq_server.list_vhosts() +Return a list of vhost based of of rabbitmqctl list_vhosts. .sp CLI Example: .sp .nf .ft C -salt \(aq*\(aq user.chshell foo /bin/zsh +salt \(aq*\(aq rabbitmq\-server.list_vhosts .ft P .fi .UNINDENT .INDENT 0.0 .TP -.B salt.modules.pw_user.chuid(name, uid) -Change the uid for a named user +.B salt.modules.rabbitmq_server.set_permissions(vhost, user, conf=\(aq.*\(aq, write=\(aq.*\(aq, read=\(aq.*\(aq) +Sets permissions for vhost via rabbitmqctl set_permissions .sp CLI Example: .sp .nf .ft C -salt \(aq*\(aq user.chuid foo 4376 +salt \(aq*\(aq rabbitmq\-server.set_permissions \(aqmyvhost\(aq \(aqmyuser\(aq .ft P .fi .UNINDENT +.SS salt.modules.reg +.sp +Manage the registry on Windows +.sp +Required python modules: _winreg .INDENT 0.0 .TP -.B salt.modules.pw_user.delete(name, remove=False, force=False) -Remove a user from the minion +.B class salt.modules.reg.Registry +Delay \(aq_winreg\(aq usage until this module is used +.UNINDENT +.INDENT 0.0 +.TP +.B salt.modules.reg.create_key(hkey, path, key, value=None) +Create a registry key .sp CLI Example: .sp .nf .ft C -salt \(aq*\(aq user.delete name True True +salt \(aq*\(aq reg.create_key HKEY_CURRENT_USER \(aqSOFTWARE\eSalt\(aq \(aqversion\(aq \(aq0.97\(aq .ft P .fi .UNINDENT .INDENT 0.0 .TP -.B salt.modules.pw_user.getent() -Return the list of all info for all users +.B salt.modules.reg.delete_key(hkey, path, key) +Delete a registry key +.sp +Note: This cannot delete a key with subkeys .sp CLI Example: .sp .nf .ft C -salt \(aq*\(aq user.getent +salt \(aq*\(aq reg.delete_key HKEY_CURRENT_USER \(aqSOFTWARE\eSalt\(aq \(aqversion\(aq .ft P .fi .UNINDENT .INDENT 0.0 .TP -.B salt.modules.pw_user.info(name) -Return user information +.B salt.modules.reg.read_key(hkey, path, key) +Read registry key value .sp CLI Example: .sp .nf .ft C -salt \(aq*\(aq user.info root +salt \(aq*\(aq reg.read_key HKEY_LOCAL_MACHINE \(aqSOFTWARE\eSalt\(aq \(aqversion\(aq .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 +.B salt.modules.reg.set_key(hkey, path, key, value) +Set a registry key .sp CLI Example: .sp .nf .ft C -salt \(aq*\(aq user.list_groups foo +salt \(aq*\(aq reg.set_key HKEY_CURRENT_USER \(aqSOFTWARE\eSalt\(aq \(aqversion\(aq \(aq0.97\(aq .ft P .fi .UNINDENT @@ -9182,32 +10558,80 @@ The networking module for RHEL/Fedora based distros .INDENT 0.0 .TP .B salt.modules.rh_ip.build_bond(iface, settings) -Create a bond script in /etc/modprobe.d +Create a bond script in /etc/modprobe.d with the passed settings +.sp +CLI Example: +.sp +.nf +.ft C +salt \(aq*\(aq ip.build_bond br0 mode=balance\-alb +.ft P +.fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.rh_ip.build_interface(iface, type, settings) Build an interface script for a network interface. +.sp +CLI Example: +.sp +.nf +.ft C +salt \(aq*\(aq ip.build_interface eth0 eth +.ft P +.fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.rh_ip.down(iface) Shutdown a network interface +.sp +CLI Example: +.sp +.nf +.ft C +salt \(aq*\(aq ip.down eth0 +.ft P +.fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.rh_ip.get_bond(iface) Return the content of a bond script +.sp +CLI Example: +.sp +.nf +.ft C +salt \(aq*\(aq ip.get_bond br0 +.ft P +.fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.rh_ip.get_interface(iface) Return the contents of an interface script +.sp +CLI Example: +.sp +.nf +.ft C +salt \(aq*\(aq ip.get_interface eth0 +.ft P +.fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.rh_ip.up(iface) Start up a network interface +.sp +CLI Example: +.sp +.nf +.ft C +salt \(aq*\(aq ip.up eth0 +.ft P +.fi .UNINDENT .SS salt.modules.rh_service .sp @@ -10204,7 +11628,7 @@ salt \(aq*\(aq solr.core_status None music .UNINDENT .INDENT 0.0 .TP -.B salt.modules.solr.delta_import(handler, host=None, core_name=None, options={}, extra=[]) +.B salt.modules.solr.delta_import(handler, host=None, core_name=None, options=None, extra=None) 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 @@ -10251,7 +11675,7 @@ salt \(aq*\(aq solr.delta_import dataimport None music {\(aqclean\(aq:True} .UNINDENT .INDENT 0.0 .TP -.B salt.modules.solr.full_import(handler, host=None, core_name=None, options={}, extra=[]) +.B salt.modules.solr.full_import(handler, host=None, core_name=None, options=None, extra=None) 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 @@ -10743,7 +12167,102 @@ CLI Example: .sp .nf .ft C -alt \(aq*\(aq solr.version +salt \(aq*\(aq solr.version +.ft P +.fi +.UNINDENT +.SS salt.modules.sqlite3 +.sp +Support for SQLite3 +.INDENT 0.0 +.TP +.B salt.modules.sqlite3.fetch(db=None, sql=None) +Retrieve data from an sqlite3 db (returns all rows, be careful!) +.sp +CLI Example: +.sp +.nf +.ft C +salt \(aq*\(aq sqlite3.fetch /root/test.db \(aqSELECT * FROM test;\(aq +.ft P +.fi +.UNINDENT +.INDENT 0.0 +.TP +.B salt.modules.sqlite3.indexes(db=None) +Show all indices in the database, for people with poor spelling skills +.sp +CLI Example: +.sp +.nf +.ft C +salt \(aq*\(aq sqlite3.indexes /root/test.db +.ft P +.fi +.UNINDENT +.INDENT 0.0 +.TP +.B salt.modules.sqlite3.indices(db=None) +Show all indices in the database +.sp +CLI Example: +.sp +.nf +.ft C +salt \(aq*\(aq sqlite3.indices /root/test.db +.ft P +.fi +.UNINDENT +.INDENT 0.0 +.TP +.B salt.modules.sqlite3.modify(db=None, sql=None) +Issue an SQL query to sqlite3 (with no return data), usually used +to modify the database in some way (insert, delete, create, etc) +.sp +CLI Example: +.sp +.nf +.ft C +salt \(aq*\(aq sqlite3.modify /root/test.db \(aqCREATE TABLE test(id INT, testdata TEXT);\(aq +.ft P +.fi +.UNINDENT +.INDENT 0.0 +.TP +.B salt.modules.sqlite3.sqlite_version() +Return version of sqlite +.sp +CLI Example: +.sp +.nf +.ft C +salt \(aq*\(aq sqlite3.sqlite_version +.ft P +.fi +.UNINDENT +.INDENT 0.0 +.TP +.B salt.modules.sqlite3.tables(db=None) +Show all tables in the database +.sp +CLI Example: +.sp +.nf +.ft C +salt \(aq*\(aq sqlite3.tables /root/test.db +.ft P +.fi +.UNINDENT +.INDENT 0.0 +.TP +.B salt.modules.sqlite3.version() +Return version of pysqlite +.sp +CLI Example: +.sp +.nf +.ft C +salt \(aq*\(aq sqlite3.version .ft P .fi .UNINDENT @@ -10778,12 +12297,48 @@ salt \(aq*\(aq ssh.check_key .UNINDENT .INDENT 0.0 .TP -.B salt.modules.ssh.check_key_file(user, keysource, config=\(aq.ssh/authorized_keys\(aq) +.B salt.modules.ssh.check_key_file(user, keysource, config=\(aq.ssh/authorized_keys\(aq, env=\(aqbase\(aq) Check a keyfile from a source destination against the local keys and return the keys to change .UNINDENT .INDENT 0.0 .TP +.B salt.modules.ssh.check_known_host(user, hostname, key=None, fingerprint=None, config=\(aq.ssh/known_hosts\(aq) +Check the record in known_hosts file, either by its value or by fingerprint +(it\(aqs enough to set up either key or fingerprint, you don\(aqt need to set up +both). +.sp +If provided key or fingerprint doesn\(aqt match with stored value, return +"update", if no value is found for a given host, return "add", otherwise +return "exists". +.sp +If neither key, nor fingerprint is defined, then additional validation is +not performed. +.sp +CLI Example: +.sp +.nf +.ft C +salt \(aq*\(aq ssh.check_known_host key=\(aqAAAA...FAaQ==\(aq +.ft P +.fi +.UNINDENT +.INDENT 0.0 +.TP +.B salt.modules.ssh.get_known_host(user, hostname, config=\(aq.ssh/known_hosts\(aq) +Return information about known host from the configfile, if any. +If there is no such key, return None. +.sp +CLI Example: +.sp +.nf +.ft C +salt \(aq*\(aq ssh.get_known_host +.ft P +.fi +.UNINDENT +.INDENT 0.0 +.TP .B salt.modules.ssh.host_keys(keydir=None) Return the minion\(aqs host keys .sp @@ -10791,20 +12346,46 @@ CLI Example: .sp .nf .ft C -salt \(aq*\(aq ssh.host_keys +salt \(aq*\(aq ssh.host_keys +.ft P +.fi +.UNINDENT +.INDENT 0.0 +.TP +.B salt.modules.ssh.recv_known_host(user, hostname, enc=None, port=None, hash_hostname=False) +Retreive information about host public key from remote server +.sp +CLI Example: +.sp +.nf +.ft C +salt \(aq*\(aq ssh.recv_known_host enc= port= +.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 .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 +.B salt.modules.ssh.rm_known_host(user, hostname, config=\(aq.ssh/known_hosts\(aq) +Remove all keys belonging to hostname from a known_hosts file. .sp CLI Example: .sp .nf .ft C -salt \(aq*\(aq ssh.rm_auth_key +salt \(aq*\(aq ssh.rm_known_host .ft P .fi .UNINDENT @@ -10823,7 +12404,7 @@ salt \(aq*\(aq ssh.set_auth_key key=\(aq\(aq enc=\(aqdsa\(aq .UNINDENT .INDENT 0.0 .TP -.B salt.modules.ssh.set_auth_key_from_file(user, source, config=\(aq.ssh/authorized_keys\(aq) +.B salt.modules.ssh.set_auth_key_from_file(user, source, config=\(aq.ssh/authorized_keys\(aq, env=\(aqbase\(aq) Add a key to the authorized_keys file, using a file as the source. .sp CLI Example: @@ -10834,6 +12415,23 @@ salt \(aq*\(aq ssh.set_auth_key_from_file salt://ssh_keys/ .ft P .fi .UNINDENT +.INDENT 0.0 +.TP +.B salt.modules.ssh.set_known_host(user, hostname, fingerprint=None, port=None, enc=None, hash_hostname=True, config=\(aq.ssh/known_hosts\(aq) +Download SSH public key from remote host "hostname", optionally validate +its fingerprint against "fingerprint" variable and save the record in the +known_hosts file. +.sp +If such a record does already exists in there, do nothing. +.sp +CLI Example: +.sp +.nf +.ft C +salt \(aq*\(aq ssh.set_known_host fingerprint=\(aqxx:xx:..:xx\(aq enc=\(aqssh\-rsa\(aq config=\(aq.ssh/known_hosts\(aq +.ft P +.fi +.UNINDENT .SS salt.modules.state .sp Control the state system on the minion @@ -10919,14 +12517,31 @@ salt \(aq*\(aq state.show_masterstate .UNINDENT .INDENT 0.0 .TP +.B salt.modules.state.show_sls(mods, env=\(aqbase\(aq, test=None, **kwargs) +Display the state data from a specific sls or list of sls files on the +master +.sp +CLI Example: +.sp +.nf +.ft C +salt \(aq*\(aq state.sls core,edit.vim dev +.ft P +.fi +.UNINDENT +.INDENT 0.0 +.TP .B salt.modules.state.single(fun=None, test=None, **kwargs) Execute a single state function with the named kwargs, returns False if insufficient data is sent to the command -.INDENT 7.0 -.TP -.B CLI Example:: +.sp +CLI Example: +.sp +.nf +.ft C salt \(aq*\(aq state.single pkg.installed name=vim -.UNINDENT +.ft P +.fi .UNINDENT .INDENT 0.0 .TP @@ -11725,7 +13340,7 @@ salt \(aq*\(aq service.stop 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, unique=True) +.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, unique=True, system=False) Add a user to the minion .sp CLI Example: @@ -12866,11 +14481,16 @@ Access time in Unix epoch time .TP .B mtime: Last modification in Unix epoch time -.TP -.B CLI Example:: -salt \(aq*\(aq file.touch /var/log/emptyfile .UNINDENT .sp +CLI Example: +.sp +.nf +.ft C +salt \(aq*\(aq file.touch /var/log/emptyfile +.ft P +.fi +.sp New in version 0.9.5. .UNINDENT .INDENT 0.0 @@ -12936,6 +14556,61 @@ salt \(aq*\(aq file.user_to_uid myusername .ft P .fi .UNINDENT +.SS salt.modules.win_groupadd +.sp +Manage groups on Windows +.INDENT 0.0 +.TP +.B salt.modules.win_groupadd.add(name, gid=None, system=False) +Add the specified group +.sp +CLI Example: +.sp +.nf +.ft C +salt \(aq*\(aq group.add foo +.ft P +.fi +.UNINDENT +.INDENT 0.0 +.TP +.B salt.modules.win_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.win_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.win_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.win_network .sp Module for gathering and managing network information @@ -13045,43 +14720,211 @@ CLI Example: 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 +.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_pkg +.sp +A module to manage software on Windows +.INDENT 0.0 +.TP +.B salt.modules.win_pkg.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.win_pkg.install(name, 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.win_pkg.list_pkgs(*args) +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.win_pkg.list_upgrades() +List all available package upgrades on this system +.sp +CLI Example: +.sp +.nf +.ft C +salt \(aq*\(aq pkg.list_upgrades +.ft P +.fi +.UNINDENT +.INDENT 0.0 +.TP +.B salt.modules.win_pkg.purge(name) +Recursively remove a package and all dependencies which were installed +with it +.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.win_pkg.refresh_db() +Just recheck the repository and 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.win_pkg.remove(name) +Remove a single package +.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.win_pkg.upgrade() +Run a full system upgrade +.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 network.ping archlinux.org +salt \(aq*\(aq pkg.upgrade .ft P .fi .UNINDENT .INDENT 0.0 .TP -.B salt.modules.win_network.traceroute(host) -Performs a traceroute to a 3rd party host +.B salt.modules.win_pkg.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 network.traceroute archlinux.org +salt \(aq*\(aq pkg.upgrade_available .ft P .fi .UNINDENT .INDENT 0.0 .TP -.B salt.modules.win_network.up(interface) -Returns True if interface is up, otherwise returns False +.B salt.modules.win_pkg.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 network.up \(aqWireless LAN adapter Wireless Network Connection\(aq +salt \(aq*\(aq pkg.version .ft P .fi .UNINDENT @@ -13283,7 +15126,7 @@ Manage Windows users with the net user command 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) +.B salt.modules.win_useradd.add(name, uid=None, gid=None, groups=None, home=False, shell=None, system=False) Add a user to the minion .sp CLI Example: @@ -13356,7 +15199,7 @@ CLI Example: .sp .nf .ft C -salt \(aq*\(aq user.delete name +salt \(aq*\(aq user.delete name .ft P .fi .UNINDENT @@ -13948,13 +15791,13 @@ salt \(aq*\(aq pkg.version .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. +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. +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, @@ -14023,8 +15866,8 @@ 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.9/salt/returners\fP +The collection of built\-in Salt returners can be found here: +\fI\%https://github.com/saltstack/salt/blob/v0.10.0/salt/returners\fP .SH FULL LIST OF BUILTIN RETURNERS .TS center; @@ -14092,8 +15935,6 @@ Return data to a Cassandra ColumnFamily .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 @@ -14147,14 +15988,38 @@ extend: .ft P .fi .sp -A few critical things happened here, first off the sls files that are going to +A few critical things happened here, first off the SLS files that are going to be extended are included, then the extend dec is defined. Under the extend dec 2 IDs are extended, the apache ID\(aqs file state is overwritten with a new name and source. Than the ssh server is extended to watch the banner file in addition to anything it is already watching. +.SS Extend is a Top Level Declaration +.sp +This means that \fBextend\fP can only be called once in an sls, if if is used +twice then only one of the extend blocks will be read. So this is WRONG: +.sp +.nf +.ft C +include: + \- http + \- ssh + +extend: + apache: + file: + \- name: /etc/httpd/conf/httpd.conf + \- source: salt://http/httpd2.conf +# Second extend will overwrite the first!! Only make one +extend: + ssh\-server: + service: + \- watch: + \- file: /etc/ssh/banner +.ft P +.fi .SS The Requisite "in" Statement .sp -Since one of the most common things to do when extending another sls is to add +Since one of the most common things to do when extending another SLS is to add states for a service to watch, or anything for a watcher to watch, the requisite in statement was added to 0.9.8 to make extending the watch and require lists easier. The ssh\-server extend statement above could be more @@ -14178,13 +16043,13 @@ include: There are a few rules to remember when extending states: .INDENT 0.0 .IP 1. 3 -Always include the sls being extended with an include declaration +Always include the SLS being extended with an include declaration .IP 2. 3 Requisites (watch and require) are appended to, everything else is overwritten .IP 3. 3 extend is a top level declaration, like an ID declaration, cannot be -declared twice in a single sls +declared twice in a single SLS .IP 4. 3 Many IDs can be extended under the extend declaration .UNINDENT @@ -14256,16 +16121,16 @@ Configurable via \fBstate_top\fP. .INDENT 0.0 .TP .B State tree -A collection of \fBsls\fP files that live under the directory specified +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. +\fBSLS 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. +\fISLS\fP. .sp Occurs only in the top level of the highstate structure. .UNINDENT @@ -14284,7 +16149,7 @@ include: .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 +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 @@ -14311,16 +16176,16 @@ ID declarations with the same name will be ignored. .INDENT 0.0 .TP .B Extend declaration -Extends a \fIname declaration\fP from an included \fBsls module\fP. The +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. +\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 +\fIstate declaration\fP that is defined in another \fBSLS\fP file. 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, @@ -14504,7 +16369,7 @@ python\-pkgs: .ft P .fi .sp -Once converted into the \fIlowstate\fP data structure the above state +Once converted into the lowstate data structure the above state declaration will be expanded into the following three state declarations: .sp .nf @@ -14566,7 +16431,7 @@ components. .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 +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 @@ -14589,17 +16454,17 @@ 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. +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 +.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 +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 @@ -14625,8 +16490,8 @@ salt/master.sls .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 +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 @@ -14634,10 +16499,10 @@ 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. +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 +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 @@ -14687,7 +16552,7 @@ salt: .ft P .fi .sp -This short stanza will ensure that vim is installed, salt is installed and up +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 @@ -14715,7 +16580,7 @@ base: .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 +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. @@ -14723,26 +16588,26 @@ salt.master state. .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. +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 +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.9/salt/renderers\fP +\fI\%https://github.com/saltstack/salt/blob/v0.10.0/salt/renderers\fP .sp -By default sls files are rendered using jinja as a templating engine, and yaml +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. +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 +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 @@ -14885,7 +16750,7 @@ 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 +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. @@ -15001,8 +16866,8 @@ emacs: .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 +In this example the default pkg module is being redirected to use the \fIyumpkg5\fP +module (\fIyum\fP 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 REQUISITES @@ -15082,7 +16947,7 @@ the service is reloaded or restarted. # This needs to be filled in .SH THE TOP FILE .sp -The top file is used to map what sls modules get loaded onto what minions via +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. @@ -15183,10 +17048,10 @@ prod: .ft P .fi .sp -In this setup all systems will pull the global sls from the base environment, +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 +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 @@ -15236,7 +17101,8 @@ In addition to globs, minions can be specified in top files a few other ways. Some common ones are \fBcompound matches\fP and \fBnode groups\fP. .sp -Here is a slightly more complex top file example: +Here is a slightly more complex top file example, showing the different types +of matches you can perform: .sp .nf .ft C @@ -15249,28 +17115,48 @@ base: \(aqsalt\-master*\(aq: \- salt.master - \(aqnag1* or G@role:monitoring\(aq: - \- match: compound - \- nagios.server - - \(aqE@^(memcache|web).(qa|prod).loc$\(aq: + \(aq^(memcache|web).(qa|prod).loc$\(aq: \- match: pcre \- nagios.mon.web \- apache.server + + \(aqos:Ubuntu\(aq: + \- match: grain + \- repos.ubuntu + + \(aqos:(RedHat|CentOS)\(aq + \- match: grain_pcre + \- repos.epel + + \(aqfoo,bar,baz\(aq: + \- match: list + \- database + + \(aqsomekey:abc\(aq + \- match: pillar + \- xyz + + \(aqnag1* or G@role:monitoring\(aq: + \- match: compound + \- nagios.server .ft P .fi .sp In this example \fBtop.sls\fP, all minions get the ldap\-client, networking and salt.minion states. Any minion with an id matching the \fBsalt\-master*\fP glob -will get the salt.master state. Minions with ids matching the nag1* glob or -with a grain named \fBrole\fP equal to \fBmonitoring\fP will get the nagios.server -state. Finally, any minion with ids matching the regular expression -\fB^(memcache|web).(qa|prod).loc$\fP, will get the nagios.mon.web and -apache.server states. +will get the salt.master state. Any minion with ids matching the regular +expression \fB^(memcache|web).(qa|prod).loc$\fP will get the nagios.mon.web and +apache.server states. All Ubuntu minions will receive the repos.ubuntu state, +while all RHEL and CentOS minions will receive the repos.epel state. The +minions \fBfoo\fP, \fBbar\fP, and \fBbaz\fP will receive the database state. Any +minion with a pillar named \fBsomekey\fP, having a value of \fBabc\fP will receive +the xyz state. Finally, minions with ids matching the nag1* glob or with a +grain named \fBrole\fP equal to \fBmonitoring\fP will receive the nagios.server +state. .SH STATE MODULES .sp State Modules are the components that map to actual enforcement and management -of salt states. +of Salt states. .SS States are \- Easy to Write! .sp State Modules should be easy to write and straightforward. The information @@ -15411,137 +17297,156 @@ _ T{ \fBalias\fP T} T{ -Aliases File Management +Configuration of email aliases. T} _ T{ \fBcmd\fP T} T{ -Command Executions +Execution of arbitrary commands. T} _ T{ \fBcron\fP T} T{ -Cron Management +Management of cron, the Unix command scheduler. T} _ T{ \fBfile\fP T} T{ -File Management +Operations on files, directories and symlinks. T} _ T{ \fBgem\fP T} T{ -Management of rubygems +Installation of Ruby modules packaged as gems. +T} +_ +T{ +\fBgit\fP +T} T{ +Interaction with Git repositories. T} _ T{ \fBgroup\fP T} T{ -Group Management +Management of user groups. T} _ T{ \fBhost\fP T} T{ -Hosts File Management +Management of addresses and names in hosts file. T} _ T{ \fBkmod\fP T} T{ -Kernel Module Management +Loading and unloading of kernel modules. T} _ T{ \fBmount\fP T} T{ -Mount Management +Mounting of filesystems. T} _ T{ \fBmysql_database\fP T} T{ -MySQL Database Management +Management of MySQL databases (schemas). T} _ T{ \fBmysql_grants\fP T} T{ -MySQL Grant Management +Management of MySQL grants (user permissions). T} _ T{ \fBmysql_user\fP T} T{ -MySQL User Management +Management of MySQL users. T} _ T{ \fBnetwork\fP T} T{ +Configuration of network interfaces. T} _ T{ \fBpip\fP T} T{ -Management of python packages +Installation of Python packages using pip. T} _ T{ \fBpkg\fP T} T{ -Package Management +Installation of packages using OS package managers such as yum or apt\-get. T} _ T{ \fBpostgres_database\fP T} T{ -Postgres Database Management +Management of PostgreSQL databases (schemas). T} _ T{ \fBrvm\fP T} T{ -Management of ruby installations and gemsets with RVM +Management of Ruby installations and gemsets with RVM, the Ruby Version Manager. +T} +_ +T{ +\fBselinux\fP +T} T{ +Management of SELinux rules. T} _ T{ \fBservice\fP T} T{ -Service Management +Starting or restarting of services and daemons. T} _ T{ \fBssh_auth\fP T} T{ -SSH Authorized Key Management +Control of entries in SSH authorized_key files. +T} +_ +T{ +\fBssh_known_hosts\fP +T} T{ +Control of SSH known_hosts entries. T} _ T{ \fBsysctl\fP T} T{ -Kernel Sysctl Management +Configuration of the Linux kernel using sysctrl. T} _ T{ \fBuser\fP T} T{ -User Management +Management of user accounts. T} _ T{ \fBvirtualenv\fP T} T{ -virtualenv management +Setup of Python virtualenv sandboxes. T} _ .TE .SS salt.states.alias -.SS Aliases File Management +.SS Configuration of email aliases. .sp The mail aliases file can be managed to contain definitions for specific email aliases: @@ -15578,7 +17483,7 @@ The forwarding address .UNINDENT .UNINDENT .SS salt.states.cmd -.SS Command Executions +.SS Execution of arbitrary commands. .sp The cmd state module manages the enforcement of executed commands, this state can tell a command to run under certain circumstances. @@ -15612,15 +17517,9 @@ syslog if there is no disk space: \- 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=()) +.B salt.states.cmd.mod_watch(name, onlyif=None, unless=None, cwd=\(aq/root\(aq, user=None, group=None, shell=None, env=()) Run a command if certain circumstances are met .INDENT 7.0 .TP @@ -15645,11 +17544,14 @@ The user name to run the command as .TP .B group The group context to run the command as +.TP +.B shell +The shell to use for execution, defaults to the shell grain .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=()) +.B salt.states.cmd.run(name, onlyif=None, unless=None, cwd=\(aq/root\(aq, user=None, group=None, shell=None, env=()) Run a command if certain circumstances are met .INDENT 7.0 .TP @@ -15674,11 +17576,14 @@ The user name to run the command as .TP .B group The group context to run the command as +.TP +.B shell +The shell to use for execution, defaults to the shell grain .UNINDENT .UNINDENT .INDENT 0.0 .TP -.B salt.states.cmd.wait(name, onlyif=None, unless=None, cwd=\(aq/root\(aq, user=None, group=None) +.B salt.states.cmd.wait(name, onlyif=None, unless=None, cwd=\(aq/root\(aq, user=None, group=None, shell=None) Run the given command only if the watch statement calls it .INDENT 7.0 .TP @@ -15703,10 +17608,13 @@ The user name to run the command as .TP .B group The group context to run the command as +.TP +.B shell +The shell to use for execution, defaults to /bin/sh .UNINDENT .UNINDENT .SS salt.states.cron -.SS Cron Management +.SS Management of cron, the Unix command scheduler. .sp The cron state module allows for user crontabs to be cleanly managed. .sp @@ -15813,10 +17721,10 @@ The information to be set in the day of day of week section. Default is .UNINDENT .UNINDENT .SS salt.states.file -.SS File Management +.SS Operations on files, directories and symlinks. .sp -Salt States can aggressively manipulate files on a system. There are a number of -ways in which files can be managed. +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. @@ -15952,7 +17860,7 @@ Usage: .ft C /etc/fstab: file.comment: - \- regex: ^//10.10.20.5 + \- regex: ^bind 127.0.0.1 .ft P .fi .sp @@ -15998,7 +17906,7 @@ Require other resources such as packages or files .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=None, **kwargs) +.B salt.states.file.managed(name, source=None, source_hash=\(aq\(aq, user=None, group=None, mode=None, template=None, makedirs=False, context=None, replace=True, defaults=None, env=None, **kwargs) 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 @@ -16045,6 +17953,10 @@ 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 replace +If this file should be replaced, if false then this command will +be ignored if the file exists already. Default is true. +.TP .B context Overrides default context variables passed to the template. .TP @@ -16054,7 +17966,7 @@ Default context passed to the template. .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=None, **kwargs) +.B salt.states.file.recurse(name, source, clean=False, require=None, user=None, group=None, dir_mode=None, file_mode=None, env=None, include_empty=False, **kwargs) Recurse through a subdirectory on the master and copy said subdirecory over to the specified path. .INDENT 7.0 @@ -16089,6 +18001,10 @@ The permissions mode to set any directories created .TP .B file_mode The permissions mode to set any files created +.TP +.B include_empty +Set this to True if empty directories should also be created +(default is False) .UNINDENT .UNINDENT .INDENT 0.0 @@ -16115,7 +18031,7 @@ Usage: # Remove ldap from nsswitch /etc/nsswitch.conf: -file.sed: + file.sed: \- before: \(aqldap\(aq \- after: \(aq\(aq \- limit: \(aq^passwd:\(aq @@ -16157,7 +18073,7 @@ Usage: .sp .nf .ft C -/var/log/httpd/logrotate.empty +/var/log/httpd/logrotate.empty: file.touch .ft P .fi @@ -16180,7 +18096,7 @@ Usage: New in version 0.9.5. .UNINDENT .SS salt.states.gem -.SS Management of rubygems +.SS Installation of Ruby modules packaged as gems. .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 @@ -16231,8 +18147,45 @@ None The user to run gem as. .UNINDENT .UNINDENT +.SS salt.states.git +.SS Interaction with Git repositories. +.sp +NOTE: This modules is under heavy development and the API is subject to change. +It may be replaced with a generic VCS module if this proves viable. +.sp +.nf +.ft C +https://github.com/saltstack/salt.git: + git: + \- latest + \- rev: develop + \- target: /tmp/salt +.ft P +.fi +.INDENT 0.0 +.TP +.B salt.states.git.latest(name, rev=None, target=None, runas=None, force=None) +Make sure the repository is cloned to the given directory and is up to date +.INDENT 7.0 +.TP +.B name +Address of the remote repository as passed to "git clone" +.TP +.B rev +The remote branch or revision to checkout after clone / before update +.TP +.B target +Name of the target directory where repository is about to be cloned +.TP +.B runas +Name of the user performing repository management operations +.TP +.B force +Force git to clone into pre\-existing directories (deletes contnents) +.UNINDENT +.UNINDENT .SS salt.states.group -.SS Group Management +.SS Management of user groups. .sp The group module is used to create and manage unix group settings, groups can be either present or absent: @@ -16243,6 +18196,7 @@ cheese: group: \- present \- gid: 7648 + \- system: True .ft P .fi .INDENT 0.0 @@ -16257,7 +18211,7 @@ The name of the group to remove .UNINDENT .INDENT 0.0 .TP -.B salt.states.group.present(name, gid=None) +.B salt.states.group.present(name, gid=None, system=False) Ensure that a group is present .INDENT 7.0 .TP @@ -16270,7 +18224,7 @@ available group id will be assigned .UNINDENT .UNINDENT .SS salt.states.host -.SS Hosts File Management +.SS Management of addresses and names in hosts file. .sp The hosts file can be managed to contain definitions for specific hosts: .sp @@ -16309,7 +18263,7 @@ The ip addr to apply to the host .UNINDENT .UNINDENT .SS salt.states.kmod -.SS Kernel Module Management +.SS Loading and unloading of kernel modules. .sp The Kernel modules on a system can be managed cleanly with the kmod state module: @@ -16345,7 +18299,7 @@ The name of the kernel module to verify is loaded .UNINDENT .UNINDENT .SS salt.states.mount -.SS Mount Management +.SS Mounting of filesystems. .sp Mount any type of mountable filesystem with the mounted function: .sp @@ -16402,10 +18356,10 @@ Set if the mount should be saved in the fstab, default to True .UNINDENT .UNINDENT .SS salt.states.mysql_database -.SS MySQL Database Management +.SS Management of MySQL databases (schemas). .sp -The mysql_database module is used to create and manage MySQL databases, databases can be set -as either absent or present +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 @@ -16435,7 +18389,7 @@ The name of the database to manage .UNINDENT .UNINDENT .SS salt.states.mysql_grants -.SS MySQL Grant Management +.SS Management of MySQL grants (user permissions). .sp The mysql_grants module is used to grant and revoke MySQL permissions. .sp @@ -16533,10 +18487,9 @@ Defines if the database value gets escaped or not. default: True .UNINDENT .UNINDENT .SS salt.states.mysql_user -.SS MySQL User Management +.SS Management of MySQL users. .sp -The mysql_database module is used to create and manage MySQL databases, databases can be set -as either absent or present +The mysql_user module is used manage MySQL users. .sp .nf .ft C @@ -16574,6 +18527,117 @@ The password in hashed form .UNINDENT .UNINDENT .SS salt.states.network +.SS Configuration of network interfaces. +.sp +The network module is used to create and manage network settings, +interfaces can be set as either managed or ignored. By default +all interfaces are ignored unless specified. +.sp +.nf +.ft C +eth0: + network: + \- managed + \- enabled: True + \- type: eth + \- proto: none + \- ipaddr: 10.1.0.1 + \- netmask: 255.255.255.0 + \- dns: + \- 8.8.8.8 + \- 8.8.4.4 +eth2: + network: + \- managed + \- type: slave + \- master: bond0 + +eth3: + network: + \- managed + \- type: slave + \- master: bond0 + +bond0: + network: + \- managed + \- type: bond + \- ipaddr: 10.1.0.1 + \- netmask: 255.255.255.0 + \- dns: + \- 8.8.8.8 + \- 8.8.4.4 + \- ipv6: + \- enabled: False + \- use_in: + \- network: eth2 + \- network: eth3 + \- require: + \- network: eth2 + \- network: eth3 + \- mode: 802.3ad + \- miimon: 100 + \- arp_interval: 250 + \- downdelay: 200 + \- lacp_rate: fast + \- max_bonds: 1 + \- updelay: 0 + \- use_carrier: on + \- xmit_hash_policy: layer2 + \- mtu: 9000 + \- autoneg: on + \- speed: 1000 + \- duplex: full + \- rx: on + \- tx: off + \- sg: on + \- tso: off + \- ufo: off + \- gso: off + \- gro: off + \- lro: off + +bond0.2: + network: + \- managed + \- type: vlan + \- ipaddr: 10.1.0.2 + \- use: + \- network: bond0 + \- require: + \- network: bond0 + +bond0.3: + network: + \- managed + \- type: vlan + \- ipaddr: 10.1.0.3 + \- use: + \- network: bond0 + \- require: + \- network: bond0 + +bond0.10: + network: + \- managed + \- type: vlan + \- ipaddr: 10.1.0.4 + \- use: + \- network: bond0 + \- require: + \- network: bond0 + +bond0.12: + network: + \- managed + \- type: vlan + \- ipaddr: 10.1.0.5 + \- use: + \- network: bond0 + \- require: + \- network: bond0 +.ft P +.fi .INDENT 0.0 .TP .B salt.states.network.managed(name, type, enabled=True, **kwargs) @@ -16594,7 +18658,7 @@ The IP parameters for this interface. .UNINDENT .UNINDENT .SS salt.states.pip -.SS Management of python packages +.SS Installation of Python packages using pip. .sp A state module to manage system installed python packages .sp @@ -16643,7 +18707,7 @@ the pip executable or virtualenenv to use .UNINDENT .UNINDENT .SS salt.states.pkg -.SS Package Management +.SS Installation of packages using OS package managers such as yum or apt\-get. .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 @@ -16697,9 +18761,9 @@ httpd: .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 +the package. Generally it is better for the \fBinstalled\fP function to be +used, as \fBlatest\fP will update the package whenever a new package is +available. .INDENT 7.0 .TP .B name @@ -16716,11 +18780,6 @@ Skip the GPG verification check for the package to be installed .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. @@ -16742,10 +18801,10 @@ The name of the package to be removed .UNINDENT .UNINDENT .SS salt.states.postgres_database -.SS Postgres Database Management +.SS Management of PostgreSQL databases (schemas). .sp -The postgres_database module is used to create and manage Postgres databases, databases can be set -as either absent or present +The postgres_database module is used to create and manage Postgres databases. +Databases can be set as either absent or present .sp .nf .ft C @@ -16775,7 +18834,7 @@ The name of the database to manage .UNINDENT .UNINDENT .SS salt.states.rvm -.SS Management of ruby installations and gemsets with RVM +.SS Management of Ruby installations and gemsets with RVM, the Ruby Version Manager. .sp This module is used to install and manage ruby installations and gemsets with RVM, the Ruby Version Manager. Different versions of ruby @@ -16922,8 +18981,53 @@ None The user to run rvm as. .UNINDENT .UNINDENT +.SS salt.states.selinux +.SS Management of SELinux rules. +.sp +If SELinux is available for the running system, the mode can be managed and +booleans can be set. +.sp +.nf +.ft C +enforcing: + selinux.mode + +samba_create_home_dirs: + selinx.boolean: + \- value: True + \- persist: True +.ft P +.fi +.INDENT 0.0 +.TP +.B salt.states.selinux.boolean(name, value, persist=False) +Set up an SELinux boolean +.INDENT 7.0 +.TP +.B name +The name of the boolean to set +.TP +.B value +The value to set on the boolean +.TP +.B persist +Defaults to False, set persist to true to make the boolean apply on a +reboot +.UNINDENT +.UNINDENT +.INDENT 0.0 +.TP +.B salt.states.selinux.mode(name) +Verifies the mode SELinux is running in, can be set to enforcing or +permissive +.INDENT 7.0 +.TP +.B name +The mode to run SELinux in, permissive or enforcing +.UNINDENT +.UNINDENT .SS salt.states.service -.SS Service Management +.SS Starting or restarting of services and daemons. .sp Services are defined as system daemons typically started with system init or rc scripts, services can be defined as running or dead. @@ -16981,7 +19085,7 @@ The name of the init or rc script used to manage the service .UNINDENT .INDENT 0.0 .TP -.B salt.states.service.mod_watch(name, sig=None) +.B salt.states.service.mod_watch(name, sig=None, reload=False) The service watcher, called to invoke the watch command. .INDENT 7.0 .TP @@ -17011,7 +19115,7 @@ 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 +.SS Control of entries in SSH authorized_key files. .sp The information stored in a user\(aqs ssh authorized key file can be easily controlled via the ssh_auth state. Defaults can be set by the enc, options, @@ -17067,7 +19171,7 @@ directory, defaults to ".ssh/authorized_keys" .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) +.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, **kwargs) Verifies that the specified ssh key is present for the specified user .INDENT 7.0 .TP @@ -17096,8 +19200,73 @@ The location of the authorized keys file relative to the user\(aqs home directory, defaults to ".ssh/authorized_keys" .UNINDENT .UNINDENT +.SS salt.states.ssh_known_hosts +.SS Control of SSH known_hosts entries. +.sp +Manage the information stored in the known_hosts files +.sp +.nf +.ft C +github.com: + ssh_known_hosts: + \- present + \- user: root + \- fingerprint: 16:27:ac:a5:76:28:2d:36:63:1b:56:4d:eb:df:a6:48 + +example.com: + ssh_known_hosts: + \- absent + \- user: root +.ft P +.fi +.INDENT 0.0 +.TP +.B salt.states.ssh_known_hosts.absent(name, user, config=\(aq.ssh/known_hosts\(aq) +Verifies that the specified host is not known by the given user +.INDENT 7.0 +.TP +.B name +The host name +.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/known_hosts" +.UNINDENT +.UNINDENT +.INDENT 0.0 +.TP +.B salt.states.ssh_known_hosts.present(name, user, fingerprint=None, port=None, enc=None, config=\(aq.ssh/known_hosts\(aq) +Verifies that the specified host is known by the specified user +.INDENT 7.0 +.TP +.B name +The name of the remote host (i.e. "github.com") +.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 fingerprint +The fingerprint of the key which must be presented in the known_hosts +file +.TP +.B port +optional parameter, denoting the port of the remote host, which will be +used in case, if the public key will be requested from it. By default +the port 22 is used. +.TP +.B config +The location of the authorized keys file relative to the user\(aqs home +directory, defaults to ".ssh/known_hosts" +.UNINDENT +.UNINDENT .SS salt.states.sysctl -.SS Kernel Sysctl Management +.SS Configuration of the Linux kernel using sysctrl. .sp Control the kernel sysctl system .sp @@ -17126,7 +19295,7 @@ The location of the sysctl configuration file .UNINDENT .UNINDENT .SS salt.states.user -.SS User Management +.SS Management of user accounts. .sp The user module is used to create and manage user settings, users can be set as either absent or present @@ -17166,7 +19335,7 @@ option to True to remove the user even if they are logged in .UNINDENT .INDENT 0.0 .TP -.B salt.states.user.present(name, uid=None, gid=None, groups=None, home=True, password=None, enforce_password=True, shell=None, fullname=None, roomnumber=None, workphone=None, homephone=None, other=None, unique=True) +.B salt.states.user.present(name, uid=None, gid=None, groups=None, home=True, password=None, enforce_password=True, shell=None, fullname=None, roomnumber=None, workphone=None, homephone=None, other=None, unique=True, system=False) Ensure that the named user is present with the specified properties .INDENT 7.0 .TP @@ -17223,11 +19392,13 @@ The user\(aqs "other" GECOS field .TP .B unique Require a unique UID, True by default +.TP +.B system +Choose UID in the range of FIRST_SYSTEM_UID and LAST_SYSTEM_UID. .UNINDENT .UNINDENT .SS salt.states.virtualenv -.sp -virtualenv management +.SS Setup of Python virtualenv sandboxes. .INDENT 0.0 .TP .B salt.states.virtualenv.managed(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, cwd=None) @@ -17251,15 +19422,15 @@ Also accepts any kwargs that the virtualenv module will. .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 +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 +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. +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 +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. @@ -17269,13 +19440,13 @@ 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 +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: +use the Python or \fBpy\fP renderer: .sp .nf .ft C @@ -17293,9 +19464,9 @@ def run(): 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 +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. +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 @@ -17303,13 +19474,13 @@ derived from the file. 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.9/salt/renderers\fP +\fI\%https://github.com/saltstack/salt/blob/v0.10.0/salt/renderers\fP .sp -Here is a simple jinja + yaml example: +Here is a simple Jinja + YAML example: .sp .nf .ft C -# Import python libs +# Import Python libs import os # Import Third Party libs @@ -17336,31 +19507,31 @@ center; |l|l|. _ T{ -\fBsalt.renderers.json_jinja\fP +\fBjson_jinja\fP T} T{ Process json with the jinja2 templating engine T} _ T{ -\fBsalt.renderers.json_mako\fP +\fBjson_mako\fP T} T{ Process json with the Mako templating engine T} _ T{ -\fBsalt.renderers.yaml_jinja\fP +\fByaml_jinja\fP T} T{ The default rendering engine, process yaml with the jinja2 templating engine T} _ T{ -\fBsalt.renderers.yaml_mako\fP +\fByaml_mako\fP T} T{ Process yaml with the Mako templating engine T} _ T{ -\fBsalt.renderers.py\fP +\fBpy\fP T} T{ Pure python state renderer T} @@ -17385,7 +19556,7 @@ 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) +.B salt.renderers.json_mako.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_jinja @@ -17407,7 +19578,7 @@ 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) +.B salt.renderers.yaml_mako.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.py @@ -17427,17 +19598,17 @@ 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. +The use for a Salt runner 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. +A runner is a Python module that contains functions, each public function is +a runner that can be executed via the \fIsalt\-run\fP command. .sp -If a python module named test.py is created in the runners directory and +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 @@ -17449,10 +19620,10 @@ contains a function called \fBfoo\fP then the function could be called with: .sp The best examples of runners can be found in the Salt source: .sp -\fI\%https://github.com/saltstack/salt/blob/v0.9.9/salt/runners\fP +\fI\%https://github.com/saltstack/salt/blob/v0.10.0/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: +responding to Salt calls would look like this: .sp .nf .ft C @@ -17471,21 +19642,27 @@ def up(): .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. +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. +In Salt 1.0 the ability to execute runners from the master was added. This +allows for the master to return collective data from runners back to the +minions via the peer interface. +.sp +The peer interface is configured through two options in the master +configuration file. For minions to send commands from the master the \fBpeer\fP +configuration is used. To allow for minions to execute runners from the master +the \fBpeer_run\fP configuration is used. .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 +expressions. Minions with specific ids can be allowed access to certain Salt modules and functions. -.SS Configuration +.SS Peer Configuration .sp -The configuration is done under the peer setting in the salt master +The configuration is done under the \fBpeer\fP 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 @@ -17499,35 +19676,85 @@ 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. +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 +.SS Peer Runner Communication +.sp +Configuration to allow minions to execute runners from the master is done via +the \fBpeer_run\fP option on the master. The \fBpeer_run\fP configuration follows +the same logic as the \fBpeer\fP option. The only difference is that access is +granted to runner modules. +.sp +To open up access to all minions to all runners: +.sp +.nf +.ft C +peer_run: + .*: + \- .* +.ft P +.fi +.sp +This configuration will allow minions with IDs ending in example.com access +to the manage and jobs runner functions. +.sp +.nf +.ft C +peer_run: + .*example.com: + \- manage.* + \- jobs.* +.ft P +.fi +.SS Using Peer Communiction +.sp +The publish module was created to manage peer communication. The publish module +comes with a number of functions to execute peer communication in different +ways. Currently there are three functions in the publish module. These examples +will show how to test the peer system via the salt\-call command. +.sp +To execute test.ping on all minions: .sp .nf .ft C -peer: - .*example.com: - \- test.* - \- ps.* - \- pkg.* +# salt\-call publish.publish \e* test.ping .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. +To execute the manage.up runner: .sp .nf .ft C -peer: - .*example.com: - \- test.* - \- ps.* - \- pkg.* - .*foo.org: - \- test.* - \- ps.* - \- pkg.* +# salt\-call publish.runner manage.up .ft P .fi .SH SALT SYNDIC @@ -17574,13 +19801,16 @@ starting the other Salt daemons. 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. +.sp +A number of client command methods are available depending on the exact +behaviour desired. .SS Using the LocalClient API .sp Sending information through the client is simple: .sp .nf .ft C -# Import the salt client library +# Import the Salt client library import salt.client # create a local client object client = salt.client.LocalClient() @@ -17589,22 +19819,216 @@ 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: +The LocalClient object only works running as root on the salt\-master, it is the +same interface used by the \fBsalt\fP command line tool. .INDENT 0.0 .TP -.B LocalClient.cmd(tgt, fun, arg=[], timeout=5, expr_form=\(aqglob\(aq) +.B LocalClient.cmd(tgt, fun, arg=[], timeout=5, expr_form=\(aqglob\(aq, ret=\(aq\(aq) +The cmd method will execute and wait for the timeout period for all minions +to reply, then it will return all minion data at once. +.UNINDENT +.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 +.IP \(bu 2 +\(aqgrain\(aq \- Match based on a grain comparison +.IP \(bu 2 +\(aqgrain_pcre\(aq \- Grain comparison with a regex +.IP \(bu 2 +\(aqpillar\(aq \- Pillar data comparison +.IP \(bu 2 +\(aqnodegroup\(aq \- Match on nodegroup +.IP \(bu 2 +\(aqrange\(aq \- Use a Range server for matching +.IP \(bu 2 +\(aqcompound\(aq \- Pass a compound match string +.UNINDENT +.UNINDENT +.INDENT 0.0 +.TP +.B ret +Specify the returner to use. The value passed can be single returner, or +a comma delimited list of returners to call in order on the minions +.UNINDENT +.INDENT 0.0 +.TP +.B LocalClient.cmd_cli(tgt, fun, arg=[], timeout=5, verbose=False, expr_form=\(aqglob\(aq, ret=\(aq\(aq) +The cmd_cli method is used by the salt command, it is a generator. This +method returns minion returns as the come back and attempts to block +until all minions return. +.UNINDENT +.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 +.IP \(bu 2 +\(aqgrain\(aq \- Match based on a grain comparison +.IP \(bu 2 +\(aqgrain_pcre\(aq \- Grain comparison with a regex +.IP \(bu 2 +\(aqpillar\(aq \- Pillar data comparison +.IP \(bu 2 +\(aqnodegroup\(aq \- Match on nodegroup +.IP \(bu 2 +\(aqrange\(aq \- Use a Range server for matching +.IP \(bu 2 +\(aqcompound\(aq \- Pass a compound match string +.UNINDENT +.UNINDENT +.INDENT 0.0 +.TP +.B ret +Specify the returner to use. The value passed can be single returner, or +a comma delimited list of returners to call in order on the minions +.UNINDENT +.INDENT 0.0 +.TP +.B verbose +Print extra information about the running command to the terminal +.UNINDENT +.INDENT 0.0 +.TP +.B LocalClient.cmd_iter(tgt, fun, arg=[], timeout=5, expr_form=\(aqglob\(aq, ret=\(aq\(aq) +The cmd_iter method is a generator which yields the individual minion +returns as the come in. +.UNINDENT +.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 +.IP \(bu 2 +\(aqgrain\(aq \- Match based on a grain comparison +.IP \(bu 2 +\(aqgrain_pcre\(aq \- Grain comparison with a regex +.IP \(bu 2 +\(aqpillar\(aq \- Pillar data comparison +.IP \(bu 2 +\(aqnodegroup\(aq \- Match on nodegroup +.IP \(bu 2 +\(aqrange\(aq \- Use a Range server for matching +.IP \(bu 2 +\(aqcompound\(aq \- Pass a compound match string +.UNINDENT +.UNINDENT +.INDENT 0.0 +.TP +.B ret +Specify the returner to use. The value passed can be single returner, or +a comma delimited list of returners to call in order on the minions +.UNINDENT +.INDENT 0.0 +.TP +.B LocalClient.cmd_iter_no_block(tgt, fun, arg=[], timeout=5, expr_form=\(aqglob\(aq, ret=\(aq\(aq) +The cmd_iter method will block waiting for individual minions to return, +the cmd_iter_no_block method will return None until the next minion +returns. This allows for actions to be injected in between minion returns .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. +as either a pcre regular expression or as a Python list. .UNINDENT .INDENT 0.0 .TP @@ -17636,13 +20060,31 @@ The type of tgt that is passed in, the allowed values are: \(aqpcre\(aq \- Perl style regular expression .IP \(bu 2 \(aqlist\(aq \- Python list of hosts +.IP \(bu 2 +\(aqgrain\(aq \- Match based on a grain comparison +.IP \(bu 2 +\(aqgrain_pcre\(aq \- Grain comparison with a regex +.IP \(bu 2 +\(aqpillar\(aq \- Pillar data comparison +.IP \(bu 2 +\(aqnodegroup\(aq \- Match on nodegroup +.IP \(bu 2 +\(aqrange\(aq \- Use a Range server for matching +.IP \(bu 2 +\(aqcompound\(aq \- Pass a compound match string +.UNINDENT .UNINDENT +.INDENT 0.0 +.TP +.B ret +Specify the returner to use. The value passed can be single returner, or +a comma delimited list of returners to call in order on the minions .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 +than send the commands one after another, they can be sent in a single publish containing a series of commands. This can dramatically lower overhead and speed up the application communicating with Salt. .sp @@ -17656,9 +20098,11 @@ 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 +All client command methods can execute compound commands. +.sp .nf .ft C -# Import the salt client library +# Import the Salt client library import salt.client # create a local client object client = salt.client.LocalClient() @@ -17681,10 +20125,10 @@ The return data from the minion will look like this: .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. +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 +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 @@ -17709,7 +20153,7 @@ the master, the syntax looks like this: .ft P .fi .sp -This will instruct all salt minions to download the vimrc file and copy it +This will instruct all Salt minions to download the vimrc file and copy it to /etc/vimrc .SS File Server Client API .sp @@ -17731,7 +20175,7 @@ import salt.minion def get_file(path, dest, env=\(aqbase\(aq): \(aq\(aq\(aq - Used to get a single file from the salt master + Used to get a single file from the Salt master CLI Example: salt \(aq*\(aq cp.get_file salt://vimrc /etc/vimrc @@ -17753,7 +20197,7 @@ import salt.config def get_file(path, dest, env=\(aqbase\(aq): \(aq\(aq\(aq - Used to get a single file from the salt master + 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) @@ -17803,7 +20247,7 @@ file_roots: .ft P .fi .sp -If a file\(aqs uri is \fBsalt://httpd/httpd.conf\fP, it will first search for the +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. @@ -17815,7 +20259,7 @@ they are defined in the configuration. 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 +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 @@ -17824,7 +20268,7 @@ option to local to make sure that the local file server interface is used. .sp New in version 0.9.5. .sp -Salt python modules can be distributed automatically via the salt file server. +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 @@ -17847,7 +20291,7 @@ _states .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 +Python modules have been created in them. There are a number of ways to sync the modules. .SS Sync Via States .sp @@ -17855,6 +20299,13 @@ 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. +.sp +When dynamic modules are autoloaded via states, modules only pertinent to +the environments matched in the master\(aqs top file are downloaded. +.sp +This is important to remember, because modules can be manually loaded from +any specific environment that environment specific modules will be loaded +when a state run is executed. .SS Sync Via the saltutil Module .sp The saltutil module has a number of functions that can be used to sync all @@ -17912,6 +20363,13 @@ will sync all module types over to a minion. For more information see: # Set the directory used to hold unix sockets #sock_dir: /tmp/salt\-unix +# The master maintains a job cache, while this is a great addition it can be +# a burden on the master for larger deployments (over 5000 minions). +# Disabling the job cache will make previously executed jobs unavailable to +# the jobs system and is not generally recommended. +# +#job_cache: True + # 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 @@ -17933,11 +20391,21 @@ will sync all module types over to a minion. For more information see: # public keys from the minions. Note that this is insecure. #auto_accept: False +##### Master Module Management ##### +########################################## +# Manage how master side modules are loaded +# +# Add any additional locations to look for master runners +#runner_dirs: [] +# +#Enable Cython for master side modules +#cython_enable: 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. +# root of the base environment as defined in "File Server settings" below. #state_top: top.sls # # The external_nodes option allows Salt to gather data that would normally be @@ -18011,7 +20479,7 @@ will sync all module types over to a minion. For more information see: # 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. +# to receive commands from. # # Set the order_masters setting to True if this master will command lower # masters\(aq syndic interfaces. @@ -18044,6 +20512,24 @@ will sync all module types over to a minion. For more information see: # 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! # +# Minions can also be allowed to execute runners from the salt master. +# Since executing a runner from the minion could be considered a security risk, +# it needs to be enabled. This setting functions just like the peer setting +# except that it opens up runners instead of module functions. +# +# All peer runner support is turned off by default and must be enabled before +# using. This will enable all peer runners for all minions: +# +# peer_run: +# .*: +# \- .* +# +# To enable just the manage.up runner for the minion foo.example.com: +# +# peer_run: +# foo.example.com: +# \- manage.up +# ##### Cluster settings ##### ########################################## @@ -18204,7 +20690,7 @@ will sync all module types over to a minion. For more information see: #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 +# 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 #state_verbose: False @@ -18440,6 +20926,16 @@ cachedir: /var/cache/salt Default: \fB24\fP .sp Set the number of hours to keep old job information +.SS \fBjob_cache\fP +.sp +Default: \fBTrue\fP +.sp +The master maintains a job cache, while this is a great addition it can be +a burden on the master for larger deployments (over 5000 minions). +Disabling the job cache will make previously executed jobs unavailable to +the jobs system and is not generally recommended. Normally it is wise to make +sure the master has access to a faster IO system or a tmpfs is mounted to the +jobs dir .SS \fBsock_dir\fP .sp Default:: \fB/tmp/salt\-unix\fP @@ -18476,6 +20972,24 @@ public keys from the minions auto_accept: False .ft P .fi +.SS Master Module Management +.SS \fBrunner_dirs\fP +.sp +Default: \fB[]\fP +.sp +Set additional directories to search for runner modules +.SS \fBcython_enable\fP +.sp +Default: \fBFalse\fP +.sp +Set to true to enable cython modules (.pyx files) to be compiled on the fly on +the Salt master +.sp +.nf +.ft C +cython_enable: False +.ft P +.fi .SS Master State System Settings .SS \fBstate_top\fP .sp @@ -18548,6 +21062,7 @@ Default: \fBbase: [/srv/salt]\fP 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. +.sp 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 @@ -18708,6 +21223,24 @@ peer: .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 \fBpeer_run\fP +.sp +Default: \fB{}\fP +.sp +The peer_run option is used to open up runners on the master to access from the +minions. The peer_run configuration matches the format of the peer +configuration. +.sp +The following example would allow foo.example.com to execute the manage.up +runner: +.sp +.nf +.ft C +peer_run: + foo.example.com: + \- manage.up +.ft P +.fi .SS Node Groups .sp Default: \fB{}\fP @@ -18751,7 +21284,7 @@ log_level: warning 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 +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 @@ -18791,7 +21324,7 @@ master: salt Default: \fB4506\fP .sp The port of the master ret server, this needs to coincide with the ret_port -option on the salt master. +option on the Salt master. .sp .nf .ft C @@ -18825,9 +21358,9 @@ pki_dir: /etc/salt/pki 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 +will be the hostname as returned by the Python call: \fBsocket.getfqdn()\fP +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 @@ -18918,7 +21451,7 @@ disable_returners: .sp Default: \fB[]\fP .sp -A list of extra directories to search for salt modules +A list of extra directories to search for Salt modules .sp .nf .ft C @@ -18930,7 +21463,7 @@ module_dirs: .sp Default: \fB[]\fP .sp -A list of extra directories to search for salt returners +A list of extra directories to search for Salt returners .sp .nf .ft C @@ -18942,7 +21475,7 @@ returners_dirs: .sp Default: \fB[]\fP .sp -A list of extra directories to search for salt states +A list of extra directories to search for Salt states .sp .nf .ft C @@ -18954,7 +21487,7 @@ states_dirs: .sp Default: \fB[]\fP .sp -A list of extra directories to search for salt renderers +A list of extra directories to search for Salt renderers .sp .nf .ft C @@ -18966,8 +21499,8 @@ render_dirs: .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 +Set this value to true to enable auto\-loading and compiling of \fB.pyx\fP modules, +This setting requires that \fBgcc\fP and \fBcython\fP are installed on the minion .sp .nf .ft C @@ -18992,7 +21525,7 @@ 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 +returned, but setting state_verbose to \fBTrue\fP will return all states that were checked .sp .nf @@ -19006,7 +21539,7 @@ 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 +autoloading modules when states run set this value to \fBFalse\fP .sp .nf .ft C @@ -19019,7 +21552,7 @@ Default: \fBTrue\fP 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 +enabled and can be disabled by changing this value to \fBFalse\fP .sp .nf .ft C @@ -19045,7 +21578,7 @@ environment: None .sp Default: \fBFalse\fP .sp -Open mode can be used to clean out the pki key received from the salt master, +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 @@ -19058,7 +21591,7 @@ open_mode: False .sp Default: \fBTrue\fP .sp -Disable multiprocessing support, by default when a minion receives a +Disable multiprocessing support by default when a minion receives a publication a new process is spawned and the command is executed therein. .sp .nf @@ -19095,7 +21628,7 @@ log_level: warning 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 +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 @@ -19124,7 +21657,7 @@ environment variables \fBSALT_MASTER_CONFIG\fP and \fBSALT_MINION_CONFIG\fP. .RE .SS Using the Salt Command .sp -The Salt command needs a few components to send information to the salt +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 @@ -19303,7 +21836,7 @@ Print a usage message briefly summarizing these command\-line options .INDENT 0.0 .TP .B \-t TIMEOUT, \-\-timeout=TIMEOUT -The timeout in seconds to wait for replies from the salt minions. +The timeout in seconds to wait for replies from the Salt minions. .UNINDENT .INDENT 0.0 .TP @@ -19324,7 +21857,7 @@ minions to execute on. .INDENT 0.0 .TP .B \-\-version -Print the version of salt that is running. +Print the version of Salt that is running. .UNINDENT .INDENT 0.0 .TP @@ -19341,7 +21874,7 @@ example: server1.foo.bar,server2.foo.bar,example7.quo.qux .INDENT 0.0 .TP .B \-G, \-\-grain -The target expression matches values returned by the salt grains system on +The target expression matches values returned by the Salt grains system on the minions. The target expression is in the format of \(aq:\(aq; example: \(aqos:Arch*\(aq .sp @@ -19352,7 +21885,7 @@ the \-\-grain\-pcre option. .INDENT 0.0 .TP .B \-\-grain\-pcre -The target expression matches values returned by the salt grains system on +The target expression matches values returned by the Salt grains system on the minions. The target expression is in the format of \(aq:< regular expression>\(aq; example: \(aqos:Arch.*\(aq .UNINDENT @@ -19373,7 +21906,7 @@ Instead of using shell globs use the return code of a function. .INDENT 0.0 .TP .B \-N, \-\-nodegroup -Use a predefined compound target defined in the salt master configuration +Use a predefined compound target defined in the Salt master configuration file .UNINDENT .INDENT 0.0 @@ -19397,7 +21930,7 @@ but will be sent to the specified return system. .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 +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 @@ -19406,16 +21939,16 @@ previous function call: \-Q test.echo\(aq) .INDENT 0.0 .TP .B \-c CONFIG, \-\-config=CONFIG -The location of the salt master configuration file, the salt master +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 +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. +an executing Python script with eval. .UNINDENT .INDENT 0.0 .TP @@ -19426,12 +21959,12 @@ form the shell would. .INDENT 0.0 .TP .B \-\-yaml\-out -Print the output from the salt command in yaml. +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. +Print the output from the salt command in JSON. .UNINDENT .INDENT 0.0 .TP @@ -19445,13 +21978,13 @@ Disable all colored output \fIsalt\-minion(1)\fP .SH SALT-MASTER .sp -The salt master daemon, used to control the salt minions +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 +The master daemon controls the Salt minions .SS Options .INDENT 0.0 .TP @@ -19461,7 +21994,7 @@ Print a usage message briefly summarizing these command\-line options. .INDENT 0.0 .TP .B \-d, \-\-daemon -Run the salt master as a daemon +Run the Salt master as a daemon .UNINDENT .INDENT 0.0 .TP @@ -19492,13 +22025,13 @@ settings see the config file. Default: \fBwarning\fP. \fIsalt\-minion(1)\fP .SH SALT-MINION .sp -The salt minion daemon, receives commands from a remote salt master. +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 Salt minion receives commands from the central Salt master and replies with the results of said commands. .SS Options .INDENT 0.0 @@ -19509,7 +22042,7 @@ Print a usage message briefly summarizing these command\-line options. .INDENT 0.0 .TP .B \-d, \-\-daemon -Run the salt minion as a daemon +Run the Salt minion as a daemon .UNINDENT .INDENT 0.0 .TP @@ -19544,7 +22077,7 @@ settings see the config file. Default: \fBwarning\fP. salt\-key [ options ] .SS Description .sp -Salt\-key executes simple management of salt server public keys used for +Salt\-key executes simple management of Salt server public keys used for authentication. .SS Options .INDENT 0.0 @@ -19560,7 +22093,7 @@ List the unaccepted minion public keys. .INDENT 0.0 .TP .B \-L, \-\-list\-all -List all public keys on this salt master: accepted, pending, +List all public keys on this Salt master: accepted, pending, and rejected. .UNINDENT .INDENT 0.0 @@ -19596,7 +22129,7 @@ Deleta all keys .INDENT 0.0 .TP .B \-c CONFIG, \-\-config=CONFIG -The master configuration file needs to be read to determine where the salt +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 @@ -19616,7 +22149,7 @@ salt\-cp \-G \(aqos:Arch.*\(aq [ options ] SOURCE DEST .fi .SS Description .sp -Salt copy copies a local file out to all of the salt minions matched by the +Salt copy copies a local file out to all of the Salt minions matched by the given target. .SS Options .INDENT 0.0 @@ -19627,12 +22160,12 @@ Print a usage message briefly summarizing these command\-line options .INDENT 0.0 .TP .B \-t TIMEOUT, \-\-timeout=TIMEOUT -The timeout in seconds to wait for replies from the salt minions. +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 +The target expression will be interpreted as a PCRE regular expression rather than a shell glob. .UNINDENT .INDENT 0.0 @@ -19644,14 +22177,14 @@ example: server1.foo.bar,server2.foo.bar,example7.quo.qux .INDENT 0.0 .TP .B \-G, \-\-grain -The target expression matches values returned by the salt grains system on +The target expression matches values returned by the Salt grains system on the minions. The target expression is in the format of \(aq:\(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 target expression matches values returned by the Salt grains system on the minions. The target expression is in the format of \(aq:\(aq; example: \(aqos:Arch.*\(aq .UNINDENT @@ -19677,7 +22210,7 @@ make sure that the compound target is encapsulated in quotes. .INDENT 0.0 .TP .B \-c CONFIG, \-\-config=CONFIG -The location of the salt master configuration file, the salt master +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 @@ -19703,7 +22236,7 @@ Print a usage message briefly summarizing these command\-line options .INDENT 0.0 .TP .B \-g, \-\-grains -Return the information generated by the salt grains +Return the information generated by the Salt grains .UNINDENT .INDENT 0.0 .TP @@ -19714,7 +22247,7 @@ directories can be delimited by commas .INDENT 0.0 .TP .B \-d, \-\-doc -Return the documentation for the specified module of for all modules if +Return the documentation for the specified module or for all modules if none are specified .UNINDENT .INDENT 0.0 @@ -19727,9 +22260,9 @@ settings see the config file. Default: \fBinfo\fP. .INDENT 0.0 .TP .B \-\-raw\-out -Print the output from the salt command in raw python +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. +an executing Python script with eval. .UNINDENT .INDENT 0.0 .TP @@ -19740,12 +22273,12 @@ form the shell would. .INDENT 0.0 .TP .B \-\-yaml\-out -Print the output from the salt command in yaml. +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. +Print the output from the salt command in JSON. .UNINDENT .INDENT 0.0 .TP @@ -19781,7 +22314,7 @@ Print a usage message briefly summarizing these command\-line options .INDENT 0.0 .TP .B \-c CONFIG, \-\-config=CONFIG -The location of the salt master configuration file, the salt master +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 @@ -19792,14 +22325,14 @@ default=/etc/salt/master \fIsalt\-minion(1)\fP .SH SALT-SYNDIC .sp -The salt syndic daemon, a special minion that passes through commands from a +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 +The Salt syndic daemon, a special minion that passes through commands from a higher master. .SS Options .INDENT 0.0 @@ -19810,7 +22343,7 @@ Print a usage message briefly summarizing these command\-line options. .INDENT 0.0 .TP .B \-d, \-\-daemon -Run the salt syndic as a daemon +Run the Salt syndic as a daemon .UNINDENT .INDENT 0.0 .TP @@ -19846,7 +22379,7 @@ 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: +The message itself is abstracted as a Python dict in this fashion: .sp .nf .ft C @@ -19905,9 +22438,9 @@ 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.9/salt/master.py\fP +\fI\%https://github.com/saltstack/salt/blob/v0.10.0/salt/master.py\fP The regular minion authentication is managed via the salt.crypt module: -\fI\%https://github.com/saltstack/salt/blob/v0.9.9/salt/crypt.py\fP +\fI\%https://github.com/saltstack/salt/blob/v0.10.0/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 @@ -19920,6 +22453,82 @@ 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 RELEASE NOTES AND UPGRADE INSTRUCTIONS +.SS Salt 0.10.0 Release Notes +.sp +0.10.0 has arrived! This release comes with MANY bug fixes, and new +capabilities which greatly enhance performance and reliability. This +release is primarily a bug fix release with many new tests and many repaired +bugs. This release also introduces a few new key features which were brought +in primarily to repair bugs and some limitations found in some of the +components of the original architecture. +.SS Major Features +.SS Event System +.sp +The Salt Master now comes equipped with a new event system. This event system +has replaced some of the back end of the Salt client and offers the beginning of +a system which will make plugging external applications into Salt. The event +system relies on a local zeromq publish socket and other processes can connect +to this socket and listen for events. The new events can be easily managed via +Salt\(aqs event library. +.SS Unprivileged User Updates +.sp +Some enhancements have been added to Salt for running as a user other than +root. These new additions should make switching the user that the Salt Master +is running as very painless, simply change the \fBuser\fP option in the master +configuration and restart the master, Salt will take care of all of the +particulars for you. +.SS Peer Runner Execution +.sp +Salt has long had the peer communication system used to allow minions to send +commands via the salt master. 0.10.0 adds a new capability here, now the +master can be configured to allow for minions to execute Salt runners via +the \fBpeer_run\fP option in the salt master configuration. +.SS YAML Parsing Updates +.sp +In the past the YAML parser for sls files would return the incorrect numbers +when the file mode was set with a preceding 0. The yaml parser used in Salt +has been modified to no longer convert these number into octal but to keep +them as the correct value so that sls files can be a little cleaner to write. +.SS State Call Data Files +.sp +It was requested that the minion keep a local cache of the most recent executed +state run. This has been added and now with state runs the data is stored in a +msgpack file in the minion\(aqs cachedir. +.SS Turning Off the Job Cache +.sp +A new option has been added to the master configuration file. In previous +releases the Salt client would look over the Salt job cache to read in +the minion return data. With the addition of the event system the Salt client +can now watch for events directly from the master worker processes. +.sp +This means that the job cache is no longer a hard requirement. Keep in mind +though, that turning off the job cache means that historic job execution data +cannot be retrieved. +.SS Test Updates +.SS Minion Swarms Are Faster +.sp +To continue our efforts with testing Salt\(aqs ability to scale the minionswarm +script has been updated. The minionswarm can now start up minions much faster +than it could before and comes with a new feature allowing modules to be +disabled, thus lowering the minion\(aqs footprint when making a swarm. These new +updates have allows us to test +.sp +.nf +.ft C +# python minionswarm.py \-m 20 \-\-master salt\-master +.ft P +.fi +.SS Many Fixes +.sp +To get a good idea for the number of bugfixes this release offers take a look +at the closed tickets for 0.10.0, this is a very substantial update: +.sp +\fI\%https://github.com/saltstack/salt/issues?milestone=12&state=closed\fP +.SS Master and Minion Stability Fixes +.sp +As Salt deployments grow new ways to break Salt are discovered. 0.10.0 comes +with a number of fixes for the minions and master greatly improving Salt +stability. .SS Salt 0.6.0 release notes .sp The Salt remote execution manager has reached initial functionality! Salt is a @@ -19952,7 +22561,7 @@ 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 +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 @@ -20083,7 +22692,7 @@ Dynamic returners .sp Faster return handling .sp -Lowered required python version to 2.6 +Lowered required Python version to 2.6 .sp Advanced minion threading .sp @@ -20103,8 +22712,8 @@ 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, +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 @@ -20113,7 +22722,7 @@ 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.9/salt/modules/cytest.pyx\fP +\fI\%https://github.com/saltstack/salt/blob/v0.10.0/salt/modules/cytest.pyx\fP .SS Dynamic Returners \- .sp By default salt returns command data back to the salt master, but now salt can @@ -20127,10 +22736,10 @@ 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.9/salt/returners\fP +\fI\%https://github.com/saltstack/salt/blob/v0.10.0/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. +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 @@ -20143,26 +22752,26 @@ Information on how to use this simple addition has been added to the wiki: 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.9/salt/modules/test.py\fP +\fI\%https://github.com/saltstack/salt/blob/v0.10.0/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 +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 +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. +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.9/conf/minion\fP +\fI\%https://github.com/saltstack/salt/blob/v0.10.0/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. +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 @@ -20233,7 +22842,7 @@ 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.9/salt/loader.py\fP +\fI\%https://github.com/saltstack/salt/blob/v0.10.0/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. @@ -20509,7 +23118,7 @@ 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.9/salt/master.py\fP +\fI\%https://github.com/saltstack/salt/blob/v0.10.0/salt/master.py\fP .sp The \fBMaster\fP class extends the \fBSMaster\fP class and set up the main master server. @@ -20517,7 +23126,7 @@ server. 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.9/salt/minion.py\fP +\fI\%https://github.com/saltstack/salt/blob/v0.10.0/salt/minion.py\fP .SS Cleaner Key Management .sp This release changes some of the key naming to allow for multiple master keys @@ -20565,7 +23174,7 @@ git repo is growing with example of how to use states. 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. +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: @@ -20711,7 +23320,7 @@ displays this new capability. .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: +write Salt States in pure Python: .sp .nf .ft C @@ -20727,9 +23336,9 @@ def run(): .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. +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: +This example of a pure Python sls module is the same as this example in yaml: .sp .nf .ft C @@ -21126,13 +23735,13 @@ 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 +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 +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 @@ -21285,7 +23894,7 @@ 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. +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. @@ -21380,7 +23989,7 @@ 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 +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 @@ -21398,8 +24007,8 @@ Salt can now manage local users on Microsoft Windows Systems .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. +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. @@ -21415,7 +24024,7 @@ The mysql states are thanks to syphernl The mysql_user state enables mysql user management. .SS \fBvirtualenv\fP .sp -The virtualenv state can manage the state of python virtual environments. +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 @@ -21452,7 +24061,7 @@ 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. +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 @@ -22072,7 +24681,7 @@ fred_file: .ft P .fi .sp -This makes the 2 lower state decs inherit the options from thier respectively +This makes the 2 lower state decs inherit the options from their respectively "used" state decs. .SS Network State .sp @@ -22098,7 +24707,7 @@ The original ssh_auth state was limited to accepting only arguments to apply to a public key, and the key itself. This was restrictive due to the way the we learned that many people were using the state, so the key section has been expanded to accept options and arguments to the key that over ride arguments -passed in the stae. This gives substantial power to using ssh_auth with names: +passed in the state. This gives substantial power to using ssh_auth with names: .sp .nf .ft C @@ -22234,6 +24843,12 @@ Using the swarm is easy, make sure a master is up for the swarm to connect to, and then use the minionswarm.py script in the tests directory to spin up as many minions as you want. Remember, this is a fork bomb, don\(aqt spin up more than your hardware can handle! +.sp +.nf +.ft C +# python minionswarm.py \-m 20 \-\-master salt\-master +.ft P +.fi .SS Shell Tests .sp The new Shell testing system allows us to test the behavior of commands @@ -22248,5 +24863,4 @@ Thomas S. Hatch and many others, please see the Authors file .SH COPYRIGHT 2012, Thomas S. Hatch .\" Generated by docutils manpage writer. -.\" .