From adf6018a68022dbc6516aedb95833d2d2d572962 Mon Sep 17 00:00:00 2001 From: Thomas S Hatch Date: Tue, 12 Feb 2013 12:02:51 -0700 Subject: [PATCH] update man pages for 0.13.0 --- doc/man/salt-call.1 | 5 +- doc/man/salt-cp.1 | 5 +- doc/man/salt-key.1 | 5 +- doc/man/salt-master.1 | 5 +- doc/man/salt-minion.1 | 5 +- doc/man/salt-run.1 | 5 +- doc/man/salt-syndic.1 | 5 +- doc/man/salt.1 | 9 +- doc/man/salt.7 | 6674 ++++++++++++++++++++++++++++++++--------- 9 files changed, 5252 insertions(+), 1466 deletions(-) diff --git a/doc/man/salt-call.1 b/doc/man/salt-call.1 index b2b4438b26db..6cdbbe068448 100644 --- a/doc/man/salt-call.1 +++ b/doc/man/salt-call.1 @@ -1,4 +1,4 @@ -.TH "SALT-CALL" "1" "January 15, 2013" "0.12.0" "Salt" +.TH "SALT-CALL" "1" "February 12, 2013" "0.13.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 @@ -134,5 +134,4 @@ Thomas S. Hatch and many others, please see the Authors fil .SH COPYRIGHT 2013, Thomas S. Hatch .\" Generated by docutils manpage writer. -.\" . diff --git a/doc/man/salt-cp.1 b/doc/man/salt-cp.1 index 383eb935be52..e7a776ef60c8 100644 --- a/doc/man/salt-cp.1 +++ b/doc/man/salt-cp.1 @@ -1,4 +1,4 @@ -.TH "SALT-CP" "1" "January 15, 2013" "0.12.0" "Salt" +.TH "SALT-CP" "1" "February 12, 2013" "0.13.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 @@ -120,5 +120,4 @@ Thomas S. Hatch and many others, please see the Authors fil .SH COPYRIGHT 2013, Thomas S. Hatch .\" Generated by docutils manpage writer. -.\" . diff --git a/doc/man/salt-key.1 b/doc/man/salt-key.1 index e598dc25feeb..76a7b83f36e2 100644 --- a/doc/man/salt-key.1 +++ b/doc/man/salt-key.1 @@ -1,4 +1,4 @@ -.TH "SALT-KEY" "1" "January 15, 2013" "0.12.0" "Salt" +.TH "SALT-KEY" "1" "February 12, 2013" "0.13.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 @@ -180,5 +180,4 @@ Thomas S. Hatch and many others, please see the Authors fil .SH COPYRIGHT 2013, Thomas S. Hatch .\" Generated by docutils manpage writer. -.\" . diff --git a/doc/man/salt-master.1 b/doc/man/salt-master.1 index a1c5ebb0c27f..458c32b2762c 100644 --- a/doc/man/salt-master.1 +++ b/doc/man/salt-master.1 @@ -1,4 +1,4 @@ -.TH "SALT-MASTER" "1" "January 15, 2013" "0.12.0" "Salt" +.TH "SALT-MASTER" "1" "February 12, 2013" "0.13.0" "Salt" .SH NAME salt-master \- salt-master 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 master daemon, used to control the Salt minions @@ -93,5 +93,4 @@ Thomas S. Hatch and many others, please see the Authors fil .SH COPYRIGHT 2013, Thomas S. Hatch .\" Generated by docutils manpage writer. -.\" . diff --git a/doc/man/salt-minion.1 b/doc/man/salt-minion.1 index c79d6cff9a3b..4e81e441ff2c 100644 --- a/doc/man/salt-minion.1 +++ b/doc/man/salt-minion.1 @@ -1,4 +1,4 @@ -.TH "SALT-MINION" "1" "January 15, 2013" "0.12.0" "Salt" +.TH "SALT-MINION" "1" "February 12, 2013" "0.13.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. @@ -94,5 +94,4 @@ Thomas S. Hatch and many others, please see the Authors fil .SH COPYRIGHT 2013, Thomas S. Hatch .\" Generated by docutils manpage writer. -.\" . diff --git a/doc/man/salt-run.1 b/doc/man/salt-run.1 index 1f273912410c..9437ff0fe11e 100644 --- a/doc/man/salt-run.1 +++ b/doc/man/salt-run.1 @@ -1,4 +1,4 @@ -.TH "SALT-RUN" "1" "January 15, 2013" "0.12.0" "Salt" +.TH "SALT-RUN" "1" "February 12, 2013" "0.13.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 @@ -77,5 +77,4 @@ Thomas S. Hatch and many others, please see the Authors fil .SH COPYRIGHT 2013, Thomas S. Hatch .\" Generated by docutils manpage writer. -.\" . diff --git a/doc/man/salt-syndic.1 b/doc/man/salt-syndic.1 index c2c574bc5202..1efc567f33d3 100644 --- a/doc/man/salt-syndic.1 +++ b/doc/man/salt-syndic.1 @@ -1,4 +1,4 @@ -.TH "SALT-SYNDIC" "1" "January 15, 2013" "0.12.0" "Salt" +.TH "SALT-SYNDIC" "1" "February 12, 2013" "0.13.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 @@ -83,5 +83,4 @@ Thomas S. Hatch and many others, please see the Authors fil .SH COPYRIGHT 2013, Thomas S. Hatch .\" Generated by docutils manpage writer. -.\" . diff --git a/doc/man/salt.1 b/doc/man/salt.1 index 6251ad2d9198..512865d0ec9b 100644 --- a/doc/man/salt.1 +++ b/doc/man/salt.1 @@ -1,4 +1,4 @@ -.TH "SALT" "1" "January 15, 2013" "0.12.0" "Salt" +.TH "SALT" "1" "February 12, 2013" "0.13.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 @@ -56,7 +56,9 @@ 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. The +timeout number specifes how long the command line client will wait to +query the minions and check on running jobs. .UNINDENT .INDENT 0.0 .TP @@ -228,5 +230,4 @@ Thomas S. Hatch and many others, please see the Authors fil .SH COPYRIGHT 2013, Thomas S. Hatch .\" Generated by docutils manpage writer. -.\" . diff --git a/doc/man/salt.7 b/doc/man/salt.7 index cf7438d1ecf5..79785b5cc430 100644 --- a/doc/man/salt.7 +++ b/doc/man/salt.7 @@ -1,4 +1,4 @@ -.TH "SALT" "7" "January 15, 2013" "0.12.0" "Salt" +.TH "SALT" "7" "February 12, 2013" "0.13.0" "Salt" .SH NAME salt \- Salt 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 INTRODUCTION TO SALT We’re not just talking about NaCl..SS The 30 second summary @@ -133,7 +133,7 @@ wget \-O \- http://bootstrap.saltstack.org | sudo sh .sp The script should also make it simple to install a salt master, if desired. .sp -Currently the install script supports: +Currently the install script has been tested to work on: .INDENT 0.0 .IP \(bu 2 Ubuntu 10.x/11.x/12.x @@ -227,14 +227,14 @@ cp /etc/salt/minion.template /etc/salt/minion Note: only the configuration files for the services to be run need be copied. .sp -\fBrc.conf\fP +\fBsystemd\fP .sp -Activate the Salt Master and/or Minion in \fB/etc/rc.conf\fP as follows: +Activate the Salt Master and/or Minion via \fBsystemctl\fP as follows: .sp .nf .ft C -\-DAEMONS=(syslog\-ng network crond) -+DAEMONS=(syslog\-ng network crond @salt\-master @salt\-minion) +systemctl enable salt\-master.service +systemctl enable salt\-minion.service .ft P .fi .sp @@ -246,151 +246,140 @@ seen here: .sp .nf .ft C -rc.d start salt\-master +systemctl start salt\-master .ft P .fi .sp Now go to the \fBConfiguring Salt\fP page. -.SS Debian -.SS Installation -.sp -Salt is currently available in in the Debian package tree: +.SS Debian Installation .sp -\fI\%http://packages.debian.org/source/salt\fP +Currently the latest packages for Debian are published in Martin F. Krafft\(aqs +personal debian.org repository. +.SS Confiure Apt .sp -If you\(aqre running a Debian release more recent than Wheezy use: +Setup apt to install Salt from the repository and use Debian\(aqs stable (squeeze) +backports for dependencies: .sp .nf .ft C -apt\-get install salt\-master -apt\-get install salt\-minion +for i in salt\-{common,master,minion,syndic,doc} sysvinit\-utils; do +echo "Package: $i" +echo "Pin: release a=squeeze\-backports" +echo "Pin\-Priority: 600" +echo +done > /etc/apt/preferences.d/local\-salt\-backport.pref .ft P .fi +.SS Add repository .sp -As of this writing salt is only available in Debian unstable. -.SS Squeeze -.sp -To build your own salt Debian packages on squeeze use: +Add the repository to the list of sources: .sp .nf .ft C -cat < /etc/apt/sources.list.d/local\-madduck\-backports.list + deb http://debian.madduck.net/repo squeeze\-backports main + deb\-src http://debian.madduck.net/repo squeeze\-backports main +_eof .ft P .fi .sp -After installing the necessary dependencies build the packages with: +Import the repository key. .sp .nf .ft C -git clone https://github.com/saltstack/salt.git -cd salt -fakeroot debian/rules binary +wget \-q \-O\- "http://debian.madduck.net/repo/gpg/archive.key" | apt\-key add \- .ft P .fi -.sp -You will need to install the salt\-common package along with the salt\-minion or -salt\-master packages. For example: +.IP Note +You can optionally verify the key integrity with \fBsha512sum\fP using the +public key signature shown here. E.g: .sp .nf .ft C -dpkg \-i salt\-common_.deb salt\-minion.deb -apt\-get \-f install +echo "8b1983fc2d2c55c83e2bbc15d93c3fc090c8e0e92c04ece555a6b6d8ff26de8b4fc2ccbe1bbd16a6357ff86b8b69fd261e90d61350e07a518d50fc9f5f0a1eb3 archive.key" | sha512sum \-c .ft P .fi +.RE .sp -The last command pulls in the required dependencies for your salt packages. -.SS Wheezy -.sp -Backports for Wheezy should be available shortly after it\(aqs release. -.sp -For more information how to use debian\-backports see -\fI\%http://backports-master.debian.org/Instructions/\fP -.SS Post\-installation tasks -.sp -Now go to the \fBConfiguring Salt\fP page. -.SS Ubuntu Installation -.SS Add repository -.sp -The latest packages for Ubuntu are published in the saltstack PPA. If you have -the \fBadd\-apt\-repository\fP utility, you can add the repository and import the -key in one step: +Update the package database: .sp .nf .ft C -sudo add\-apt\-repository ppa:saltstack/salt +apt\-get update .ft P .fi +.SS Install packages .sp -Alternately, manually add the repository and import the PPA key with these commands: +Install the Salt master, minion, or syndic from the repository with the apt\-get +command. These examples each install one daemon, but more than one package name +may be given at a time: .sp .nf .ft C -echo deb http://ppa.launchpad.net/saltstack/salt/ubuntu \(galsb_release \-sc\(ga main | sudo tee /etc/apt/sources.list.d/saltstack.list -wget \-q \-O\- "http://keyserver.ubuntu.com:11371/pks/lookup?op=get&search=0x4759FA960E27C0A6" | sudo apt\-key add \- +apt\-get install salt\-master .ft P .fi .sp -After adding the repository, update the package management database: +.nf +.ft C +apt\-get install salt\-minion +.ft P +.fi .sp .nf .ft C -sudo apt\-get update +apt\-get install salt\-syndic .ft P .fi -.SS Install packages +.SS Post\-installation tasks .sp -Install the Salt master, minion, or syndic from the repository with the apt\-get -command. These examples each install one daemon, but more than one package name -may be given at a time: +Now go to the \fBConfiguring Salt\fP page. +.SS Packages from Source +.sp +To build your own salt Debian packages on squeeze use: .sp .nf .ft C -sudo apt\-get install salt\-master +cat <.deb salt\-minion.deb +apt\-get \-f install .ft P .fi -.SS Post\-installation tasks .sp -Now go to the \fBConfiguring Salt\fP page. -.SS Fedora & CentOS / Enterprise Linux +The last command pulls in the required dependencies for your salt packages. +.sp +For more information how to use debian\-backports see +\fI\%http://backports-master.debian.org/Instructions/\fP +.SS Fedora .sp Beginning with version 0.9.4, Salt has been available in the primary Fedora 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" -.sp -Salt and all dependencies have been \fIfinally\fP accepted into the yum -reposities for EPEL5 and EPEL6. Currently, the latest is in epel\-testing -while awaiting promotion to epel proper, and may be installed as follows: -.sp -.nf -.ft C -yum \-\-enablerepo=epel\-testing install salt -.ft P -.fi -.sp -On RHEL6, the proper jinja packages were moved from EPEL to the -"RHEL Server Optional Channel". Verify this repository is enabled before -installing salt on RHEL6. -.RE .SS Installation .sp Salt can be installed using \fByum\fP and is available in the standard Fedora @@ -449,11 +438,11 @@ Now go to the \fBConfiguring Salt\fP page. .SS FreeBSD .sp Salt was added to the FreeBSD ports tree Dec 26th, 2011 by Christer Edwards -<\fI\%christer.edwards@gmail.com\fP>. It has been tested on FreeBSD 7.4, 8.2 and 9.0 +<\fI\%christer.edwards@gmail.com\fP>. It has been tested on FreeBSD 7.4, 8.2, 9.0 and 9.1 releases. .sp Salt is dependent on the following additional ports. These will be installed as -dependencies of the \fBsysutils/salt\fP port. +dependencies of the \fBsysutils/py\-salt\fP port. .sp .nf .ft C @@ -471,13 +460,9 @@ To install Salt from the FreeBSD ports tree, use the command: .sp .nf .ft C -cd /usr/ports/sysutils/salt && make install clean +make \-C /usr/ports/sysutils/py\-salt install clean .ft P .fi -.sp -Once the port is installed, it is necessary to make a few configuration changes. -These include defining the IP to bind to (optional), and some configuration -path changes to make salt fit more natively into the FreeBSD filesystem tree. .SS Post\-installation tasks .sp \fBMaster\fP @@ -527,6 +512,7 @@ Activate the Salt Minion in \fB/etc/rc.conf\fP or \fB/etc/rc.conf.local\fP and a .nf .ft C + salt_minion_enable="YES" ++ salt_minion_paths="/bin:/sbin:/usr/bin:/usr/sbin:/usr/local/bin:/usr/local/sbin" .ft P .fi .sp @@ -553,11 +539,367 @@ emerge app\-admin/salt .SS Post\-installation tasks .sp Now go to the \fBConfiguring Salt\fP page. +.SS OS X +.SS Dependency Installation +.sp +ZeroMQ and swig need to be installed first. +.sp +Using homebrew: +.sp +.nf +.ft C +brew install swig +brew install zmq +.ft P +.fi +.sp +Using macports, zmq and swig may need to be installed this way: +.sp +.nf +.ft C +sudo port install pyzmq +sudo port install py27\-m2crypto +sudo port install py27\-crypto +sudo port install py27\-msgpack +sudo port install python\-swig +.ft P +.fi +.sp +For installs using the OSX system python, pip install needs to use \(aqsudo\(aq: +.sp +.nf +.ft C +sudo pip install salt +.ft P +.fi +.sp +For installs using \fI\%python installed via homebrew\fP, sudo should be unnecessary: +.sp +.nf +.ft C +pip install salt +.ft P +.fi +.SS Salt\-Master Customizations +.sp +To run salt\-master on OSX, the root user maxfiles limit must be increased: +.sp +.nf +.ft C +sudo launchctl limit maxfiles 10000 +.ft P +.fi +.sp +And add this configuration option to the /etc/salt/master file: +.sp +.nf +.ft C +max_open_files: 10000 +.ft P +.fi +.sp +Now the salt\-master should run without errors: +.sp +.nf +.ft C +sudo salt\-master \-\-log\-level=all +.ft P +.fi +.SS Post\-installation tasks +.sp +Now go to the \fBConfiguring Salt\fP page. +.SS RHEL / CentOS / Scientific Linux / Amazon Linux / Oracle Linux +.sp +Beginning with version 0.9.4, Salt has been available in \fI\%EPEL\fP. It is installable using yum. Salt should work properly with all mainstream derivatives +of RHEL, including CentOS, Scientific Linux, Oracle Linux and Amazon Linux. Report any bugs or issues to the salt github project. +.SS Installation +.sp +Salt and all dependencies have been accepted into the yum +reposities for EPEL5 and EPEL6. The latest salt version can be found in epel\-testing, while an older but more tested version can be found in regular epel. +.sp +Example showing how to install salt from epel\-testing: +.sp +.nf +.ft C +yum \-\-enablerepo=epel\-testing install salt\-minion +.ft P +.fi +.sp +On RHEL6, the proper jinja package \(aqpython\-jinja2\(aq was moved from EPEL to the +"RHEL Server Optional Channel". Verify this repository is enabled before +installing salt on RHEL6. +.sp +Salt can be installed using \fByum\fP and is available in the standard Fedora +repositories. +.SS Stable Release +.sp +Salt is packaged separately for the minion and the master. It is necessary only to install the appropriate package for the role the machine will play. Typically, there will be one master and multiple minions. +.sp +On the salt\-master, run this: +.sp +.nf +.ft C +yum install salt\-master +.ft P +.fi +.sp +On each salt\-minion, run this: +.sp +.nf +.ft C +yum install salt\-minion +.ft P +.fi +.SS Post\-installation tasks +.sp +\fBMaster\fP +.sp +To have the Master start automatically at boot time: +.sp +.nf +.ft C +chkconfig salt\-master on +.ft P +.fi +.sp +To start the Master: +.sp +.nf +.ft C +service salt\-master start +.ft P +.fi +.sp +\fBMinion\fP +.sp +To have the Minion start automatically at boot time: +.sp +.nf +.ft C +chkconfig salt\-minion on +.ft P +.fi +.sp +To start the Minion: +.sp +.nf +.ft C +service salt\-minion start +.ft P +.fi +.sp +Now go to the \fBConfiguring Salt\fP page. +.SS Solaris +.sp +Salt was added to the OpenCSW package repository in September of 2012 by Romeo +Theriault <\fI\%romeot@hawaii.edu\fP> at version 0.10.2 of Salt. It has mainly been +tested on Solaris 10 (sparc), though it is built for and has been tested +minimally on Solaris 10 (x86), Solaris 9 (sparc/x86) and 11 (sparc/x86). +(Please let me know if you\(aqre using it on these platforms!) Most of the testing +has also just focused on the minion, though it has verified that the master +starts up successfully on Solaris 10. +.sp +Comments and patches for better support on these platforms is very welcome. +.sp +As of version 0.10.4, solaris is well supported under salt, with all of the +following working well: +.INDENT 0.0 +.IP 1. 3 +remote execution +.IP 2. 3 +grain detection +.IP 3. 3 +service control with SMF +.IP 4. 3 +\(aqpkg\(aq states with \(aqpkgadd\(aq and \(aqpkgutil\(aq modules +.IP 5. 3 +cron modules/states +.IP 6. 3 +user and group modules/states +.IP 7. 3 +shadow password management modules/states +.UNINDENT +.sp +Salt is dependent on the following additional packages. These will +automatically be installed as dependencies of the \fBpy_salt\fP package.: +.sp +.nf +.ft C +py_yaml +py_pyzmq +py_jinja2 +py_msgpack_python +py_m2crypto +py_crypto +python +.ft P +.fi +.SS Installation +.sp +To install Salt from the OpenCSW package repository you first need to install +\fI\%pkgutil\fP assuming you don\(aqt already have it installed: +.sp +On Solaris 10: +.sp +.nf +.ft C +pkgadd \-d http://get.opencsw.org/now +.ft P +.fi +.sp +On Solaris 9: +.sp +.nf +.ft C +wget http://mirror.opencsw.org/opencsw/pkgutil.pkg +pkgadd \-d pkgutil.pkg all +.ft P +.fi +.sp +Once pkgutil is installed you\(aqll need to edit it\(aqs config file +\fB/etc/opt/csw/pkgutil.conf\fP to point it at the unstable catalog: +.sp +.nf +.ft C +\- #mirror=http://mirror.opencsw.org/opencsw/testing ++ mirror=http://mirror.opencsw.org/opencsw/unstable +.ft P +.fi +.sp +Ok, time to install salt. +.sp +.nf +.ft C +# Update the catalog +root> /opt/csw/bin/pkgutil \-U +# Install salt +root> /opt/csw/bin/pkgutil \-i \-y py_salt +.ft P +.fi +.SS Minion Configuration +.sp +Now that salt is installed you can find it\(aqs configuration files in +\fB/etc/opt/csw/salt/\fP. +.sp +You\(aqll want to edit the minion config file to set the name of your salt master +server: +.sp +.nf +.ft C +\- #master: salt ++ master: your\-salt\-server +.ft P +.fi +.sp +If you would like to use \fI\%pkgutil\fP as the default package provider for your +Solaris minions, you can do so using the \fBproviders\fP option in the +minion config file. +.sp +You can now start the salt minion like so: +.sp +On Solaris 10: +.sp +.nf +.ft C +svcadm enable salt\-minion +.ft P +.fi +.sp +On Solaris 9: +.sp +.nf +.ft C +/etc/init.d/salt\-minion start +.ft P +.fi +.sp +You should now be able to log onto the salt master and check to see if the +salt\-minion key is awaiting acceptance: +.sp +.nf +.ft C +salt\-key \-l un +.ft P +.fi +.sp +Accept the key: +.sp +.nf +.ft C +salt\-key \-a +.ft P +.fi +.sp +Run a simple test against the minion: +.sp +.nf +.ft C +salt \(aq\(aq test.ping +.ft P +.fi +.SS Troubleshooting +.sp +Logs are in \fB/var/log/salt\fP +.SS Ubuntu Installation +.SS Add repository +.sp +The latest packages for Ubuntu are published in the saltstack PPA. If you have +the \fBadd\-apt\-repository\fP utility, you can add the repository and import the +key in one step: +.sp +.nf +.ft C +sudo add\-apt\-repository ppa:saltstack/salt +.ft P +.fi +.sp +Alternately, manually add the repository and import the PPA key with these commands: +.sp +.nf +.ft C +echo deb http://ppa.launchpad.net/saltstack/salt/ubuntu \(galsb_release \-sc\(ga main | sudo tee /etc/apt/sources.list.d/saltstack.list +wget \-q \-O\- "http://keyserver.ubuntu.com:11371/pks/lookup?op=get&search=0x4759FA960E27C0A6" | sudo apt\-key add \- +.ft P +.fi +.sp +After adding the repository, update the package management database: +.sp +.nf +.ft C +sudo apt\-get update +.ft P +.fi +.SS Install packages +.sp +Install the Salt master, minion, or syndic from the repository with the apt\-get +command. These examples each install one daemon, but more than one package name +may be given at a time: +.sp +.nf +.ft C +sudo apt\-get install salt\-master +.ft P +.fi +.sp +.nf +.ft C +sudo apt\-get install salt\-minion +.ft P +.fi +.sp +.nf +.ft C +sudo apt\-get install salt\-syndic +.ft P +.fi +.SS Post\-installation tasks +.sp +Now go to the \fBConfiguring Salt\fP page. .SS Windows .sp Salt has full support for running the Salt Minion on Windows. .sp -There are no plans for the forseeable future to develop a Salt +There are no plans for the foreseeable future to develop a Salt Master on Windows. For now you must run your Salt Master on a supported operating system to control your Salt Minions on Windows. .sp @@ -567,13 +909,18 @@ and many of the Salt States currently work on Windows, as well. .sp A Salt Minion Windows installer can be found here: .IP "Download here" -.sp -\fI\%http://saltstack.org/static/downloads/Salt-Minion-0.11.1-Setup-amd64.exe\fP +.INDENT 0.0 +.IP \(bu 2 +\fI\%http://saltstack.org/static/downloads/Salt-Minion-0.12.1-Setup-amd64.exe\fP +.IP \(bu 2 +\fI\%http://saltstack.org/static/downloads/Salt-Minion-0.12.1-Setup-win32.exe\fP +.UNINDENT .RE .sp -This installer has been tested on Windows 7 64bit and Windows Server 2008R2 -64bit. Please file a bug report on our github repo if issues for other -platforms are found. +The 64bit installer has been tested on Windows 7 64bit and Windows Server +2008R2 64bit. The 32bit installer has been tested on Windows 2003 Server 32bit. +Please file a bug report on our github repo if issues for other platforms are +found. .sp The installer asks for 2 bits of information; the master hostname and the minion name. The installer will update the minion config with these options and @@ -603,7 +950,7 @@ Salt\-Minion\-0.11.1\-Setup\-amd64.exe /S /master=yoursaltmaster /minion\-name=y .sp The Salt Windows installer is built with the open\-source NSIS compiler. The source for the installer is found in the pkg directory of the Salt repo here: -\fI\%https://github.com/saltstack/salt/blob/develop/pkg/windows/installer/Salt-Minion-Setup.nsi\fP +\fI\%https://github.com/saltstack/salt/blob/develop/pkg/windows/installer/Salt-Minion-Setup.nsi\fP. To create the installer run \fBpython setup.py bdist_esky\fP, extract the frozen archive from \fBdist/\fP into \fBpkg/windows/buildenv/\fP and run NSIS. .sp @@ -639,7 +986,7 @@ Install \fI\%Python 2.7.x\fP .IP 4. 4 Add c:\ePython27 to your system path .IP 5. 4 -Install the Microsoft Visuall C++ 2008 SP1 Redistributable, \fI\%vcredist_x86\fP. +Install the Microsoft Visual C++ 2008 SP1 Redistributable, \fI\%vcredist_x86\fP. .IP 6. 4 Install \fI\%Win32OpenSSL-1_0_0e.exe\fP .INDENT 4.0 @@ -781,7 +1128,7 @@ On a 64 bit Windows host the following script makes an unattended install of sal .ft P .fi .sp -You can execute the above command remotely from a linux host using winexe: +You can execute the above command remotely from a Linux host using winexe: .sp .nf .ft C @@ -790,157 +1137,6 @@ winexe \-U "administrator" //fqdn "PowerShell (New\-Object ......);" .fi .sp For more info check \fI\%http://csa-net.dk/salt\fP -.SS Solaris -.sp -Salt was added to the OpenCSW package repository in September of 2012 by Romeo -Theriault <\fI\%romeot@hawaii.edu\fP> at version 0.10.2 of Salt. It has mainly been -tested on Solaris 10 (sparc), though it is built for and has been tested -minimally on Solaris 10 (x86), Solaris 9 (sparc/x86) and 11 (sparc/x86). -(Please let me know if you\(aqre using it on these platforms!) Most of the testing -has also just focused on the minion, though it has verified that the master -starts up successfully on Solaris 10. -.sp -Comments and patches for better support on these platforms is very welcome. -.sp -As of version 0.10.4, solaris is well supported under salt, with all of the -following working well: -.INDENT 0.0 -.IP 1. 3 -remote execution -.IP 2. 3 -grain detection -.IP 3. 3 -service control with SMF -.IP 4. 3 -\(aqpkg\(aq states with \(aqpkgadd\(aq and \(aqpkgutil\(aq modules -.IP 5. 3 -cron modules/states -.IP 6. 3 -user and group modules/states -.IP 7. 3 -shadow password management modules/states -.UNINDENT -.sp -Salt is dependent on the following additional packages. These will -automatically be installed as dependencies of the \fBpy_salt\fP package.: -.sp -.nf -.ft C -py_yaml -py_pyzmq -py_jinja2 -py_msgpack_python -py_m2crypto -py_crypto -python -.ft P -.fi -.SS Installation -.sp -To install Salt from the OpenCSW package repository you first need to install -\fI\%pkgutil\fP assuming you don\(aqt already have it installed: -.sp -On Solaris 10: -.sp -.nf -.ft C -pkgadd \-d http://get.opencsw.org/now -.ft P -.fi -.sp -On Solaris 9: -.sp -.nf -.ft C -wget http://mirror.opencsw.org/opencsw/pkgutil.pkg -pkgadd \-d pkgutil.pkg all -.ft P -.fi -.sp -Once pkgutil is installed you\(aqll need to edit it\(aqs config file -\fB/etc/opt/csw/pkgutil.conf\fP to point it at the unstable catalog: -.sp -.nf -.ft C -\- #mirror=http://mirror.opencsw.org/opencsw/testing -+ mirror=http://mirror.opencsw.org/opencsw/unstable -.ft P -.fi -.sp -Ok, time to install salt. -.sp -.nf -.ft C -# Update the catalog -root> /opt/csw/bin/pkgutil \-U -# Install salt -root> /opt/csw/bin/pkgutil \-i \-y py_salt -.ft P -.fi -.SS Minion Configuration -.sp -Now that salt is installed you can find it\(aqs configuration files in -\fB/etc/opt/csw/salt/\fP. -.sp -You\(aqll want to edit the minion config file to set the name of your salt master -server: -.sp -.nf -.ft C -\- #master: salt -+ master: your\-salt\-server -.ft P -.fi -.sp -If you would like to use \fI\%pkgutil\fP as the default package provider for your -Solaris minions, you can do so using the \fBproviders\fP option in the -minion config file. -.sp -You can now start the salt minion like so: -.sp -On Solaris 10: -.sp -.nf -.ft C -svcadm enable salt\-minion -.ft P -.fi -.sp -On Solaris 9: -.sp -.nf -.ft C -/etc/init.d/salt\-minion start -.ft P -.fi -.sp -You should now be able to log onto the salt master and check to see if the -salt\-minion key is awaiting acceptance: -.sp -.nf -.ft C -salt\-key \-l un -.ft P -.fi -.sp -Accept the key: -.sp -.nf -.ft C -salt\-key \-a -.ft P -.fi -.sp -Run a simple test against the minion: -.sp -.nf -.ft C -salt \(aq\(aq test.ping -.ft P -.fi -.SS Troubleshooting -.sp -Logs are in \fB/var/log/salt\fP .SS Dependencies .sp Salt should run on any Unix\-like platform so long as the dependencies are met. @@ -957,11 +1153,13 @@ Salt should run on any Unix\-like platform so long as the dependencies are met. \fI\%msgpack-python\fP \- High\-performance message interchange format .IP \(bu 2 \fI\%YAML\fP \- Python YAML bindings +.IP \(bu 2 +\fI\%Jinja2\fP \- parsing Salt States (configurable in the master settings) .UNINDENT .SS Optional Dependencies .INDENT 0.0 .IP \(bu 2 -\fI\%Jinja2\fP \- parsing Salt States (configurable in the master settings) +\fI\%mako\fP \- an optional parser for Salt States (configurable in the master settings) .IP \(bu 2 gcc \- dynamic \fI\%Cython\fP module compiling .UNINDENT @@ -1002,6 +1200,8 @@ interfaces (0.0.0.0). To bind Salt to a specific IP, redefine the .fi .sp After updating the configuration file, restart the Salt master. +See the \fBmaster configuration reference\fP +for more details about other configurable options. .SS Minion Configuration .sp Although there are many Salt Minion configuration options, configuring @@ -1021,6 +1221,8 @@ configuration file, typically \fB/etc/salt/minion\fP, as follows: .fi .sp After updating the configuration file, restart the Salt minion. +See the \fBminion configuration reference\fP +for more details about other configurable options. .SS Running Salt .INDENT 0.0 .IP 1. 3 @@ -1142,78 +1344,140 @@ either want to visit the section regarding Salt States, or the section on Modules. .SH DEVELOPING SALT .sp -If you want to help develop Salt there is a great need and your patches are -welcome! +There is a great need for contributions to salt and patches are welcome! The goal +here is to make contributions clear, make sure there is a trail for where the code +has come from, and most importantly, to give credit where credit is due! .sp -To assist in Salt development, you can help in a number of ways. -.SS Setting a Github pull request +There are a number of ways to contribute to salt development. +.SS Sending a Github pull request .sp -This is the preferred method for contributions, simply create a Github -fork, commit your changes to the fork, and then open up a pull request. -If you want to make our life really easier, please also enable Travis\-CI on -your fork. Salt is already configured, all you need to do is follow the first -two(2) steps on their \fI\%Getting Started Doc\fP. -.SS Posting patches to the mailing list +This is the preferred method for contributions. Simply create a Github +fork, commit changes to the fork, and then open up a pull request. .sp -If you have a patch for Salt, please format it via \fBgit format\-patch\fP -and send it to the Salt users mailing list. This allows the patch to give you -the contributor the credit for your patch, and gives the Salt community an -archive of the patch and a place for discussion. -.SS Contributions Welcome! +The following is an example (from \fI\%Open Comparison Contributing Docs\fP ) +of an efficient workflow for forking, cloning, branching, committing, and +sending a pull request for a github repository. .sp -The goal here is 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! +First, make a local clone of your github fork of the salt github repo and make edits and +changes locally. .sp -The \fI\%Open Comparison Contributing Docs\fP explains the workflow for forking, -cloning, branching, committing, and sending a pull request for the git -repository. +Then, create a new branch on your clone by entering the following commands: .sp -\fBgit pull upstream develop\fP is a shorter way to update your local repository -to the latest version. -.SS Editing and Previewing the Docs +.nf +.ft C +git checkout \-b fixed\-broken\-thing + +Switched to a new branch \(aqfixed\-broken\-thing\(aq +.ft P +.fi .sp -You need \fBsphinx\-build\fP to build the docs. In Debian/Ubuntu this is provided -in the \fBpython\-sphinx\fP package. +Choose a name for your branch that describes its purpose. .sp -Then: +Now commit your changes to this new branch with the following command: .sp .nf .ft C -cd doc; make html +#add and commit all changes at once +git commit \-a \-m \(aqdescription of my fixes for the broken thing\(aq .ft P .fi -.INDENT 0.0 -.IP \(bu 2 -The docs then are built in the \fBdocs/_build/html/\fP folder. If you make -changes and want to see the results, \fBmake html\fP again. -.IP \(bu 2 -The docs use \fBreStructuredText\fP for markup. See a live demo at -\fI\%http://rst.ninjs.org/\fP. -.IP \(bu 2 -The help information on each module or state is culled from the python code -that runs for that piece. Find them in \fBsalt/modules/\fP or \fBsalt/states/\fP. -.IP \(bu 2 -If you are developing using Arch Linux (or any other distribution for which -Python 3 is the default Python installation), then \fBsphinx\-build\fP may be -named \fBsphinx\-build2\fP instead. If this is the case, then you will need to -run the following \fBmake\fP command: +.sp +And then push your locally committed changes back up to GitHub: +.sp +.nf +.ft C +git push \-\-set\-upstream origin fixed\-broken\-thing +.ft P +.fi +.sp +Now go look at your fork of the salt repo on the GitHub website. The new +branch will now be listed under the "Source" tab where it says "Switch Branches". +Select the new branch from this list, and then click the "Pull request" button. +.sp +Put in a descriptive comment, and include links to any project issues related to the pull request. +.sp +The repo managers will be notified of your pull request and it will +be reviewed. If a reviewer asks for changes, just make the changes locally in the +same local feature branch, push them to GitHub, then add a comment to the +discussion section of the pull request. +.IP Note +Travis\-CI +.sp +To make reviewing pull requests easier for the maintainers, please enable Travis\-CI on +the fork. Salt is already configured, so simply follow the first +2 steps on the Travis\-CI \fI\%Getting Started Doc\fP. +.RE +.SS Keeping Salt Forks in Sync +.sp +Salt is advancing quickly. It is therefore critical to pull upstream changes from master into forks on a regular basis. Nothing is worse than putting in a days of hard work into a pull request only to have it rejected because it has diverged too far from master. +.sp +To pull in upstream changes: +.sp +.nf +.ft C +# For ssh github +git remote add upstream git@github.com:saltstack/salt.git +git fetch upstream + +# For https github +git remote add upstream https://github.com/saltstack/salt.git +git fetch upstream +.ft P +.fi +.sp +To check the log to be sure that you actually want the changes, run this before merging: +.sp +.nf +.ft C +git log upstream/develop +.ft P +.fi +.sp +Then to accept the changes and merge into the current branch: +.sp +.nf +.ft C +git merge upstream/develop +.ft P +.fi +.sp +For more info, see \fI\%Github Fork a Repo Guide\fP or \fI\%Open Comparison Contributing Docs\fP +.SS Posting patches to the mailing list +.sp +Patches will also be accepted by email. Format patches using \fI\%git format-patch\fP +and send them to the Salt users mailing list. The contributor will then get credit +for the patch, and the Salt community will have an archive of the patch and a place for discussion. +.SS Installing Salt for development +.sp +Clone the repository using: +.sp +.nf +.ft C +git clone https://github.com/saltstack/salt +.ft P +.fi +.IP Note +tags +.sp +Just cloning the repository is enough to work with Salt and make +contributions. However, fetching additional tags from git is required to +have Salt report the correct version for itself. To do this, first +add the git repository as an upstream source: .sp .nf .ft C -make SPHINXBUILD=sphinx\-build2 html +git remote add upstream http://github.com/saltstack/salt .ft P .fi -.UNINDENT -.SS Installing Salt for development .sp -Clone the repository using: +Fetching tags is done with the git \(aqfetch\(aq utility: .sp .nf .ft C -git clone https://github.com/saltstack/salt +git fetch \-\-tags upstream .ft P .fi +.RE .sp Create a new \fI\%virtualenv\fP: .sp @@ -1226,15 +1490,13 @@ virtualenv /path/to/your/virtualenv On Arch Linux, where Python 3 is the default installation of Python, use the \fBvirtualenv2\fP command instead of \fBvirtualenv\fP. .IP Note -Using your system Python modules in the virtualenv -.sp -If you have the required python modules installed on your system already -and would like to use them in the virtualenv rather than having pip -download and compile new ones into this environment, run \fBvirtualenv\fP -with the \fB\-\-system\-site\-packages\fP option. If you do this, you can skip -the pip command below that installs the dependencies (pyzmq, M2Crypto, -etc.), assuming that the listed modules are all installed in your system -PYTHONPATH at the time you create your virtualenv. +Using system Python modules in the virtualenv +.sp +To use already\-installed python modules in virtualenv (instead of having pip +download and compile new ones), run \fBvirtualenv \-\-system\-site\-packages\fP +Using this method eliminates the requirement to install the salt dependencies +again, although it does assume that the listed modules are all installed in the +system PYTHONPATH at the time of virtualenv creation. .RE .sp Activate the virtualenv: @@ -1257,9 +1519,9 @@ pip install \-e ./salt # the path to the salt git clone from above .IP Note Installing M2Crypto .sp -You may need \fBswig\fP and \fBlibssl\-dev\fP to build M2Crypto. If you -encounter the error \fBcommand \(aqswig\(aq failed with exit status 1\fP -while installing M2Crypto, try installing it with the following command: +\fBswig\fP and \fBlibssl\-dev\fP are required to build M2Crypto. To fix +the error \fBcommand \(aqswig\(aq failed with exit status 1\fP while installing M2Crypto, +try installing it with the following command: .sp .nf .ft C @@ -1270,19 +1532,20 @@ env SWIG_FEATURES="\-cpperraswarn \-includeall \-D__\(gauname \-m\(ga__ \-I/usr/ Debian and Ubuntu systems have modified openssl libraries and mandate that a patched version of M2Crypto be installed. This means that M2Crypto needs to be installed via apt: -.INDENT 0.0 -.INDENT 3.5 +.sp +.nf +.ft C apt\-get install python\-m2crypto -.UNINDENT -.UNINDENT +.ft P +.fi .sp -This also means that you should use \fB\-\-system\-site\-packages\fP when -creating the virtualenv, to pull in the M2Crypto installed using apt. +This also means that pulling in the M2Crypto installed using apt requires using +\fB\-\-system\-site\-packages\fP when creating the virtualenv. .RE .IP Note Important note for those developing using RedHat variants .sp -If you are developing on a RedHat variant, be advised that the package +For developers using a RedHat variant, be advised that the package provider for newer Redhat\-based systems (\fByumpkg.py\fP) relies on RedHat\(aqs python interface for yum. The variants that use this module to provide package support include the following: @@ -1295,9 +1558,14 @@ support include the following: \fI\%Amazon Linux\fP .UNINDENT .sp -If you are developing using one of these releases, you will want to create -your virtualenv using the \fB\-\-system\-site\-packages\fP option so that these -modules are available in the virtualenv. +Developers using one of these systems should create the salt virtualenv using the +\fB\-\-system\-site\-packages\fP option to ensure that the correct modules are available. +.RE +.IP Note +Installing dependencies on OS X. +.sp +You can install needed dependencies on OS X using homebrew or macports. +See \fBOS X Installation\fP .RE .SS Running a self\-contained development version .sp @@ -1398,24 +1666,24 @@ length. Remember that this path is relative to the value you set in .sp \fBNOTE:\fP The socket path is limited to 107 characters on Solaris and Linux, and 103 characters on BSD\-based systems. -.SS File descriptor limit +.IP Note +File descriptor limits .sp -Check your file descriptor limit with: +Ensure that the system open file limit is raised to at least 2047: .sp .nf .ft C +# check your current limit ulimit \-n -.ft P -.fi -.sp -If it is less than 2047, you should increase it with: -.sp -.nf -.ft C + +# raise the limit. persists only until reboot +# use \(aqlimit descriptors 2047\(aq for c\-shell ulimit \-n 2047 -(or "limit descriptors 2047" for c\-shell) .ft P .fi +.sp +To set file descriptors on OSX, refer to the \fBOS X Installation\fP instructions. +.RE .SS Running the tests .sp You will need \fBmock\fP to run the tests: @@ -1449,6 +1717,47 @@ For greater control while running the tests, please try: \&./tests/runtests.py \-h .ft P .fi +.SS Editing and previewing the documention +.sp +You need \fBsphinx\-build\fP command to build the docs. In Debian/Ubuntu this is provided +in the \fBpython\-sphinx\fP package. You can also install this directly to your virtual +environment using pip: +.sp +.nf +.ft C +pip install Sphinx +.ft P +.fi +.sp +Change to salt documention directory, then: +.sp +.nf +.ft C +cd doc; make html +.ft P +.fi +.INDENT 0.0 +.IP \(bu 2 +The docs then are built in the \fBdocs/_build/html/\fP folder. If you make +changes and want to see the results, \fBmake html\fP again. +.IP \(bu 2 +The docs use \fI\%reStructuredText\fP for markup. +See a live demo at \fI\%http://rst.ninjs.org/\fP. +.IP \(bu 2 +The help information on each module or state is culled from the python code +that runs for that piece. Find them in \fBsalt/modules/\fP or \fBsalt/states/\fP. +.IP \(bu 2 +If you are developing using Arch Linux (or any other distribution for which +Python 3 is the default Python installation), then \fBsphinx\-build\fP may be +named \fBsphinx\-build2\fP instead. If this is the case, then you will need to +run the following \fBmake\fP command: +.sp +.nf +.ft C +make SPHINXBUILD=sphinx\-build2 html +.ft P +.fi +.UNINDENT .SH TARGETING .INDENT 0.0 .TP @@ -1644,8 +1953,9 @@ names of the grains and the values are the values. .sp Custom grains should be placed in a \fB_grains\fP directory located under the \fBfile_roots\fP specified by the master config file. They will be -distributed to the minions when \fI\%state.highstate\fP is run, or by executing the -\fI\%saltutil.sync_grains\fP or \fI\%saltutil.sync_all\fP functions. +distributed to the minions when \fBstate.highstate\fP is run, or by executing the +\fBsaltutil.sync_grains\fP or +\fBsaltutil.sync_all\fP functions. .sp Before adding a grain to Salt, consider what the grain is and remember that grains need to be static data. If the data is something that is likely to @@ -1774,6 +2084,14 @@ T} T{ \fBS@192.168.1.0/24\fP or \fBS@192.168.1.100\fP T} _ +T{ +R +T} T{ +Range cluster match +T} T{ +\fBR@%foo.bar\fP +T} +_ .TE .sp Matchers can be joined using boolean \fBand\fP, \fBor\fP, and \fBnot\fP operators. @@ -1823,7 +2141,280 @@ 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 +.SH SALT TUTORIALS +.SS 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 \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 \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 +.IP 1. 3 +Install \fI\%Salt\fP with dependencies +.IP 2. 3 +Point the minion to the master +.UNINDENT +.sp +Here is a sample script: +.sp +.nf +.ft C +#!/bin/bash + +# Install saltstack +add\-apt\-repository ppa:saltstack/salt \-y +apt\-get update \-y +apt\-get install salt\-minion \-y +apt\-get install salt\-master \-y +apt\-get upgrade \-y + +# Set salt master location and start minion +sed \-i \(aqs/#master: salt/master: [salt_master_fqdn]/\(aq /etc/salt/minion +salt\-minion \-d +.ft P +.fi +.sp +First the script adds the saltstack ppa and installs the package. Then +we copy over the minion config template and tell it where to find the +master. You will have to replace \fB[salt_master_fqdn]\fP with something +that resolves to your Salt master. +.SS Used With Boto +.sp +\fI\%Boto\fP will accept a string for user data +which can be used to pass our bootstrap script. If the script is saved to +a file, you can read it into a string: +.sp +.nf +.ft C +import boto + +user_data = open(\(aqsalt_bootstrap.sh\(aq) + +conn = boto.connect_ec2(, ) + +reservation = conn.run_instances(image_id=, + key_name=, + user_data=user_data.read()) +.ft P +.fi +.SS Additional Notes +.sp +Sometime in the future the ppa will include and install an upstart file. In the +meantime, you can use the bootstrap to \fI\%build one\fP. +.sp +It may also be useful to set the node\(aqs role during this phase. One option +would be saving the node\(aqs role to a file and then using a custom Grain +to select it. +.SS Using cron with Salt +.sp +The Salt Minion can initiate its own highstate using the \fIsalt\-call\fP command. +.sp +.nf +.ft C +$ salt\-call state.highstate +.ft P +.fi +.sp +This will cause the minion to check in with the master and ensure it is in the +correct \(aqstate\(aq. +.SS Use cron to initiate a highstate +.sp +If you would like the Salt Minion to regularly check in with the master you can +use the venerable cron to run the \fIsalt\-call\fP command. +.sp +.nf +.ft C +# PATH=/bin:/sbin:/usr/bin:/usr/sbin + +00 00 * * * salt\-call state.highstate +.ft P +.fi +.sp +The above cron entry will run a highstate every day at midnight. +.IP Note +Be aware that you may need to ensure the PATH for cron includes any +scripts or commands that need to be executed. +.RE +.SS Automatic Updates / Frozen Deployments +.sp +New in version 0.10.3.d. +.sp +Salt has support for the +\fI\%Esky\fP application freezing and update +tool. This tool allows one to build a complete zipfile out of the salt scripts +and all their dependencies \- including shared objects / DLLs. +.SS Getting Started +.sp +To build frozen applications, you\(aqll need a suitable build environment for each +of your platforms. You should probably set up a virtualenv in order to limit +the scope of Q/A. +.sp +This process does work on Windows. Follow the directions at +\fI\%https://github.com/saltstack/salt-windows-install\fP for details on +installing Salt in Windows. Only the 32\-bit Python and dependencies have been +tested, but they have been tested on 64\-bit Windows. +.sp +You will need to install \fBesky\fP and \fBbbfreeze\fP from Pypi in order to enable +the \fBbdist_esky\fP command in \fBsetup.py\fP. +.SS Building and Freezing +.sp +Once you have your tools installed and the environment configured, you can then +\fBpython setup.py bdist\fP to get the eggs prepared. After that is done, run +\fBpython setup.py bdist_esky\fP to have Esky traverse the module tree and pack +all the scripts up into a redistributable. There will be an appropriately +versioned \fBsalt\-VERSION.zip\fP in \fBdist/\fP if everything went smoothly. +.SS Windows +.sp +You will need to add \fBC:\ePython27\elib\esite\-packages\ezmq\fP to your PATH +variable. This helps bbfreeze find the zmq dll so it can pack it up. +.SS Using the Frozen Build +.sp +Unpack the zip file in your desired install location. Scripts like +\fBsalt\-minion\fP and \fBsalt\-call\fP will be in the root of the zip file. The +associated libraries and bootstrapping will be in the directories at the same +level. (Check the \fI\%Esky\fP documentation +for more information) +.sp +To support updating your minions in the wild, put your builds on a web server +that your minions can reach. \fBsalt.modules.saltutil.update()\fP will +trigger an update and (optionally) a restart of the minion service under the +new version. +.SS Gotchas +.SS My Windows minion isn\(aqt responding +.sp +The process dispatch on Windows is slower than it is on *nix. You may need to +add \(aq\-t 15\(aq to your salt calls to give them plenty of time to return. +.SS Windows and the Visual Studio Redist +.sp +You will need to install the Visual C++ 2008 32\-bit redistributable on all +Windows minions. Esky has an option to pack the library into the zipfile, +but OpenSSL does not seem to acknowledge the new location. If you get a +\fBno OPENSSL_Applink\fP error on the console when trying to start your +frozen minion, you have forgotten to install the redistributable. +.SS Mixed Linux environments and Yum +.sp +The Yum Python module doesn\(aqt appear to be available on any of the standard +Python package mirrors. If you need to support RHEL/CentOS systems, you +should build on that platform to support all your Linux nodes. Also remember +to build your virtualenv with \fB\-\-system\-site\-packages\fP so that the +\fByum\fP module is included. +.SS Automatic (Python) module discovery +.sp +Automatic (Python) module discovery does not work with the late\-loaded scheme that +Salt uses for (Salt) modules. You will need to explicitly add any +misbehaving modules to the \fBfreezer_includes\fP in Salt\(aqs \fBsetup.py\fP. +Always check the zipped application to make sure that the necessary modules +were included. +.SS Opening the Firewall up for Salt +.sp +The Salt master communicates with the minions using an AES\-encrypted ZeroMQ +connection. These communications are done over ports 4505 and 4506, which need +to be accessible on the master only. This document outlines suggested firewall +rules for allowing these incoming connections to the master. +.IP Note +\fBNo firewall configuration needs to be done on Salt minions. These changes +refer to the master only.\fP +.RE +.SS RHEL 6 / CENTOS 6 +.sp +The lokkit command packaged with some linux distributions makes opening +iptables firewall ports very simple via the command line. Just be careful +to not lock out access to the server by neglecting to open the ssh +port. +.sp +\fBlokkit example\fP +.sp +.nf +.ft C +lokkit \-p 22:tcp \-p 4505:tcp \-p 4506:tcp +.ft P +.fi +.sp +The system\-config\-firewall\-tui command provides a text\-based interface to modifying +the firewall. +.sp +\fBsystem\-config\-firewall\-tui\fP +.sp +.nf +.ft C +system\-config\-firewall\-tui +.ft P +.fi +.SS iptables +.sp +Different Linux distributions store their \fI\%iptables\fP rules in different places, +which makes it difficult to standardize firewall documentation. Included are +some of the more common locations, but your mileage may vary. +.sp +\fBFedora / RHEL / CentOS\fP +.sp +.nf +.ft C +/etc/sysconfig/iptables +.ft P +.fi +.sp +\fBArch Linux\fP +.sp +.nf +.ft C +/etc/iptables/iptables.rules +.ft P +.fi +.sp +\fBDebian\fP +.sp +Follow these instructions: \fI\%http://wiki.debian.org/iptables\fP +.sp +Once you\(aqve found your firewall rules, you\(aqll need to add the two lines below +to allow traffic on \fBtcp/4505\fP and \fBtcp/4506\fP: +.sp +.nf +.ft C +\-A INPUT \-m state \-\-state new \-m tcp \-p tcp \-\-dport 4505 \-j ACCEPT +\-A INPUT \-m state \-\-state new \-m tcp \-p tcp \-\-dport 4506 \-j ACCEPT +.ft P +.fi +.sp +\fBUbuntu\fP +.sp +Create a file named \fB/etc/ufw/applications.d/salt\-master\fP +.sp +.nf +.ft C +[Salt Master] +title=Salt master +description=Salt is a remote execution and configuration management tool. +ports=4505,4506/tcp +.ft P +.fi +.SS pf.conf +.sp +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 +.nf +.ft C +pass in on $int_if proto tcp from any to $int_if port 4505 +pass in on $int_if proto tcp from any to $int_if port 4506 +.ft P +.fi +.sp +Once these additions have been made to the \fBpf.conf\fP the rules will need to +be reloaded. This can be done using the \fBpfctl\fP command. +.sp +.nf +.ft C +pfctl \-vf /etc/pf.conf +.ft P +.fi +.SS Remote execution tutorial .sp \fBBefore continuing\fP make sure you have a working Salt installation by following the \fBinstallation\fP and the \fBconfiguration\fP instructions. @@ -1880,11 +2471,19 @@ salt \-E \(aqvirtmach[0\-9]\(aq test.ping .ft P .fi .sp -Finally, targets can be explicitly specified in a list: +Targets can be explicitly specified in a list: +.sp +.nf +.ft C +salt \-L \(aqfoo,bar,baz,quo\(aq test.ping +.ft P +.fi +.sp +Or Multiple target types can be combined in one command: .sp .nf .ft C -salt \-L foo,bar,baz,quo test.ping +salt \-C \(aqG@os:Ubuntu and webser* or E@database.*\(aq test.ping .ft P .fi .SS function @@ -1939,12 +2538,225 @@ salt \(aq*\(aq pip.install salt timeout=5 upgrade=True .fi .sp They are always in the form of \fBkwarg=argument\fP. -.SH HOW DO I USE SALT STATES? +.SS Preseed Minion with Accepted Key +.sp +In some situations, it is not convenient to wait for a minion to start before +accepting its key on the master. For instance, you may want the minion to +bootstrap itself as soon as it comes online. You may also want to to let your +developers provision new development machines on the fly. +.sp +There is a general four step process to do this: +.INDENT 0.0 +.IP 1. 3 +Generate the keys on the master: +.sp +.nf +.ft C +root@saltmaster# salt\-key \-\-gen\-keys=[key_name] +.ft P +.fi +.UNINDENT +.sp +Pick a name for the key, such as the minion\(aqs id. +.INDENT 0.0 +.IP 2. 3 +Add the public key to the accepted minion folder: +.sp +.nf +.ft C +root@saltmaster# cp key_name.pub /etc/salt/pki/master/minions/[minion_id] +.ft P +.fi +.UNINDENT +.sp +It is necessary that the public key file has the same name as your minion id. +This is how Salt matches minions with their keys. Also note that the pki folder +could be in a different location, depending on your OS or if specified in the +master config file. +.INDENT 0.0 +.IP 3. 3 +Distribute the minion keys. +.UNINDENT +.sp +There is no single method to get the keypair to your minion. If you are +spooling up minions on EC2, you could pass them in using user_data or a +cloud\-init script. If you are handing them off to a team of developers for provisioning dev machines, you will need a secure file transfer. +.IP "Security Warning" +.sp +Since the minion key is already accepted on the master, distributing +the private key poses a potential security risk. A malicious party +will have access to your entire state tree and other sensitive data. +.RE +.INDENT 0.0 +.IP 4. 3 +Preseed the Minion with the keys +.UNINDENT +.sp +You will want to place the minion keys before starting the salt\-minion daemon: +.sp +.nf +.ft C +/etc/salt/pki/minion/minion.pem +/etc/salt/pki/minion/minion.pub +.ft P +.fi +.sp +Once in place, you should be able to start salt\-minion and run +\fBsalt\-call state.highstate\fP or any other salt commands that require master +authentication. +.SS Salt Masterless Quickstart +.sp +Running a masterless salt\-minion lets you use salt\(aqs configuration management +for a single machine. It is also useful for testing out state trees before +deploying to a production setup. +.sp +The only real difference in using a standalone minion is that instead of issuing +commands with \fBsalt\fP, we use the \fBsalt\-call\fP command, like this: +.sp +.nf +.ft C +salt\-call \-\-local state.highstate +.ft P +.fi +.SS Bootstrap Salt Minion +.sp +First we need to install the salt minion. The \fI\%salt-bootstrap\fP script makes +this incredibly easy for any OS with a Bourne shell. You can use it like this: +.sp +.nf +.ft C +wget \-O \- http://bootstrap.saltstack.org | sudo sh +.ft P +.fi +.sp +Or see the \fI\%salt-bootstrap\fP documentation for other one liners. Additionally, +if you are using \fI\%Vagrant\fP to test out salt, the \fI\%salty-vagrant\fP tool will +provision the VM for you. +.SS Create State Tree +.sp +Now we build an example state tree. This is where the configuration +is defined. For more in depth directions, see the \fI\%tutorial\fP. +.sp +1. Create the top.sls file +.sp +.nf +.ft C +# /srv/salt/top.sls +base: + \(aq*\(aq: + \- webserver +.ft P +.fi +.sp +2. Create our webserver state tree +.sp +.nf +.ft C +# /srv/salt/webserver.sls +apache: # ID declaration + pkg: # state declaration + \- installed # function declaration +.ft P +.fi +.sp +The only thing left is to provision our minion using the highstate command. +Salt\-call also gives us an easy way to give us verbose output: +.sp +.nf +.ft C +salt\-call \-\-local state.highstate \-l debug +.ft P +.fi +.sp +The \fB\-\-local\fP flag tells the salt\-minion to look for the state tree in the local file system. +Normally the minion copies the state tree from the master and executes it from there. +.sp +That\(aqs it, good luck! +.SS 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. +.sp +Now the declared state can now be executed with: +.sp +.nf +.ft C +salt\-call state.highstate +.ft P +.fi +.sp +Or the salt\-call command can be executed with the \fI\-\-local\fP flag, this makes it +unnecessary to change the configuration file: +.sp +.nf +.ft C +salt\-call state.highstate \-\-local +.ft P +.fi +.SS How Do I Use Salt States? .sp Simplicity, Simplicity, Simplicity .sp Many of the most powerful and useful engineering solutions are founded on -simple principals, the Salt SLS system strives to do just that. K.I.S.S. +simple principles. The Salt SLS system strives to do just that. K.I.S.S. .sp The core of the Salt State system is the SLS, or the SaLt State file. The SLS is a representation of the state in which a system should be in, and is set up @@ -2414,7 +3226,7 @@ The minions can also be started in the foreground in debug mode. Start the minion in debug mode with: \fBsalt\-minion \-l debug\fP. .sp Now onto the \fBStates tutorial, part 1\fP. -.SH STATES TUTORIAL, PART 1 +.SS States tutorial, part 1 .sp The purpose of this tutorial is to demonstrate how quickly you can configure a system to be managed by Salt States. For detailed information about the state @@ -2595,7 +3407,7 @@ salt \(aq*\(aq state.highstate \-t 60 # On the master This tutorial focused on getting a simple Salt States configuration working. \fBPart 2\fP will build on this example to cover more advanced \fIsls\fP syntax and will explore more of the states that ship with Salt. -.SH STATES TUTORIAL, PART 2 +.SS States tutorial, part 2 .IP Note This tutorial builds on the topic covered in \fBpart 1\fP. It is recommended that you begin there. @@ -2754,7 +3566,7 @@ explained in \fBPart 3\fP. .sp In \fBpart 3\fP we will discuss how to use includes, extends and templating to make a more complete State Tree configuration. -.SH STATES TUTORIAL, PART 3 +.SS States tutorial, part 3 .IP Note This tutorial builds on the topic covered in \fBpart1\fP and \fBpart 2\fP. It is recommended that you begin there. @@ -2879,578 +3691,214 @@ django: .SS \fIExtend declaration\fP .sp You can modify previous declarations by using an \fIextend declaration\fP. For -example the following modifies the Apache tree to also restart Apache when the -vhosts file is changed: -.sp -\fBapache/apache.sls\fP: -.sp -.nf -.ft C -apache: - pkg.installed -.ft P -.fi -.sp -\fBapache/mywebsite.sls\fP: -.sp -.nf -.ft C -include: - \- apache - -extend: - apache: - service: - \- watch: - \- file: /etc/httpd/extra/httpd\-vhosts.conf - -/etc/httpd/extra/httpd\-vhosts.conf: - file.managed: - \- source: salt://apache/httpd\-vhosts.conf -.ft P -.fi -.IP "Using extend with require or watch" -.sp -The \fBextend\fP statement works differently for \fBrequire\fP or \fBwatch\fP. -It appends to, rather than replacing the requisite component. -.RE -.SS \fIName declaration\fP -.sp -You can override the \fIID declaration\fP by using a \fIname -declaration\fP. For example, the previous example is a bit more maintainable if -rewritten as follows: -.sp -\fBapache/mywebsite.sls\fP: -.sp -.nf -.ft C -include: - \- apache - -extend: - apache: - service: - \- watch: - \- file: mywebsite - -mywebsite: - file.managed: - \- name: /etc/httpd/extra/httpd\-vhosts.conf - \- source: salt://apache/httpd\-vhosts.conf -.ft P -.fi -.SS \fINames declaration\fP -.sp -Even more powerful is using a \fInames declaration\fP to override the -\fIID declaration\fP for multiple states at once. This often can remove the -need for looping in a template. For example, the first example in this tutorial -can be rewritten without the loop: -.sp -.nf -.ft C -stooges: - user.present: - \- names: - \- moe - \- larry - \- curly -.ft P -.fi -.SS Continue learning -.sp -The best way to continue learning about Salt States is to read through the -\fBreference documentation\fP and to look through examples -of existing \fIstate trees\fP. You can find examples in the -\fI\%salt-states repository\fP and please send a pull\-request on GitHub with any -state trees that you build and want to share! -.sp -If you have any questions, suggestions, or just want to chat with other people -who are using Salt we have an \fBactive community\fP. -.SH ACCESS CONTROL SYSTEM -.sp -New in version 0.10.4. -.sp -Salt maintains a standard system used to open granular control to non -administrative users to execute Salt commands. The access control system -has been applied to all systems used to configure access to non administrative -control interfaces in Salt.These interfaces include, the \fBpeer\fP system, the -\fBexternal auth\fP system and the \fBclient acl\fP system. -.sp -The access control system mandated a standard configuration syntax used in -all of the three aforementioned systems. While this adds functionality to the -configuration in 0.10.4, it does not negate the old configuration. -.sp -Now specific functions can be opened up to specific minions from specific users -in the case of external auth and client acls, and for specific minions in the -case of the peer system. -.sp -The access controls are manifest using matchers in these configurations: -.sp -.nf -.ft C -client_acl: - fred: - \- web\e*: - \- pkg.list_pkgs - \- test.* - \- apache.* -.ft P -.fi -.sp -In the above example, fred is able to send commands only to minions which match -the specifieed glob target. This can be expanded to include other functions for -other minions based on standard targets. -.sp -.nf -.ft C -external_auth: - pam: - dave: - \- mongo\e*: - \- network.* - \- log\e*: - \- network.* - \- pkg.* - \- \(aqG@os:RedHat\(aq: - \- kmod.* - \- test.ping -.ft P -.fi -.sp -The above allows for all minions to be hit by test.ping by dave, and adds a -few functions for hitting other minions. -.SH EXTERNAL AUTHENTICATION SYSTEM -.sp -Salt 0.10.4 comes with a fantastic new way to open up running Salt commands -to users. This system allows for Salt itself to pass through authentication to -any authentication system (The Unix PAM system was the first) to determine -if a user has permission to execute a Salt command. -.sp -The external authentication system allows for specific users to be granted -access to execute specific functions on specific minions. Access is configured -in the master configuration file, and uses the new access control system: -.sp -.nf -.ft C -external_auth: - pam: - thatch: - \- \(aqweb*\(aq: - \- test.* - \- network.* -.ft P -.fi -.sp -So, the above allows the user thatch to execute functions in the test and -network modules on the minions that match the web* target. -.sp -The external authentication system can then be used from the command line by -any user on the same system as the master with the \fI\-a\fP option: -.sp -.nf -.ft C -$ salt \-a pam web\e* test.ping -.ft P -.fi -.sp -The system will ask the user for the credentials required by the -authentication system and then publish the command. -.SS Tokens -.sp -With external authentication alone the authentication credentials will be -required with every call to Salt. This can be alleviated with Salt tokens. -.sp -The tokens are short term authorizations and can be easily created by just -adding a capital T option when authenticating: -.sp -.nf -.ft C -$ salt \-T \-a pam web\e* test.ping -.ft P -.fi -.sp -Now a token will be created that has a expiration of, by default, 12 hours. -This token is stored in the active user\(aqs home directory and is now sent with -all subsequent communications, so the authentication does not need to be -declared again until the token expires. -.SH OPENING THE FIREWALL UP FOR SALT -.sp -The Salt master communicates with the minions using an AES\-encrypted ZeroMQ -connection. These communications are done over ports 4505 and 4506, which need -to be accessible on the master only. This document outlines suggested firewall -rules for allowing these incoming connections to the master. -.IP Note -\fBNo firewall configuration needs to be done on Salt minions. These changes -refer to the master only.\fP -.RE -.SS RHEL 6 / CENTOS 6 -.sp -The lokkit command packaged with some linux distributions makes opening -iptables firewall ports very simple via the command line. Just be careful -to not lock out access to the server by neglecting to open the ssh -port. -.sp -\fBlokkit example\fP -.sp -.nf -.ft C -lokkit \-p 22:tcp \-p 4505:tcp \-p 4506:tcp -.ft P -.fi -.sp -The system\-config\-firewall\-tui command provides a text\-based interface to modifying -the firewall. -.sp -\fBsystem\-config\-firewall\-tui\fP -.sp -.nf -.ft C -system\-config\-firewall\-tui -.ft P -.fi -.SS iptables -.sp -Different Linux distributions store their \fI\%iptables\fP rules in different places, -which makes it difficult to standardize firewall documentation. Included are -some of the more common locations, but your mileage may vary. -.sp -\fBFedora / RHEL / CentOS\fP -.sp -.nf -.ft C -/etc/sysconfig/iptables -.ft P -.fi -.sp -\fBArch Linux\fP -.sp -.nf -.ft C -/etc/iptables/iptables.rules -.ft P -.fi -.sp -\fBDebian\fP -.sp -Follow these instructions: \fI\%http://wiki.debian.org/iptables\fP -.sp -Once you\(aqve found your firewall rules, you\(aqll need to add the two lines below -to allow traffic on \fBtcp/4505\fP and \fBtcp/4506\fP: -.sp -.nf -.ft C -\-A INPUT \-m state \-\-state new \-m tcp \-p tcp \-\-dport 4505 \-j ACCEPT -\-A INPUT \-m state \-\-state new \-m tcp \-p tcp \-\-dport 4506 \-j ACCEPT -.ft P -.fi -.sp -\fBUbuntu\fP -.sp -Create a file named \fB/etc/ufw/applications.d/salt\-master\fP -.sp -.nf -.ft C -[Salt Master] -title=Salt master -description=Salt is a remote execution and configuration management tool. -ports=4505,4506/tcp -.ft P -.fi -.SS pf.conf +example the following modifies the Apache tree to also restart Apache when the +vhosts file is changed: .sp -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. +\fBapache/apache.sls\fP: .sp .nf .ft C -pass in on $int_if proto tcp from any to $int_if port 4505 -pass in on $int_if proto tcp from any to $int_if port 4506 +apache: + pkg.installed .ft P .fi .sp -Once these additions have been made to the \fBpf.conf\fP the rules will need to -be reloaded. This can be done using the \fBpfctl\fP command. +\fBapache/mywebsite.sls\fP: .sp .nf .ft C -pfctl \-vf /etc/pf.conf +include: + \- apache + +extend: + apache: + service: + \- watch: + \- file: /etc/httpd/extra/httpd\-vhosts.conf + +/etc/httpd/extra/httpd\-vhosts.conf: + file.managed: + \- source: salt://apache/httpd\-vhosts.conf .ft P .fi -.SH BOOTSTRAPPING SALT ON LINUX EC2 WITH CLOUD-INIT +.IP "Using extend with require or watch" .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 \fI\%AMI\fP, but this creates another resource to maintain and document. +The \fBextend\fP statement works differently for \fBrequire\fP or \fBwatch\fP. +It appends to, rather than replacing the requisite component. +.RE +.SS \fIName declaration\fP .sp -A better method for Linux machines uses Canonical\(aqs \fI\%CloudInit\fP to run a bootstrap script -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 -.IP 1. 3 -Install \fI\%Salt\fP with dependencies -.IP 2. 3 -Point the minion to the master -.UNINDENT +You can override the \fIID declaration\fP by using a \fIname +declaration\fP. For example, the previous example is a bit more maintainable if +rewritten as follows: .sp -Here is a sample script: +\fBapache/mywebsite.sls\fP: .sp .nf .ft C -#!/bin/bash +include: + \- apache -# Install saltstack -add\-apt\-repository ppa:saltstack/salt \-y -apt\-get update \-y -apt\-get install salt\-minion \-y -apt\-get install salt\-master \-y -apt\-get upgrade \-y +extend: + apache: + service: + \- watch: + \- file: mywebsite -# Set salt master location and start minion -cp /etc/salt/minion.template /etc/salt/minion -sed \-i \(aqs/#master: salt/master: [salt_master_fqdn]/\(aq /etc/salt/minion -salt\-minion \-d +mywebsite: + file.managed: + \- name: /etc/httpd/extra/httpd\-vhosts.conf + \- source: salt://apache/httpd\-vhosts.conf .ft P .fi +.SS \fINames declaration\fP .sp -First the script adds the saltstack ppa and installs the package. Then -we copy over the minion config template and tell it where to find the -master. You will have to replace \fB[salt_master_fqdn]\fP with something -that resolves to your Salt master. -.SS Used With Boto -.sp -\fI\%Boto\fP will accept a string for user data -which can be used to pass our bootstrap script. If the script is saved to -a file, you can read it into a string: +Even more powerful is using a \fInames declaration\fP to override the +\fIID declaration\fP for multiple states at once. This often can remove the +need for looping in a template. For example, the first example in this tutorial +can be rewritten without the loop: .sp .nf .ft C -import boto - -user_data = open(\(aqsalt_bootstrap.sh\(aq) - -conn = boto.connect_ec2(, ) - -reservation = conn.run_instances(image_id=, - key_name=, - user_data=user_data.read()) +stooges: + user.present: + \- names: + \- moe + \- larry + \- curly .ft P .fi -.SS Additional Notes -.sp -Sometime in the future the ppa will include and install an upstart file. In the -meantime, you can use the bootstrap to \fI\%build one\fP. -.sp -It may also be useful to set the node\(aqs role during this phase. One option -would be saving the node\(aqs role to a file and then using a custom Grain -to select it. -.SH AUTOMATIC UPDATES / FROZEN DEPLOYMENTS -.sp -New in version 0.10.3.d. -.sp -Salt has support for the -\fI\%Esky\fP application freezing and update -tool. This tool allows one to build a complete zipfile out of the salt scripts -and all their dependencies \- including shared objects / DLLs. -.SS Getting Started -.sp -To build frozen applications, you\(aqll need a suitable build environment for each -of your platforms. You should probably set up a virtualenv in order to limit -the scope of Q/A. -.sp -This process does work on Windows. Follow the directions at -\fI\%https://github.com/saltstack/salt-windows-install\fP for details on -installing Salt in Windows. Only the 32\-bit Python and dependencies have been -tested, but they have been tested on 64\-bit Windows. -.sp -You will need to install \fBesky\fP and \fBbbfreeze\fP from Pypi in order to enable -the \fBbdist_esky\fP command in \fBsetup.py\fP. -.SS Building and Freezing -.sp -Once you have your tools installed and the environment configured, you can then -\fBpython setup.py bdist\fP to get the eggs prepared. After that is done, run -\fBpython setup.py bdist_esky\fP to have Esky traverse the module tree and pack -all the scripts up into a redistributable. There will be an appropriately -versioned \fBsalt\-VERSION.zip\fP in \fBdist/\fP if everything went smoothly. -.SS Windows -.sp -You will need to add \fBC:\ePython27\elib\esite\-packages\ezmq\fP to your PATH -variable. This helps bbfreeze find the zmq dll so it can pack it up. -.SS Using the Frozen Build -.sp -Unpack the zip file in your desired install location. Scripts like -\fBsalt\-minion\fP and \fBsalt\-call\fP will be in the root of the zip file. The -associated libraries and bootstrapping will be in the directories at the same -level. (Check the \fI\%Esky\fP documentation -for more information) +.SS Continue learning .sp -To support updating your minions in the wild, put your builds on a web server -that your minions can reach. \fBsalt.modules.saltutil.update()\fP will -trigger an update and (optionally) a restart of the minion service under the -new version. -.SS Gotchas -.SS My Windows minion isn\(aqt responding +The best way to continue learning about Salt States is to read through the +\fBreference documentation\fP and to look through examples +of existing \fIstate trees\fP. You can find examples in the +\fI\%salt-states repository\fP and please send a pull\-request on GitHub with any +state trees that you build and want to share! .sp -The process dispatch on Windows is slower than it is on *nix. You may need to -add \(aq\-t 15\(aq to your salt calls to give them plenty of time to return. -.SS Windows and the Visual Studio Redist +If you have any questions, suggestions, or just want to chat with other people +who are using Salt we have an \fBactive community\fP. +.SH ACCESS CONTROL SYSTEM .sp -You will need to install the Visual C++ 2008 32\-bit redistributable on all -Windows minions. Esky has an option to pack the library into the zipfile, -but OpenSSL does not seem to acknowledge the new location. If you get a -\fBno OPENSSL_Applink\fP error on the console when trying to start your -frozen minion, you have forgotten to install the redistributable. -.SS Mixed Linux environments and Yum +New in version 0.10.4. .sp -The Yum Python module doesn\(aqt appear to be available on any of the standard -Python package mirrors. If you need to support RHEL/CentOS systems, you -should build on that platform to support all your Linux nodes. Also remember -to build your virtualenv with \fB\-\-system\-site\-packages\fP so that the -\fByum\fP module is included. -.SS Automatic (Python) module discovery +Salt maintains a standard system used to open granular control to non +administrative users to execute Salt commands. The access control system +has been applied to all systems used to configure access to non administrative +control interfaces in Salt.These interfaces include, the \fBpeer\fP system, the +\fBexternal auth\fP system and the \fBclient acl\fP system. .sp -Automatic (Python) module discovery does not work with the late\-loaded scheme that -Salt uses for (Salt) modules. You will need to explicitly add any -misbehaving modules to the \fBfreezer_includes\fP in Salt\(aqs \fBsetup.py\fP. -Always check the zipped application to make sure that the necessary modules -were included. -.SH PRESEED MINION WITH ACCEPTED KEY +The access control system mandated a standard configuration syntax used in +all of the three aforementioned systems. While this adds functionality to the +configuration in 0.10.4, it does not negate the old configuration. .sp -In some situations, it is not convenient to wait for a minion to start before -accepting its key on the master. For instance, you may want the minion to -bootstrap itself as soon as it comes online. You may also want to to let your -developers provision new development machines on the fly. +Now specific functions can be opened up to specific minions from specific users +in the case of external auth and client acls, and for specific minions in the +case of the peer system. .sp -There is a general four step process to do this: -.INDENT 0.0 -.IP 1. 3 -Generate the keys on the master: +The access controls are manifest using matchers in these configurations: .sp .nf .ft C -root@saltmaster# salt\-key \-\-gen\-keys=[key_name] +client_acl: + fred: + \- web\e*: + \- pkg.list_pkgs + \- test.* + \- apache.* .ft P .fi -.UNINDENT .sp -Pick a name for the key, such as the minion\(aqs id. -.INDENT 0.0 -.IP 2. 3 -Add the public key to the accepted minion folder: +In the above example, fred is able to send commands only to minions which match +the specifieed glob target. This can be expanded to include other functions for +other minions based on standard targets. .sp .nf .ft C -root@saltmaster# cp key_name.pub /etc/salt/pki/master/minions/[minion_id] +external_auth: + pam: + dave: + \- mongo\e*: + \- network.* + \- log\e*: + \- network.* + \- pkg.* + \- \(aqG@os:RedHat\(aq: + \- kmod.* + \- test.ping .ft P .fi -.UNINDENT -.sp -It is necessary that the public key file has the same name as your minion id. -This is how Salt matches minions with their keys. Also note that the pki folder -could be in a different location, depending on your OS or if specified in the -master config file. -.INDENT 0.0 -.IP 3. 3 -Distribute the minion keys. -.UNINDENT .sp -There is no single method to get the keypair to your minion. If you are -spooling up minions on EC2, you could pass them in using user_data or a -cloud\-init script. If you are handing them off to a team of developers for provisioning dev machines, you will need a secure file transfer. -.IP "Security Warning" +The above allows for all minions to be hit by test.ping by dave, and adds a +few functions for hitting other minions. +.SH EXTERNAL AUTHENTICATION SYSTEM .sp -Since the minion key is already accepted on the master, distributing -the private key poses a potential security risk. A malicious party -will have access to your entire state tree and other sensitive data. -.RE -.INDENT 0.0 -.IP 4. 3 -Preseed the Minion with the keys -.UNINDENT +Salt 0.10.4 comes with a fantastic new way to open up running Salt commands +to users. This system allows for Salt itself to pass through authentication to +any authentication system (The Unix PAM system was the first) to determine +if a user has permission to execute a Salt command. .sp -You will want to place the minion keys before starting the salt\-minion daemon: +The external authentication system allows for specific users to be granted +access to execute specific functions on specific minions. Access is configured +in the master configuration file, and uses the new access control system: .sp .nf .ft C -/etc/salt/pki/minion/minion.pem -/etc/salt/pki/minion/minion.pub +external_auth: + pam: + thatch: + \- \(aqweb*\(aq: + \- test.* + \- network.* .ft P .fi .sp -Once in place, you should be able to start salt\-minion and run -\fBsalt\-call state.highstate\fP or any other salt commands that require master -authentication. -.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 +So, the above allows the user thatch to execute functions in the test and +network modules on the minions that match the web* target. .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. +The external authentication system can then be used from the command line by +any user on the same system as the master with the \fI\-a\fP option: .sp .nf .ft C -file_client: local +$ salt \-a pam web\e* test.ping .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 +The system will ask the user for the credentials required by the +authentication system and then publish the command. +.SS Tokens .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: +With external authentication alone the authentication credentials will be +required with every call to Salt. This can be alleviated with Salt tokens. +.sp +The tokens are short term authorizations and can be easily created by just +adding a capital T option when authenticating: .sp .nf .ft C -file_roots: - base: - \- /srv/salt +$ salt \-T \-a pam web\e* test.ping .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. +Now a token will be created that has a expiration of, by default, 12 hours. +This token is stored in the active user\(aqs home directory and is now sent with +all subsequent communications, so the authentication does not need to be +declared again until the token expires. .SH PILLAR OF SALT .sp 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. .sp -Pillar was added to Salt in version 0.9.8 as an experimental add on. +Pillar was added to Salt in version 0.9.8 +.IP Note +Storing sensitive data +.sp +Unlike state tree, pillar data is only available for the targetted +minion specified by the matcher type. This makes it useful for +storing sensitive data specific to a particular minion. +.RE .SS Declaring the Master Pillar .sp The Salt Master server maintains a pillar_roots setup that matches the @@ -3473,8 +3921,8 @@ pillar_roots: .fi .sp This example configuration declares that the base environment will be located -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: +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 @@ -3486,9 +3934,18 @@ base: .ft P .fi .sp -This further example shows how to enable pcre matching in the salt pillar file. -The flexibility enabled by pcre matching is particularly useful in salt pillar -files. +This further example shows how to use other standard top matching types (grain +matching is used in this example) to deliver specific salt pillar data to minions +with different \(aqos\(aq grains: +.sp +.nf +.ft C +dev: + \(aqos:Debian\(aq: + \- match: grain + \- servers +.ft P +.fi .sp \fB/srv/pillar/packages.sls\fP .sp @@ -3527,7 +3984,9 @@ git: .SS Viewing Minion Pillar .sp Once the pillar is set up the data can be viewed on the minion via the -\fBpillar.data\fP module: +\fBpillar\fP module, the pillar module comes with two functions, \fBpillar.data\fP +and \fBpillar.raw\fP. \fBpillar.data\fP will return a freshly reloaded pillar and +\fBpillar.raw\fP wil return the current pillar without a refresh: .sp .nf .ft C @@ -3547,6 +4006,9 @@ locally. This is done with the \fBsaltutil.refresh_pillar\fP function. salt \(aq*\(aq saltutil.refresh_pillar .ft P .fi +.sp +This function triggers the minion to refresh the pillar and will always return +\fBTrue\fP .SS Targeting with Pillar .sp Pillar data can be used when targeting minions. This allows for ultimate @@ -3661,19 +4123,19 @@ that have already, or partially returned. # salt\-run jobs.list_jobs .ft P .fi -.SH SALT SCHEDULEING +.SH SALT SCHEDULING .sp -Introduced in Salt 0.12.0, the scheduling system is a powerful tool for -creating incremental executions on minions or the master. The schedule system -exposes the execution of any execution function on minions or any runner on -the master. +In Salt versions greater than 0.12.0, the scheduling system allows incremental +executions on minions or the master. The schedule system exposes the execution +of any execution function on minions or any runner on the master. .sp To set up the scheduler on the master add the schedule option to the master -config file, to set up the scheduler on the minion add the schedule option to +config file. +.sp +To set up the scheduler on the minion add the schedule option to the minion config file or to the minion\(aqs pillar. .sp -The schedule option defines jobs which execute at certain intervals. The salt -scheduler only supports interval assignments in 0.12.0. To set up a highstate +The schedule option defines jobs which execute at certain intervals. To set up a highstate to run on a minion every 60 minutes set this in the minion config or pillar: .sp .nf @@ -4227,75 +4689,136 @@ A few examples of salt states from the community: \fI\%https://github.com/rentalita/ubuntu-setup/\fP .IP \(bu 2 \fI\%https://github.com/brutasse/states\fP +.IP \(bu 2 +\fI\%https://github.com/bclermont/states\fP +.IP \(bu 2 +\fI\%https://github.com/pcrews/salt-data\fP .UNINDENT .SS Follow on ohloh .sp \fI\%https://www.ohloh.net/p/salt\fP +.SS Other community links +.INDENT 0.0 +.IP \(bu 2 +\fI\%Salt Stack Inc.\fP +.IP \(bu 2 +\fI\%Subreddit\fP +.IP \(bu 2 +\fI\%Google+\fP +.IP \(bu 2 +\fI\%YouTube\fP +.IP \(bu 2 +\fI\%Facebook\fP +.IP \(bu 2 +\fI\%Twitter\fP +.IP \(bu 2 +\fI\%Wikipedia page\fP +.UNINDENT .SS Developing Salt .sp -If you want to help develop Salt there is a great need and your patches are -welcome! +There is a great need for contributions to salt and patches are welcome! The goal +here is to make contributions clear, make sure there is a trail for where the code +has come from, and most importantly, to give credit where credit is due! .sp -To assist in Salt development, you can help in a number of ways. -.SS Setting a Github pull request +There are a number of ways to contribute to salt development. +.SS Sending a Github pull request .sp -This is the preferred method for contributions, simply create a Github -fork, commit your changes to the fork, and then open up a pull request. -If you want to make our life really easier, please also enable Travis\-CI on -your fork. Salt is already configured, all you need to do is follow the first -two(2) steps on their \fI\%Getting Started Doc\fP. -.SS Posting patches to the mailing list +This is the preferred method for contributions. Simply create a Github +fork, commit changes to the fork, and then open up a pull request. .sp -If you have a patch for Salt, please format it via \fBgit format\-patch\fP -and send it to the Salt users mailing list. This allows the patch to give you -the contributor the credit for your patch, and gives the Salt community an -archive of the patch and a place for discussion. -.SS Contributions Welcome! +The following is an example (from \fI\%Open Comparison Contributing Docs\fP ) +of an efficient workflow for forking, cloning, branching, committing, and +sending a pull request for a github repository. .sp -The goal here is 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! +First, make a local clone of your github fork of the salt github repo and make edits and +changes locally. .sp -The \fI\%Open Comparison Contributing Docs\fP explains the workflow for forking, -cloning, branching, committing, and sending a pull request for the git -repository. +Then, create a new branch on your clone by entering the following commands: .sp -\fBgit pull upstream develop\fP is a shorter way to update your local repository -to the latest version. -.SS Editing and Previewing the Docs +.nf +.ft C +git checkout \-b fixed\-broken\-thing + +Switched to a new branch \(aqfixed\-broken\-thing\(aq +.ft P +.fi .sp -You need \fBsphinx\-build\fP to build the docs. In Debian/Ubuntu this is provided -in the \fBpython\-sphinx\fP package. +Choose a name for your branch that describes its purpose. .sp -Then: +Now commit your changes to this new branch with the following command: .sp .nf .ft C -cd doc; make html +#add and commit all changes at once +git commit \-a \-m \(aqdescription of my fixes for the broken thing\(aq .ft P .fi -.INDENT 0.0 -.IP \(bu 2 -The docs then are built in the \fBdocs/_build/html/\fP folder. If you make -changes and want to see the results, \fBmake html\fP again. -.IP \(bu 2 -The docs use \fBreStructuredText\fP for markup. See a live demo at -\fI\%http://rst.ninjs.org/\fP. -.IP \(bu 2 -The help information on each module or state is culled from the python code -that runs for that piece. Find them in \fBsalt/modules/\fP or \fBsalt/states/\fP. -.IP \(bu 2 -If you are developing using Arch Linux (or any other distribution for which -Python 3 is the default Python installation), then \fBsphinx\-build\fP may be -named \fBsphinx\-build2\fP instead. If this is the case, then you will need to -run the following \fBmake\fP command: +.sp +And then push your locally committed changes back up to GitHub: .sp .nf .ft C -make SPHINXBUILD=sphinx\-build2 html +git push \-\-set\-upstream origin fixed\-broken\-thing .ft P .fi -.UNINDENT +.sp +Now go look at your fork of the salt repo on the GitHub website. The new +branch will now be listed under the "Source" tab where it says "Switch Branches". +Select the new branch from this list, and then click the "Pull request" button. +.sp +Put in a descriptive comment, and include links to any project issues related to the pull request. +.sp +The repo managers will be notified of your pull request and it will +be reviewed. If a reviewer asks for changes, just make the changes locally in the +same local feature branch, push them to GitHub, then add a comment to the +discussion section of the pull request. +.IP Note +Travis\-CI +.sp +To make reviewing pull requests easier for the maintainers, please enable Travis\-CI on +the fork. Salt is already configured, so simply follow the first +2 steps on the Travis\-CI \fI\%Getting Started Doc\fP. +.RE +.SS Keeping Salt Forks in Sync +.sp +Salt is advancing quickly. It is therefore critical to pull upstream changes from master into forks on a regular basis. Nothing is worse than putting in a days of hard work into a pull request only to have it rejected because it has diverged too far from master. +.sp +To pull in upstream changes: +.sp +.nf +.ft C +# For ssh github +git remote add upstream git@github.com:saltstack/salt.git +git fetch upstream + +# For https github +git remote add upstream https://github.com/saltstack/salt.git +git fetch upstream +.ft P +.fi +.sp +To check the log to be sure that you actually want the changes, run this before merging: +.sp +.nf +.ft C +git log upstream/develop +.ft P +.fi +.sp +Then to accept the changes and merge into the current branch: +.sp +.nf +.ft C +git merge upstream/develop +.ft P +.fi +.sp +For more info, see \fI\%Github Fork a Repo Guide\fP or \fI\%Open Comparison Contributing Docs\fP +.SS Posting patches to the mailing list +.sp +Patches will also be accepted by email. Format patches using \fI\%git format-patch\fP +and send them to the Salt users mailing list. The contributor will then get credit +for the patch, and the Salt community will have an archive of the patch and a place for discussion. .SS Installing Salt for development .sp Clone the repository using: @@ -4305,6 +4828,28 @@ Clone the repository using: git clone https://github.com/saltstack/salt .ft P .fi +.IP Note +tags +.sp +Just cloning the repository is enough to work with Salt and make +contributions. However, fetching additional tags from git is required to +have Salt report the correct version for itself. To do this, first +add the git repository as an upstream source: +.sp +.nf +.ft C +git remote add upstream http://github.com/saltstack/salt +.ft P +.fi +.sp +Fetching tags is done with the git \(aqfetch\(aq utility: +.sp +.nf +.ft C +git fetch \-\-tags upstream +.ft P +.fi +.RE .sp Create a new \fI\%virtualenv\fP: .sp @@ -4317,15 +4862,13 @@ virtualenv /path/to/your/virtualenv On Arch Linux, where Python 3 is the default installation of Python, use the \fBvirtualenv2\fP command instead of \fBvirtualenv\fP. .IP Note -Using your system Python modules in the virtualenv -.sp -If you have the required python modules installed on your system already -and would like to use them in the virtualenv rather than having pip -download and compile new ones into this environment, run \fBvirtualenv\fP -with the \fB\-\-system\-site\-packages\fP option. If you do this, you can skip -the pip command below that installs the dependencies (pyzmq, M2Crypto, -etc.), assuming that the listed modules are all installed in your system -PYTHONPATH at the time you create your virtualenv. +Using system Python modules in the virtualenv +.sp +To use already\-installed python modules in virtualenv (instead of having pip +download and compile new ones), run \fBvirtualenv \-\-system\-site\-packages\fP +Using this method eliminates the requirement to install the salt dependencies +again, although it does assume that the listed modules are all installed in the +system PYTHONPATH at the time of virtualenv creation. .RE .sp Activate the virtualenv: @@ -4348,9 +4891,9 @@ pip install \-e ./salt # the path to the salt git clone from above .IP Note Installing M2Crypto .sp -You may need \fBswig\fP and \fBlibssl\-dev\fP to build M2Crypto. If you -encounter the error \fBcommand \(aqswig\(aq failed with exit status 1\fP -while installing M2Crypto, try installing it with the following command: +\fBswig\fP and \fBlibssl\-dev\fP are required to build M2Crypto. To fix +the error \fBcommand \(aqswig\(aq failed with exit status 1\fP while installing M2Crypto, +try installing it with the following command: .sp .nf .ft C @@ -4361,19 +4904,20 @@ env SWIG_FEATURES="\-cpperraswarn \-includeall \-D__\(gauname \-m\(ga__ \-I/usr/ Debian and Ubuntu systems have modified openssl libraries and mandate that a patched version of M2Crypto be installed. This means that M2Crypto needs to be installed via apt: -.INDENT 0.0 -.INDENT 3.5 +.sp +.nf +.ft C apt\-get install python\-m2crypto -.UNINDENT -.UNINDENT +.ft P +.fi .sp -This also means that you should use \fB\-\-system\-site\-packages\fP when -creating the virtualenv, to pull in the M2Crypto installed using apt. +This also means that pulling in the M2Crypto installed using apt requires using +\fB\-\-system\-site\-packages\fP when creating the virtualenv. .RE .IP Note Important note for those developing using RedHat variants .sp -If you are developing on a RedHat variant, be advised that the package +For developers using a RedHat variant, be advised that the package provider for newer Redhat\-based systems (\fByumpkg.py\fP) relies on RedHat\(aqs python interface for yum. The variants that use this module to provide package support include the following: @@ -4386,9 +4930,14 @@ support include the following: \fI\%Amazon Linux\fP .UNINDENT .sp -If you are developing using one of these releases, you will want to create -your virtualenv using the \fB\-\-system\-site\-packages\fP option so that these -modules are available in the virtualenv. +Developers using one of these systems should create the salt virtualenv using the +\fB\-\-system\-site\-packages\fP option to ensure that the correct modules are available. +.RE +.IP Note +Installing dependencies on OS X. +.sp +You can install needed dependencies on OS X using homebrew or macports. +See \fBOS X Installation\fP .RE .SS Running a self\-contained development version .sp @@ -4489,24 +5038,24 @@ length. Remember that this path is relative to the value you set in .sp \fBNOTE:\fP The socket path is limited to 107 characters on Solaris and Linux, and 103 characters on BSD\-based systems. -.SS File descriptor limit +.IP Note +File descriptor limits .sp -Check your file descriptor limit with: +Ensure that the system open file limit is raised to at least 2047: .sp .nf .ft C +# check your current limit ulimit \-n -.ft P -.fi -.sp -If it is less than 2047, you should increase it with: -.sp -.nf -.ft C + +# raise the limit. persists only until reboot +# use \(aqlimit descriptors 2047\(aq for c\-shell ulimit \-n 2047 -(or "limit descriptors 2047" for c\-shell) .ft P .fi +.sp +To set file descriptors on OSX, refer to the \fBOS X Installation\fP instructions. +.RE .SS Running the tests .sp You will need \fBmock\fP to run the tests: @@ -4540,6 +5089,47 @@ For greater control while running the tests, please try: \&./tests/runtests.py \-h .ft P .fi +.SS Editing and previewing the documention +.sp +You need \fBsphinx\-build\fP command to build the docs. In Debian/Ubuntu this is provided +in the \fBpython\-sphinx\fP package. You can also install this directly to your virtual +environment using pip: +.sp +.nf +.ft C +pip install Sphinx +.ft P +.fi +.sp +Change to salt documention directory, then: +.sp +.nf +.ft C +cd doc; make html +.ft P +.fi +.INDENT 0.0 +.IP \(bu 2 +The docs then are built in the \fBdocs/_build/html/\fP folder. If you make +changes and want to see the results, \fBmake html\fP again. +.IP \(bu 2 +The docs use \fI\%reStructuredText\fP for markup. +See a live demo at \fI\%http://rst.ninjs.org/\fP. +.IP \(bu 2 +The help information on each module or state is culled from the python code +that runs for that piece. Find them in \fBsalt/modules/\fP or \fBsalt/states/\fP. +.IP \(bu 2 +If you are developing using Arch Linux (or any other distribution for which +Python 3 is the default Python installation), then \fBsphinx\-build\fP may be +named \fBsphinx\-build2\fP instead. If this is the case, then you will need to +run the following \fBmake\fP command: +.sp +.nf +.ft C +make SPHINXBUILD=sphinx\-build2 html +.ft P +.fi +.UNINDENT .SH SALT BASED PROJECTS .sp A number of unofficial open source projects, based on Salt, or written to @@ -4872,7 +5462,8 @@ This system binds sls files to event tags on the master. These sls files then define reactions. This means that the reactor system has two parts. First, the reactor option needs to be set in the master configuration file. The reactor option allows for event tags to be associated with sls reaction files. Second, -these reaction files use highdata to define reactions to be executed. +these reaction files use highdata (like the state system) to define reactions +to be executed. .SS Event System .sp A basic understanding of the event system is required to understand reactors. @@ -4889,7 +5480,7 @@ event. .sp The event tag and data are both critical when working with the reactor system. In the master configuration file under the reactor option, tags are associated -with lists of reactor sls files (globs can be used for matching): +with lists of reactor sls formulas (globs can be used for matching): .sp .nf .ft C @@ -4931,13 +5522,69 @@ state.highstate. Similarly, a runner can be called: .ft C {% if data[\(aqdata\(aq][\(aqoverstate\(aq] == \(aqrefresh\(aq %} overstate_run: - runner.state.overstate + runner.state.over {% endif %} .ft P .fi .sp This example will execute the state.overstate runner and initiate an overstate execution. +.SS Understanding the Structure of Reactor Formulas +.sp +While the reactor system uses the same data structure as the state system, this +data does not translate the same way to operations. In state formulas +information is mapped to the state functions, but in the reactor system +information is mapped to a number of available subsystems on the master. These +systems are the \fILocalClient\fP and the \fIRunners\fP. The \fIstate declaration\fP field +takes a reference to the function to call in each interface. So to trigger a +salt\-run call the \fIstate declaration\fP field will start with \fIrunner\fP, followed +by the runner function to call. This means that a call to what would be on the +command line \fIsalt\-run manage.up\fP will be \fIrunner.manage.up\fP. An example of +this in a reactor formula would look like this: +.sp +.nf +.ft C +manage_up: + runner.manage.up +.ft P +.fi +.sp +If the runner takes arguments then they can be specified as well: +.sp +.nf +.ft C +overstate_dev_env: + runner.state.over: + \- env: dev +.ft P +.fi +.sp +Executing remote commands maps to the \fILocalClient\fP interface which is used by +the \fIsalt\fP command. This interface more specifically maps to the \fIcmd_async\fP +method inside of the \fILocalClient\fP class. This means that the arguments passed +are being passed to the \fIcmd_async\fP method, not the remote method. The field +starts with \fIcmd\fP to use the \fILocalClient\fP subsystem. The result is that to +execute a remote command it looks like this: +.sp +.nf +.ft C +clean_tmp: + cmd.cmd.run: + \- tgt: \(aq*\(aq + \- arg: + \- rm \-rf /tmp/* +.ft P +.fi +.sp +The \fIarg\fP option takes a list of arguments as they would be presented on the +command line, so the above declaration is the same as running this salt +command: +.sp +.nf +.ft C +salt \e* cmd.run \(aqrm \-rf /tmp/*\(aq +.ft P +.fi .SH SALT CODING STYLE .sp Salt is developed with a certain coding style, while the style is dominantly @@ -5180,6 +5827,370 @@ The point release is only designated by tagging the commit on the release branch with release number using the existing convention (version 0.11.1 is tagged with v0.11.1). From the tag point a new source tarball is generated and published to Pypi, and a release announcement is made. +.SH SALT DEVELOPMENT GUIDELINES +.SS Dunder Dictionaries +.sp +Salt provides several special "dunder" dictionaries as a convenience for Salt +development. These include \fB__opts__\fP, \fB__context__\fP, \fB__salt__\fP, and +others. This document will describe each dictionary and detail where they exist +and what information and/or functionality they provide. +.SS __context__ +.sp +\fB__context__\fP exists in state modules and execution modules. +.sp +During a state run the \fB__context__\fP dictionary persists across all states +that are run and then is destroyed when the state ends. +.sp +When running an execution module \fB__context__\fP persists across all module +executions until the modules are refreshed; such as when \fBsaltutils.sync_all\fP +or \fBstate.highstate\fP are executed. +.sp +A great place to see how to use \fB__context__\fP is in the cp.py module in +salt/modules/cp.py. The fileclient authenticates with the master when it is +instantiated and then is used to copy files to the minion. Rather than create a +new fileclient for each file that is to be copied down, one instance of the +fileclient is instantiated in the \fB__context__\fP dictionary and is reused for +each file. Here is an example from salt/modules/cp.py: +.sp +.nf +.ft C +if not \(aqcp.fileclient\(aq in __context__: + __context__[\(aqcp.fileclient\(aq] = salt.fileclient.get_file_client(__opts__) +.ft P +.fi +.IP Note +Because __context__ may or may not have been destroyed, always be +sure to check for the existence of the key in __context__ and +generate the key before using it. +.RE +.SS Package Providers +.sp +This page contains guidelines for writing package providers. +.SS Package Functions +.sp +One of the most important features of Salt is package management. There is no +shortage of package managers, so in the interest of providing a consistent +experience in \fBpkg\fP states, there are certain functions +that should be present in a package provider. Note that these are subject to +change as new features are added or existing features are enhanced. +.SS list_pkgs +.sp +This function should declare an empty dict, and then add packages to it by +calling \fBpkg_resource.add_pkg\fP, like +so: +.sp +.nf +.ft C +__salt__[\(aqpkg_resource.add_pkg\(aq](ret, name, version) +.ft P +.fi +.sp +The last thing that should be done before returning is to execute +\fBpkg_resource.sort_pkglist\fP. This +function does not presently do anything to the return dict, but will be used in +future versions of Salt. +.sp +.nf +.ft C +__salt__[\(aqpkg_resource.sort_pkglist\(aq](ret) +.ft P +.fi +.sp +\fBlist_pkgs\fP returns a dictionary of installed packages, with the keys being +the package names and the values being the version installed. Example return +data: +.sp +.nf +.ft C +{\(aqfoo\(aq: \(aq1.2.3\-4\(aq, + \(aqbar\(aq: \(aq5.6.7\-8\(aq} +.ft P +.fi +.SS available_version +.sp +Accepts an arbitrary number of arguments. Each argument is a package name. The +return value for a package will be an empty string if the package is not found +or if the package is up\-to\-date. The only case in which a non\-empty string is +returned is if the package is available for new installation (i.e. not already +installed) or if there is an upgrade available. +.sp +If only one argument was passed, this function return a string, otherwise a +dict of name/version pairs is returned. +.SS version +.sp +Like \fBavailable_version\fP, accepts an arbitrary number of arguments and +returns a string if a single package name was passed, or a dict of name/value +pairs if more than one was passed. The only difference is that the return +values are the currently\-installed versions of whatever packages are passed. If +the package is not installed, an empty string is returned for that package. +.SS upgrade_available +.sp +Deprecated and destined to be removed. For now, should just do the following: +.sp +.nf +.ft C +return __salt__[\(aqpkg.available_version\(aq](name) != \(aq\(aq +.ft P +.fi +.SS install +.sp +The following arguments are required and should default to \fBNone\fP: +.INDENT 0.0 +.IP 1. 3 +name (for single\-package pkg states) +.IP 2. 3 +pkgs (for multiple\-package pkg states) +.IP 3. 3 +sources (for binary package file installation) +.UNINDENT +.sp +The first thing that this function should do is call +\fBpkg_resource.parse_targets\fP +(see below). This function will convert the SLS input into a more easily parsed +data structure. +\fBpkg_resource.parse_targets\fP may +need to be modified to support your new package provider, as it does things +like parsing package metadata which cannot be done for every package management +system. +.sp +.nf +.ft C +pkg_params, pkg_type = __salt__[\(aqpkg_resource.parse_targets\(aq](name, + pkgs, + sources) +.ft P +.fi +.sp +Two values will be returned to the \fBinstall\fP function. The first of +them will be a dictionary. The keys of this dictionary will be package names, +though the values will differ depending on what kind of installation is being +done: +.INDENT 0.0 +.IP \(bu 2 +If \fBname\fP was provided (and \fBpkgs\fP was not), then there will +be a single key in the dictionary, and its value will be \fBNone\fP. Once the +data has been returned, if the \fBversion\fP keyword argument was +provided, then it should replace the \fBNone\fP value in the dictionary. +.IP \(bu 2 +If \fBpkgs\fP was provided, then \fBname\fP is ignored, and the +dictionary will contain one entry for each package in the \fBpkgs\fP +list. The values in the dictionary will be \fBNone\fP if a version was not +specified for the package, and the desired version if specified. See the +\fBMultiple Package Installation Options\fP section of the +\fBpkg.installed\fP state for more info. +.IP \(bu 2 +If \fBsources\fP was provided, then \fBname\fP is ignored, and the +dictionary values will be the path/URI for the package. +.UNINDENT +.sp +The second return value will be a string with two possbile values: +\fBrepository\fP or \fBfile\fP. The \fBinstall\fP function can use this value +(if necessary) to build the proper command to install the targeted package(s). +.sp +Both before and after the installing the target(s), you should run +\fBlist_pkgs\fP to obtain a list of the installed packages. You should then +return the output of +\fBpkg_resource.find_changes\fP: +.sp +.nf +.ft C +return __salt__[\(aqpkg_resource.find_changes\(aq](old, new) +.ft P +.fi +.SS remove +.sp +Removes the passed package and return a list of the packages removed. +.SS Package Repo Functions +.sp +There are some functions provided by \fBpkg\fP which are specific to package +repositories, and not to packages themselves. When writing modules for new +package managers, these functions should be made available as stated below, in +order to provide compatibility with the \fBpkgrepo\fP state. +.sp +All repo functions should accept a basedir option, which defines which +directory repository configuration should be found in. The default for this +is dictated by the repo manager that is being used, and rarely needs to be +changed. +.sp +.nf +.ft C +basedir = \(aq/etc/yum.repos.d\(aq +__salt__[\(aqpkg.list_repos\(aq](basedir) +.ft P +.fi +.SS list_repos +.sp +Lists the repositories that are currently configured on this system. +.sp +.nf +.ft C +__salt__[\(aqpkg.list_repos\(aq]() +.ft P +.fi +.sp +Returns a dictionary, in the following format: +.sp +.nf +.ft C +{\(aqreponame\(aq: \(aqconfig_key_1\(aq: \(aqconfig value 1\(aq, + \(aqconfig_key_2\(aq: \(aqconfig value 2\(aq, + \(aqconfig_key_3\(aq: [\(aqlist item 1 (when appropriate)\(aq, + \(aqlist item 2 (when appropriate)]} +.ft P +.fi +.SS get_repo +.sp +Displays all local configuration for a specific repository. +.sp +.nf +.ft C +__salt__[\(aqpkg.get_repo\(aq](repo=\(aqmyrepo\(aq) +.ft P +.fi +.sp +The information is formatted in much the same way as list_repos, but is +specific to only one repo. +.sp +.nf +.ft C +{\(aqconfig_key_1\(aq: \(aqconfig value 1\(aq, + \(aqconfig_key_2\(aq: \(aqconfig value 2\(aq, + \(aqconfig_key_3\(aq: [\(aqlist item 1 (when appropriate)\(aq, + \(aqlist item 2 (when appropriate)]} +.ft P +.fi +.SS del_repo +.sp +Removes the local configuration for a specific repository. Requires a \fIrepo\fP +argument, which must match the locally configured name. This function returns +a string, which informs the user as to whether or not the operation was a +success. +.sp +.nf +.ft C +__salt__[\(aqpkg.del_repo\(aq](repo=\(aqmyrepo\(aq) +.ft P +.fi +.SS mod_repo +.sp +Modify the local configuration for one or more option for a conifigured repo. +This is also the way to create new repository configuration on the local +system; if a repo is specified which does not yet exist, it will be created. +.sp +The options specified for this function are specific to the system; please +refer to the documentation for your specific repo manager for specifics. +.sp +.nf +.ft C +__salt__[\(aqpkg.mod_repo\(aq](repo=\(aqmyrepo\(aq, url=\(aqhttp://myurl.com/repo\(aq) +.ft P +.fi +.SS Low\-Package Functions +.sp +In general, the standard package functions as describes above will meet your +needs. These functions use the system\(aqs native repo manager (for instance, +yum or the apt tools). In most cases, the repo manager is actually separate +from the package manager. For instance, yum is usually a front\-end for rpm, and +apt is usually a front\-end for dpkg. When possible, the package functions that +use those package managers directly should do so through the low package +functions. +.sp +It is normal and sane for \fBpkg\fP to make calls to \fBlowpkgs\fP, but \fBlowpkg\fP +must never make calls to \fBpkg\fP. This is affects functions which are required +by both \fBpkg\fP and \fBlowpkg\fP, but the technique in \fBpkg\fP is more performant +than what is available to \fBlowpkg\fP. When this is the case, the \fBlowpkg\fP +function that requires that technique must still use the \fBlowpkg\fP version. +.SS list_pkgs +.sp +Returns a dict of packages installed, including the package name and version. +Can accept a list of packages; if none are spcified, then all installed +packages will be listed. +.sp +.nf +.ft C +installed = __salt__[\(aqlowpkg.list_pkgs\(aq](\(aqfoo\(aq, \(aqbar\(aq) +.ft P +.fi +.sp +Example output: +.sp +.nf +.ft C +{\(aqfoo\(aq: \(aq1.2.3\-4\(aq, + \(aqbar\(aq: \(aq5.6.7\-8\(aq} +.ft P +.fi +.SS verify +.sp +Many (but not all) package management systems provide a way to verify that the +files installed by the package manager have or have not changed. This function +accepts a list of packages; if none are specified, all packages will be +included. +.sp +.nf +.ft C +installed = __salt__[\(aqlowpkg.verify\(aq](\(aqhttpd\(aq) +.ft P +.fi +.sp +Example output: +.sp +.nf +.ft C +{\(aq/etc/httpd/conf/httpd.conf\(aq: {\(aqmismatch\(aq: [\(aqsize\(aq, \(aqmd5sum\(aq, \(aqmtime\(aq], + \(aqtype\(aq: \(aqconfig\(aq}} +.ft P +.fi +.SS file_list +.sp +Lists all of the files installed by all packages specified. If not packages are +specified, then all files for all known packages are returned. +.sp +.nf +.ft C +installed = __salt__[\(aqlowpkg.file_list\(aq](\(aqhttpd\(aq, \(aqapache\(aq) +.ft P +.fi +.sp +This function does not return which files belong to which packages; all files +are returned as one giant list (hence the \fIfile_list\fP function name. However, +This information is still returned inside of a dict, so that it can provide +any errors to the user in a sane manner. +.sp +.nf +.ft C +{\(aqerrors\(aq: [\(aqpackage apache is not installed\(aq], + \(aqfiles\(aq: [\(aq/etc/httpd\(aq, + \(aq/etc/httpd/conf\(aq, + \(aq/etc/httpd/conf.d\(aq, + \(aq...SNIP...\(aq]} +.ft P +.fi +.SS file_dict +.sp +Lists all of the files installed by all packages specified. If not packages are +specified, then all files for all known packages are returned. +.sp +.nf +.ft C +installed = __salt__[\(aqlowpkg.file_dict\(aq](\(aqhttpd\(aq, \(aqapache\(aq, \(aqkernel\(aq) +.ft P +.fi +.sp +Unlike \fIfile_list\fP, this function will break down which files belong to which +packages. It will also return errors in the same manner as \fIfile_list\fP. +.sp +.nf +.ft C +{\(aqerrors\(aq: [\(aqpackage apache is not installed\(aq], + \(aqpackages\(aq: {\(aqhttpd\(aq: [\(aq/etc/httpd\(aq, + \(aq/etc/httpd/conf\(aq, + \(aq...SNIP...\(aq], + \(aqkernel\(aq: [\(aq/boot/.vmlinuz\-2.6.32\-279.el6.x86_64.hmac\(aq, + \(aq/boot/System.map\-2.6.32\-279.el6.x86_64\(aq, + \(aq...SNIP...\(aq]}} +.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 @@ -5275,14 +6286,15 @@ Salt modules are the functions called by the \fBsalt\fP command. .sp Salt ships with many modules that cover a wide variety of tasks. .RE -.SS Easy Modules to write +.SS Modules Are Easy to Write! .sp 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 within the \fBfile_roots\fP specified by the master config file, and they will be -synced to the minions when \fI\%state.highstate\fP is run, or by executing the -\fI\%saltutil.sync_modules\fP or \fI\%saltutil.sync_all\fP functions. +synced to the minions when \fBstate.highstate\fP is run, or by executing the +\fBsaltutil.sync_modules\fP or +\fBsaltutil.sync_all\fP functions. .sp 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 @@ -5447,7 +6459,7 @@ def spam(eggs): .sp Now when the sys.doc call is executed the docstring will be cleanly returned to the calling terminal. -.SS Add Module meta data +.SS Add Module metadata .sp Add information about the module using the following field lists: .sp @@ -5655,12 +6667,6 @@ Cassandra NoSQL Database Module T} _ T{ -\fBcluster\fP -T} T{ -The cluster module is used to distribute and activate salt HA cluster -T} -_ -T{ \fBcmdmod\fP T} T{ A module for shelling out @@ -5819,7 +6825,7 @@ _ T{ \fBgroupadd\fP T} T{ -Manage groups on Linux +Manage groups on Linux and OpenBSD T} _ T{ @@ -6515,6 +7521,15 @@ salt \(aq*\(aq alternatives.remove name path .INDENT 0.0 .TP .B salt.modules.alternatives.show_current(name) +Display the current alternatives for the given name +.sp +CLI Example: +.sp +.nf +.ft C +salt \(aq*\(aq alternatives.show_current emacs +.ft P +.fi .UNINDENT .SS salt.modules.apache .sp @@ -6638,16 +7653,85 @@ salt \(aq*\(aq pkg.available_version ... .UNINDENT .INDENT 0.0 .TP -.B salt.modules.apt.compare(version1=\(aq\(aq, version2=\(aq\(aq) -Compare two version strings. Return \-1 if version1 < version2, -0 if version1 == version2, and 1 if version1 > version2. Return None if -there was a problem making the comparison. +.B salt.modules.apt.compare(pkg1=\(aq\(aq, oper=\(aq==\(aq, pkg2=\(aq\(aq) +Compare two version strings. .sp CLI Example: .sp .nf .ft C -salt \(aq*\(aq pkg.compare \(aq0.2.4\-0ubuntu1\(aq \(aq0.2.4.1\-0ubuntu1\(aq +salt \(aq*\(aq pkg.compare \(aq0.2.4\-0\(aq \(aq<\(aq \(aq0.2.4.1\-0\(aq +salt \(aq*\(aq pkg.compare pkg1=\(aq0.2.4\-0\(aq oper=\(aq<\(aq pkg2=\(aq0.2.4.1\-0\(aq +.ft P +.fi +.UNINDENT +.INDENT 0.0 +.TP +.B salt.modules.apt.del_repo(repo, refresh=False) +Delete a repo from the sources.list / sources.list.d +.sp +If the .list file is in the sources.list.d directory +and the file that the repo exists in does not contain any other +repo configuration, the file itself will be deleted. +.sp +The repo passed in must be a fully formed repository definition +string. +.sp +CLI Examples: +.sp +.nf +.ft C +salt \(aq*\(aq pkg.del_repo "myrepo definition" +salt \(aq*\(aq pkg.del_repo "myrepo definition" refresh=True +.ft P +.fi +.UNINDENT +.INDENT 0.0 +.TP +.B salt.modules.apt.file_dict(*packages) +List the files that belong to a package, grouped by package. Not +specifying any packages will return a list of _every_ file on the system\(aqs +package database (not generally recommended). +.sp +CLI Examples: +.sp +.nf +.ft C +salt \(aq*\(aq pkg.file_list httpd +salt \(aq*\(aq pkg.file_list httpd postfix +salt \(aq*\(aq pkg.file_list +.ft P +.fi +.UNINDENT +.INDENT 0.0 +.TP +.B salt.modules.apt.file_list(*packages) +List the files that belong to a package. Not specifying any packages will +return a list of _every_ file on the system\(aqs package database (not +generally recommended). +.sp +CLI Examples: +.sp +.nf +.ft C +salt \(aq*\(aq pkg.file_list httpd +salt \(aq*\(aq pkg.file_list httpd postfix +salt \(aq*\(aq pkg.file_list +.ft P +.fi +.UNINDENT +.INDENT 0.0 +.TP +.B salt.modules.apt.get_repo(repo) +Display a repo from the sources.list / sources.list.d +.sp +The repo passwd in needs to be a complete repo entry. +.sp +CLI Examples: +.sp +.nf +.ft C +salt \(aq*\(aq pkg.get_repo "myrepo definition" .ft P .fi .UNINDENT @@ -6685,7 +7769,7 @@ Provide the path to a debconf answers file, processed before installation. .TP .B version -Install a specific version of the package, e.g. 1.0.9~ubuntu. Ignored +Install a specific version of the package, e.g. 1.2.3~0ubuntu0. Ignored if "pkgs" or "sources" is passed. .UNINDENT .sp @@ -6698,7 +7782,8 @@ passed as a python list. .INDENT 7.0 .TP .B CLI Example:: -salt \(aq*\(aq pkg.install pkgs=\(aq["foo","bar"]\(aq +salt \(aq*\(aq pkg.install pkgs=\(aq["foo", "bar"]\(aq +salt \(aq*\(aq pkg.install pkgs=\(aq["foo", {"bar": "1.2.3\-0ubuntu0"}]\(aq .UNINDENT .TP .B sources @@ -6752,7 +7837,21 @@ salt \(aq*\(aq pkg.list_pkgs httpd .UNINDENT .INDENT 0.0 .TP -.B salt.modules.apt.list_upgrades() +.B salt.modules.apt.list_repos() +Lists all repos in the sources.list (and sources.lists.d) files +.sp +CLI Example: +.sp +.nf +.ft C +salt \(aq*\(aq pkg.list_repos +salt \(aq*\(aq pkg.list_repos disabled=True +.ft P +.fi +.UNINDENT +.INDENT 0.0 +.TP +.B salt.modules.apt.list_upgrades(refresh=True) List all available package upgrades. .sp CLI Example: @@ -6765,7 +7864,54 @@ salt \(aq*\(aq pkg.list_upgrades .UNINDENT .INDENT 0.0 .TP -.B salt.modules.apt.purge(pkg) +.B salt.modules.apt.mod_repo(repo, refresh=False, **kwargs) +Modify one or more values for a repo. If the repo does not exist, it will +be created, so long as the definition is well formed. For Ubuntu the +"ppa:/repo" format is acceptable. "ppa:" format can only be +used to create a new repository. +.sp +The following options are available to modify a repo definition: +.sp +.nf +.ft C +comps (a comma separated list of components for the repo, e.g. "main") +file (a file name to be used) +refresh (refresh the apt sources db when the mod is done) +keyserver (keyserver to get gpg key from) +keyid (key id to load with the keyserver argument) +key_url (URl to a gpg key to add to the apt gpg keyring) +consolidate (if true, will attempt to de\-dup and consolidate sources) +.ft P +.fi +.sp +CLI Examples: +.sp +.nf +.ft C +salt \(aq*\(aq pkg.mod_repo \(aqmyrepo definition\(aq uri=http://new/uri +salt \(aq*\(aq pkg.mod_repo \(aqmyrepo definition\(aq comps=main,universe +.ft P +.fi +.UNINDENT +.INDENT 0.0 +.TP +.B salt.modules.apt.perform_cmp(pkg1=\(aq\(aq, pkg2=\(aq\(aq) +Do a cmp\-style comparison on two packages. Return \-1 if pkg1 < pkg2, 0 if +pkg1 == pkg2, and 1 if pkg1 > pkg2. Return None if there was a problem +making the comparison. +.sp +CLI Example: +.sp +.nf +.ft C +salt \(aq*\(aq pkg.perform_cmp \(aq0.2.4\-0ubuntu1\(aq \(aq0.2.4.1\-0ubuntu1\(aq +salt \(aq*\(aq pkg.perform_cmp pkg1=\(aq0.2.4\-0ubuntu1\(aq pkg2=\(aq0.2.4.1\-0ubuntu1\(aq +.ft P +.fi +.UNINDENT +.INDENT 0.0 +.TP +.B salt.modules.apt.purge(pkg, **kwargs) Remove a package via \fBapt\-get purge\fP along with all configuration files and unused dependencies. .sp @@ -6784,13 +7930,15 @@ salt \(aq*\(aq pkg.purge .B salt.modules.apt.refresh_db() Updates the APT database to latest packages based upon repositories .sp -Returns a dict: -.sp -.nf -.ft C -{\(aq\(aq: Bool} -.ft P -.fi +Returns a dict, with the keys being package databases and the values being +the result of the update attempt. Values can be one of the following: +.INDENT 7.0 +.INDENT 3.5 +\fBTrue\fP: Database updated successfully +\fBFalse\fP: Problem updating database +\fBNone\fP: Database already up\-to\-date +.UNINDENT +.UNINDENT .sp CLI Example: .sp @@ -6802,7 +7950,7 @@ salt \(aq*\(aq pkg.refresh_db .UNINDENT .INDENT 0.0 .TP -.B salt.modules.apt.remove(pkg) +.B salt.modules.apt.remove(pkg, **kwargs) Remove a single package via \fBapt\-get remove\fP .sp Returns a list containing the names of the removed packages. @@ -6889,7 +8037,7 @@ salt \(aq*\(aq archive.gunzip /tmp/sourcefile.txt.gz .sp The template arg can be set to \(aqjinja\(aq or another supported template engine to render the command arguments before execution. -For example: +CLI Example: .sp .nf .ft C @@ -6912,7 +8060,7 @@ salt \(aq*\(aq archive.gzip /tmp/sourcefile.txt .sp The template arg can be set to \(aqjinja\(aq or another supported template engine to render the command arguments before execution. -For example: +CLI Example: .sp .nf .ft C @@ -7354,16 +8502,15 @@ salt \(aq*\(aq pkg.available_version .UNINDENT .INDENT 0.0 .TP -.B salt.modules.brew.compare(version1=\(aq\(aq, version2=\(aq\(aq) -Compare two version strings. Return \-1 if version1 < version2, -0 if version1 == version2, and 1 if version1 > version2. Return None if -there was a problem making the comparison. +.B salt.modules.brew.compare(pkg1=\(aq\(aq, oper=\(aq==\(aq, pkg2=\(aq\(aq) +Compare two version strings. .sp CLI Example: .sp .nf .ft C -salt \(aq*\(aq pkg.compare \(aq0.2.4\-0\(aq \(aq0.2.4.1\-0\(aq +salt \(aq*\(aq pkg.compare \(aq0.2.4\-0\(aq \(aq<\(aq \(aq0.2.4.1\-0\(aq +salt \(aq*\(aq pkg.compare pkg1=\(aq0.2.4\-0\(aq oper=\(aq<\(aq pkg2=\(aq0.2.4.1\-0\(aq .ft P .fi .UNINDENT @@ -7446,7 +8593,23 @@ salt \(aq*\(aq pkg.list_upgrades .UNINDENT .INDENT 0.0 .TP -.B salt.modules.brew.remove(pkgs) +.B salt.modules.brew.perform_cmp(pkg1=\(aq\(aq, pkg2=\(aq\(aq) +Do a cmp\-style comparison on two packages. Return \-1 if pkg1 < pkg2, 0 if +pkg1 == pkg2, and 1 if pkg1 > pkg2. Return None if there was a problem +making the comparison. +.sp +CLI Example: +.sp +.nf +.ft C +salt \(aq*\(aq pkg.perform_cmp \(aq0.2.4\-0\(aq \(aq0.2.4.1\-0\(aq +salt \(aq*\(aq pkg.perform_cmp pkg1=\(aq0.2.4\-0\(aq pkg2=\(aq0.2.4.1\-0\(aq +.ft P +.fi +.UNINDENT +.INDENT 0.0 +.TP +.B salt.modules.brew.remove(pkgs, **kwargs) Removes packages with \fBbrew uninstall\fP .sp Return a list containing the removed packages: @@ -7712,16 +8875,6 @@ salt \(aq*\(aq cassandra.version .ft P .fi .UNINDENT -.SS salt.modules.cluster -.sp -The cluster module is used to distribute and activate salt HA cluster -components -.INDENT 0.0 -.TP -.B salt.modules.cluster.distrib(minions, master_conf, master_pem, conf_file) -Set up this minion as a failover master \- only intended for use by the -cluster interface -.UNINDENT .SS salt.modules.cmdmod .sp A module for shelling out @@ -7948,28 +9101,68 @@ Return config information .TP .B salt.modules.config.backup_mode(backup=\(aq\(aq) Return the backup mode +.sp +CLI Example: +.sp +.nf +.ft C +salt \(aq*\(aq config.backup_mode +.ft P +.fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.config.dot_vals(value) Pass in a configuration value that should be preceded by the module name and a dot, this will return a list of all read key/value pairs +.sp +CLI Example: +.sp +.nf +.ft C +salt \(aq*\(aq config.dot_vals host +.ft P +.fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.config.manage_mode(mode) Return a mode value, normalized to a string +.sp +CLI Example: +.sp +.nf +.ft C +salt \(aq*\(aq config.manage_mode +.ft P +.fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.config.option(value, default=\(aq\(aq, omit_opts=False, omit_master=False, omit_pillar=False) Pass in a generic option and receive the value that will be assigned +.sp +CLI Example: +.sp +.nf +.ft C +salt \(aq*\(aq config.option redis.host +.ft P +.fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.config.valid_fileproto(uri) Returns a boolean value based on whether or not the URI passed has a valid remote file protocol designation +.sp +CLI Example: +.sp +.nf +.ft C +salt \(aq*\(aq config.valid_fileproto salt://path/to/file +.ft P +.fi .UNINDENT .SS salt.modules.cp .sp @@ -8177,7 +9370,7 @@ salt \(aq*\(aq cp.list_master .B salt.modules.cp.list_master_dirs(env=\(aqbase\(aq) List all of the directories stored on the master .sp -CLI Exmaple: +CLI Example: .sp .nf .ft C @@ -8217,6 +9410,14 @@ salt \(aq*\(aq cp.list_states Used with salt\-cp, pass the files dict, and the destination. .sp This function receives small fast copy files from the master via salt\-cp +.sp +CLI Example: +.sp +.nf +.ft C +This function does not work via the CLI +.ft P +.fi .UNINDENT .SS salt.modules.cron .sp @@ -8342,6 +9543,14 @@ salt \(aq*\(aq cron.set_special @hourly \(aqecho foobar\(aq .TP .B salt.modules.cron.write_cron_file(user, path) Writes the contents of a file to a user\(aqs crontab +.sp +CLI Example: +.sp +.nf +.ft C +salt \(aq*\(aq cron.write_cron_file root /tmp/new_cron +.ft P +.fi .UNINDENT .SS salt.modules.daemontools .sp @@ -8361,16 +9570,27 @@ provider: daemontools .TP .B salt.modules.daemontools.full_restart(name) Calls daemontools.restart() function +.sp +CLI Example: +.sp +.nf +.ft C +salt \(aq*\(aq daemontools.full_restart +.ft P +.fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.daemontools.get_all() Return a list of all available services -.INDENT 7.0 -.TP -.B CLI Example:: +.sp +CLI Example: +.sp +.nf +.ft C salt \(aq*\(aq daemontools.get_all -.UNINDENT +.ft P +.fi .UNINDENT .INDENT 0.0 .TP @@ -8378,27 +9598,38 @@ salt \(aq*\(aq daemontools.get_all Wrapper for term() .sp CLI Example: +.sp +.nf +.ft C salt \(aq*\(aq daemontools.reload +.ft P +.fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.daemontools.restart(name) Restart service via daemontools. This will stop/start service -.INDENT 7.0 -.TP -.B CLI Example: +.sp +CLI Example: +.sp +.nf +.ft C salt \(aq*\(aq daemontools.restart -.UNINDENT +.ft P +.fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.daemontools.start(name, enable=None, sig=None) Starts service via daemontools -.INDENT 7.0 -.TP -.B CLI Example:: +.sp +CLI Example: +.sp +.nf +.ft C salt \(aq*\(aq daemontools.start -.UNINDENT +.ft P +.fi .UNINDENT .INDENT 0.0 .TP @@ -8417,21 +9648,27 @@ salt \(aq*\(aq daemontools.status .TP .B salt.modules.daemontools.stop(name, enable=None, sig=None) Stops service via daemontools -.INDENT 7.0 -.TP -.B CLI Example:: +.sp +CLI Example: +.sp +.nf +.ft C salt \(aq*\(aq daemontools.stop -.UNINDENT +.ft P +.fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.daemontools.term(name) Send a TERM to service via daemontools -.INDENT 7.0 -.TP -.B CLI Example:: +.sp +CLI Example: +.sp +.nf +.ft C salt \(aq*\(aq daemontools.term -.UNINDENT +.ft P +.fi .UNINDENT .SS salt.modules.data .sp @@ -8808,6 +10045,14 @@ salt \(aq*\(aq django.collectstatic settings.py .TP .B salt.modules.djangomod.command(settings_module, command, bin_env=None, pythonpath=None, *args, **kwargs) Run arbitrary django management command +.sp +CLI Example: +.sp +.nf +.ft C +salt \(aq*\(aq django.command +.ft P +.fi .UNINDENT .INDENT 0.0 .TP @@ -8894,25 +10139,29 @@ salt \(aq*\(aq pkg.available_version ... .UNINDENT .INDENT 0.0 .TP -.B salt.modules.ebuild.compare(version1=\(aq\(aq, version2=\(aq\(aq) -Compare two version strings. Return \-1 if version1 < version2, -0 if version1 == version2, and 1 if version1 > version2. Return None if -there was a problem making the comparison. +.B salt.modules.ebuild.compare(pkg1=\(aq\(aq, oper=\(aq==\(aq, pkg2=\(aq\(aq) +Compare two version strings. .sp CLI Example: .sp .nf .ft C -salt \(aq*\(aq pkg.compare \(aq0.2.4\-0\(aq \(aq0.2.4.1\-0\(aq +salt \(aq*\(aq pkg.compare \(aq0.2.4\-0\(aq \(aq<\(aq \(aq0.2.4.1\-0\(aq +salt \(aq*\(aq pkg.compare pkg1=\(aq0.2.4\-0\(aq oper=\(aq<\(aq pkg2=\(aq0.2.4.1\-0\(aq .ft P .fi .UNINDENT .INDENT 0.0 .TP -.B salt.modules.ebuild.depclean(pkg=None) +.B salt.modules.ebuild.depclean(pkg=None, slot=None) Portage has a function to remove unused dependencies. If a package is provided, it will only removed the package if no other package depends on it. +.INDENT 7.0 +.TP +.B slot +Restrict the remove to a specific slot. Ignored if pkg is None +.UNINDENT .sp Return a list containing the removed packages: .sp @@ -8926,7 +10175,7 @@ salt \(aq*\(aq pkg.depclean .UNINDENT .INDENT 0.0 .TP -.B salt.modules.ebuild.install(name=None, refresh=False, pkgs=None, sources=None, **kwargs) +.B salt.modules.ebuild.install(name=None, refresh=False, pkgs=None, sources=None, slot=None, **kwargs) Install the passed package(s), add refresh=True to sync the portage tree before package is installed. .INDENT 7.0 @@ -8945,6 +10194,20 @@ salt \(aq*\(aq pkg.install .TP .B refresh Whether or not to sync the portage tree before installing. +.TP +.B version +Install a specific version of the package, e.g. 1.0.9\-r1. Ignored +if "pkgs" or "sources" is passed. +.TP +.B slot +Similar to version, but specifies a valid slot to be installed. It +will install the latest available version in the specified slot. +Ignored if "pkgs" or "sources" or "version" is passed. +.INDENT 7.0 +.TP +.B CLI Example:: +salt \(aq*\(aq pkg.install sys\-devel/gcc slot=\(aq4.4\(aq +.UNINDENT .UNINDENT .sp Multiple Package Installation Options: @@ -9000,7 +10263,7 @@ salt \(aq*\(aq pkg.list_pkgs .UNINDENT .INDENT 0.0 .TP -.B salt.modules.ebuild.list_upgrades() +.B salt.modules.ebuild.list_upgrades(refresh=True) List all available package upgrades. .sp CLI Example: @@ -9013,6 +10276,22 @@ salt \(aq*\(aq pkg.list_upgrades .UNINDENT .INDENT 0.0 .TP +.B salt.modules.ebuild.perform_cmp(pkg1=\(aq\(aq, pkg2=\(aq\(aq) +Do a cmp\-style comparison on two packages. Return \-1 if pkg1 < pkg2, 0 if +pkg1 == pkg2, and 1 if pkg1 > pkg2. Return None if there was a problem +making the comparison. +.sp +CLI Example: +.sp +.nf +.ft C +salt \(aq*\(aq pkg.perform_cmp \(aq0.2.4\-0\(aq \(aq0.2.4.1\-0\(aq +salt \(aq*\(aq pkg.perform_cmp pkg1=\(aq0.2.4\-0\(aq pkg2=\(aq0.2.4.1\-0\(aq +.ft P +.fi +.UNINDENT +.INDENT 0.0 +.TP .B salt.modules.ebuild.porttree_matches(name) Returns a list containing the matches for a given package name from the portage tree. Note that the specific version of the package will not be @@ -9021,7 +10300,7 @@ rather the name of the package (i.e. "dev\-python/paramiko"). .UNINDENT .INDENT 0.0 .TP -.B salt.modules.ebuild.purge(pkg) +.B salt.modules.ebuild.purge(pkg, **kwargs) Portage does not have a purge, this function calls remove followed by depclean to emulate a purge process .sp @@ -9050,8 +10329,13 @@ salt \(aq*\(aq pkg.refresh_db .UNINDENT .INDENT 0.0 .TP -.B salt.modules.ebuild.remove(pkg) +.B salt.modules.ebuild.remove(pkg, slot=None, **kwargs) Remove a single package via emerge \-\-unmerge +.INDENT 7.0 +.TP +.B slot +Restrict the remove to a specific slot. +.UNINDENT .sp Return a list containing the names of the removed packages: .sp @@ -9065,8 +10349,14 @@ salt \(aq*\(aq pkg.remove .UNINDENT .INDENT 0.0 .TP -.B salt.modules.ebuild.update(pkg, refresh=False) +.B salt.modules.ebuild.update(pkg, slot=None, refresh=False) Updates the passed package (emerge \-\-update package) +.INDENT 7.0 +.TP +.B slot +Restrict the update to a particular slot. It will update to the +latest version within the slot. +.UNINDENT .sp Return a dict containing the new package names and versions: .sp @@ -9087,7 +10377,7 @@ salt \(aq*\(aq pkg.update .UNINDENT .INDENT 0.0 .TP -.B salt.modules.ebuild.upgrade(refresh=False) +.B salt.modules.ebuild.upgrade(refresh=True) Run a full system upgrade (emerge \-\-update world) .sp Return a dict containing the new package names and versions: @@ -9350,7 +10640,15 @@ New in version 0.9.5. .INDENT 0.0 .TP .B salt.modules.file.check_file_meta(name, sfn, source, source_sum, user, group, mode, env) -Check for the changes in the file metadata +Check for the changes in the file metadata. +.sp +CLI Example: +.sp +.nf +.ft C +salt \(aq*\(aq file.check_file_meta /etc/httpd/conf.d/httpd.conf salt://http/httpd.conf \(aq{hash_type: \(aqmd5\(aq, \(aqhsum\(aq: }\(aq root, root, \(aq755\(aq base +.ft P +.fi .UNINDENT .INDENT 0.0 .TP @@ -9368,11 +10666,27 @@ A file path A string in the form =. For example: \fBmd5=e138491e9d5b97023cea823fe17bac22\fP .UNINDENT +.sp +CLI Example: +.sp +.nf +.ft C +salt \(aq*\(aq file.check_hash /etc/fstab md5= +.ft P +.fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.file.check_managed(name, source, source_hash, user, group, mode, template, makedirs, context, defaults, env, **kwargs) Check to see what changes need to be made for a file +.sp +CLI Example: +.sp +.nf +.ft C +salt \(aq*\(aq file.check_managed /etc/httpd/conf.d/httpd.conf salt://http/httpd.conf \(aq{hash_type: \(aqmd5\(aq, \(aqhsum\(aq: }\(aq root, root, \(aq755\(aq jinja True None None base +.ft P +.fi .UNINDENT .INDENT 0.0 .TP @@ -9389,6 +10703,14 @@ specify mode 0777, for example, it must be specified as the string, \(aq0777\(aq otherwise, 0777 will be parsed as an octal and you\(aqd get 511 instead. .UNINDENT +.sp +CLI Example: +.sp +.nf +.ft C +salt \(aq*\(aq file.check_perms /etc/sudoers \(aq{}\(aq root root 400 +.ft P +.fi .UNINDENT .INDENT 0.0 .TP @@ -9480,7 +10802,7 @@ CLI Example: .sp .nf .ft C -salt \(aq*\(aq /etc/foobar \(aq*cheese*\(aq +salt \(aq*\(aq file.contains_glob /etc/foobar \(aq*cheese*\(aq .ft P .fi .UNINDENT @@ -9494,7 +10816,7 @@ CLI Example: .sp .nf .ft C -salt \(aq*\(aq /etc/crontab \(aq^maint\(aq +salt \(aq*\(aq file.contains_regex /etc/crontab \(aq^maint\(aq .ft P .fi .UNINDENT @@ -9653,12 +10975,13 @@ salt \(aq*\(aq file.find /var/log name=\e*.[0\-9] mtime=+30d size=+10m delete .B salt.modules.file.get_diff(minionfile, masterfile, env=\(aqbase\(aq) Return unified diff of file compared to file on master .sp -Example: -.INDENT 7.0 -.INDENT 3.5 -salt * file.get_diff /home/fred/.vimrc salt://users/fred/.vimrc -.UNINDENT -.UNINDENT +CLI Example: +.sp +.nf +.ft C +salt \e* file.get_diff /home/fred/.vimrc salt://users/fred/.vimrc +.ft P +.fi .UNINDENT .INDENT 0.0 .TP @@ -9705,11 +11028,27 @@ collisions: \fBget_sum(..., \(aqxyz\(aq) == \(aqHash xyz not supported\(aq\fP .UNINDENT .UNINDENT .UNINDENT +.sp +CLI Example: +.sp +.nf +.ft C +salt \(aq*\(aq file.get_hash /etc/shadow +.ft P +.fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.file.get_managed(name, template, source, source_hash, user, group, mode, env, context, defaults, **kwargs) Return the managed file data for file.managed +.sp +CLI Example: +.sp +.nf +.ft C +salt \(aq*\(aq file.get_managed /etc/httpd/conf.d/httpd.conf jinja salt://http/httpd.conf \(aq{hash_type: \(aqmd5\(aq, \(aqhsum\(aq: }\(aq root root \(aq755\(aq base None None +.ft P +.fi .UNINDENT .INDENT 0.0 .TP @@ -9733,7 +11072,7 @@ CLI Example: .sp .nf .ft C -salt \(aq*\(aq selinux.get_context /etc/hosts +salt \(aq*\(aq file.get_selinux_context /etc/hosts .ft P .fi .UNINDENT @@ -9807,18 +11146,42 @@ salt \(aq*\(aq file.group_to_gid root .TP .B salt.modules.file.makedirs(path, user=None, group=None, mode=None) Ensure that the directory containing this path is available. +.sp +CLI Example: +.sp +.nf +.ft C +salt \(aq*\(aq file.makedirs /opt/code +.ft P +.fi .UNINDENT .INDENT 0.0 .TP -.B salt.modules.file.makedirs_perms(name, user=None, group=None, mode=493) +.B salt.modules.file.makedirs_perms(name, user=None, group=None, mode=\(aq0755\(aq) Taken and modified from os.makedirs to set user, group and mode for each directory created. +.sp +CLI Example: +.sp +.nf +.ft C +salt \(aq*\(aq file.makedirs_perms /opt/code +.ft P +.fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.file.manage_file(name, sfn, ret, source, source_sum, user, group, mode, env, backup) Checks the destination against what was retrieved with get_managed and makes the appropriate modifications (if necessary). +.sp +CLI Example: +.sp +.nf +.ft C +salt \(aq*\(aq file.manage_file /etc/httpd/conf.d/httpd.conf \(aq{}\(aq salt://http/httpd.conf \(aq{hash_type: \(aqmd5\(aq, \(aqhsum\(aq: }\(aq root root \(aq755\(aq base \(aq\(aq +.ft P +.fi .UNINDENT .INDENT 0.0 .TP @@ -9857,6 +11220,15 @@ New in version 0.10.4. .INDENT 0.0 .TP .B salt.modules.file.remove(path) +Remove the named file +.sp +CLI Example: +.sp +.nf +.ft C +salt \(aq*\(aq file.remove /tmp/foo +.ft P +.fi .UNINDENT .INDENT 0.0 .TP @@ -9867,7 +11239,7 @@ CLI Example: .sp .nf .ft C -salt \(aq*\(aq selinux.restorecon /home/user/.ssh/authorized_keys +salt \(aq*\(aq file.restorecon /home/user/.ssh/authorized_keys .ft P .fi .UNINDENT @@ -9949,7 +11321,7 @@ CLI Example: .sp .nf .ft C -salt \(aq*\(aq selinux.chcon path +salt \(aq*\(aq file.set_selinux_context path .ft P .fi .UNINDENT @@ -9957,6 +11329,11 @@ salt \(aq*\(aq selinux.chcon path .TP .B salt.modules.file.source_list(source, source_hash, env) Check the source list and return the source to use +.INDENT 7.0 +.TP +.B CLI Example:: +salt \(aq*\(aq file.source_list salt://http/httpd.conf \(aq{hash_type: \(aqmd5\(aq, \(aqhsum\(aq: }\(aq base +.UNINDENT .UNINDENT .INDENT 0.0 .TP @@ -10229,29 +11606,68 @@ salt \(aq*\(aq kmod.remove kvm Package support for FreeBSD .INDENT 0.0 .TP -.B salt.modules.freebsdpkg.available_version(name) -The available version of the package in the repository +.B salt.modules.freebsdpkg.available_version(*names) +Return the latest version of the named package available for upgrade or +installation. If more than one package name is specified, a dict of +name/version pairs is returned. +.sp +If the latest version of a given package is already installed, an empty +string will be returned for that package. .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq pkg.available_version +salt \(aq*\(aq pkg.available_version ... .ft P .fi .UNINDENT .INDENT 0.0 .TP -.B salt.modules.freebsdpkg.compare(version1=\(aq\(aq, version2=\(aq\(aq) -Compare two version strings. Return \-1 if version1 < version2, -0 if version1 == version2, and 1 if version1 > version2. Return None if -there was a problem making the comparison. +.B salt.modules.freebsdpkg.compare(pkg1=\(aq\(aq, oper=\(aq==\(aq, pkg2=\(aq\(aq) +Compare two version strings. .sp CLI Example: .sp .nf .ft C -salt \(aq*\(aq pkg.compare \(aq0.2.4\-0\(aq \(aq0.2.4.1\-0\(aq +salt \(aq*\(aq pkg.compare \(aq0.2.4\-0\(aq \(aq<\(aq \(aq0.2.4.1\-0\(aq +salt \(aq*\(aq pkg.compare pkg1=\(aq0.2.4\-0\(aq oper=\(aq<\(aq pkg2=\(aq0.2.4.1\-0\(aq +.ft P +.fi +.UNINDENT +.INDENT 0.0 +.TP +.B salt.modules.freebsdpkg.file_dict(*packages) +List the files that belong to a package, grouped by package. Not +specifying any packages will return a list of _every_ file on the +system\(aqs package database (not generally recommended). +.sp +CLI Examples: +.sp +.nf +.ft C +salt \(aq*\(aq pkg.file_list httpd +salt \(aq*\(aq pkg.file_list httpd postfix +salt \(aq*\(aq pkg.file_list +.ft P +.fi +.UNINDENT +.INDENT 0.0 +.TP +.B salt.modules.freebsdpkg.file_list(*packages) +List the files that belong to a package. Not specifying any packages will +return a list of _every_ file on the system\(aqs package database (not +generally recommended). +.sp +CLI Examples: +.sp +.nf +.ft C +salt \(aq*\(aq pkg.file_list httpd +salt \(aq*\(aq pkg.file_list httpd postfix +salt \(aq*\(aq pkg.file_list .ft P .fi .UNINDENT @@ -10338,7 +11754,23 @@ salt \(aq*\(aq pkg.list_pkgs .UNINDENT .INDENT 0.0 .TP -.B salt.modules.freebsdpkg.purge(name) +.B salt.modules.freebsdpkg.perform_cmp(pkg1=\(aq\(aq, pkg2=\(aq\(aq) +Do a cmp\-style comparison on two packages. Return \-1 if pkg1 < pkg2, 0 if +pkg1 == pkg2, and 1 if pkg1 > pkg2. Return None if there was a problem +making the comparison. +.sp +CLI Example: +.sp +.nf +.ft C +salt \(aq*\(aq pkg.perform_cmp \(aq0.2.4\-0\(aq \(aq0.2.4.1\-0\(aq +salt \(aq*\(aq pkg.perform_cmp pkg1=\(aq0.2.4\-0\(aq pkg2=\(aq0.2.4.1\-0\(aq +.ft P +.fi +.UNINDENT +.INDENT 0.0 +.TP +.B salt.modules.freebsdpkg.purge(name, **kwargs) Remove a single package with pkg_delete .sp Returns a list containing the removed packages. @@ -10383,7 +11815,7 @@ salt \(aq*\(aq pkg.rehash .UNINDENT .INDENT 0.0 .TP -.B salt.modules.freebsdpkg.remove(name=None, pkgs=None) +.B salt.modules.freebsdpkg.remove(name=None, pkgs=None, **kwargs) Remove a single package. .INDENT 7.0 .TP @@ -10451,14 +11883,17 @@ salt \(aq*\(aq pkg.upgrade .UNINDENT .INDENT 0.0 .TP -.B salt.modules.freebsdpkg.version(name) -Returns a version if the package is installed, else returns an empty string +.B salt.modules.freebsdpkg.version(*names) +Returns a string representing the package version or an empty string if not +installed. If more than one package name is specified, a dict of +name/version pairs is returned. .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq pkg.version +salt \(aq*\(aq pkg.version ... .ft P .fi .UNINDENT @@ -10720,6 +12155,14 @@ Generate RDoc documentation for the gem(s). False Generate RI documentation for the gem(s). .UNINDENT +.sp +CLI Example: +.sp +.nf +.ft C +salt \(aq*\(aq gem.install vagrant +.ft P +.fi .UNINDENT .INDENT 0.0 .TP @@ -10738,6 +12181,14 @@ If RVM is installed, the ruby version and gemset to use. None The user to run gem as. .UNINDENT +.sp +CLI Example: +.sp +.nf +.ft C +gem.list +.ft P +.fi .UNINDENT .INDENT 0.0 .TP @@ -10756,6 +12207,14 @@ If RVM is installed, the ruby version and gemset to use. None The user to run gem as. .UNINDENT +.sp +CLI Example: +.sp +.nf +.ft C +salt \(aq*\(aq gem.sources_add http://rubygems.org/ +.ft P +.fi .UNINDENT .INDENT 0.0 .TP @@ -10771,6 +12230,14 @@ If RVM is installed, the ruby version and gemset to use. None The user to run gem as. .UNINDENT +.sp +CLI Example: +.sp +.nf +.ft C +salt \(aq*\(aq gem.sources_list +.ft P +.fi .UNINDENT .INDENT 0.0 .TP @@ -10789,6 +12256,14 @@ If RVM is installed, the ruby version and gemset to use. None The user to run gem as. .UNINDENT +.sp +CLI Example: +.sp +.nf +.ft C +salt \(aq*\(aq gem.sources_remove http://rubygems.org/ +.ft P +.fi .UNINDENT .INDENT 0.0 .TP @@ -10807,6 +12282,14 @@ If RVM is installed, the ruby version and gemset to use. None The user to run gem as. .UNINDENT +.sp +CLI Example: +.sp +.nf +.ft C +salt \(aq*\(aq gem.uninstall vagrant +.ft P +.fi .UNINDENT .INDENT 0.0 .TP @@ -10825,6 +12308,14 @@ If RVM is installed, the ruby version and gemset to use. None The user to run gem as. .UNINDENT +.sp +CLI Example: +.sp +.nf +.ft C +salt \(aq*\(aq gem.update vagrant +.ft P +.fi .UNINDENT .INDENT 0.0 .TP @@ -10844,6 +12335,14 @@ If RVM is installed, the ruby version and gemset to use. None The user to run gem as. .UNINDENT +.sp +CLI Example: +.sp +.nf +.ft C +salt \(aq*\(aq gem.update_system +.ft P +.fi .UNINDENT .SS salt.modules.gentoolkitmod .sp @@ -11465,6 +12964,14 @@ Any additional options to add to the command line None Run git as a user other than what the minion runs as .UNINDENT +.sp +CLI Example: +.sp +.nf +.ft C +salt \(aq*\(aq git.submodule /path/to/repo.git/sub/repo +.ft P +.fi .UNINDENT .SS salt.modules.glance .sp @@ -11559,8 +13066,8 @@ salt \(aq*\(aq glance.image_get Control aspects of the grains data .INDENT 0.0 .TP -.B salt.modules.grains.item(key=None, sanitize=False) -Return a singe component of the grains data +.B salt.modules.grains.item(*args, **kargs) +Return a single component of the grains data .sp CLI Example: .sp @@ -11570,11 +13077,21 @@ salt \(aq*\(aq grains.item os .ft P .fi .sp -Sanitized CLI output: +Return multiple components of the grains data +.sp +CLI Example: .sp .nf .ft C -salt \(aq*\(aq grains.items serialnumber sanitize=True +salt \(aq*\(aq grains.item os osrelease oscodename +.ft P +.fi +.sp +Sanitized CLI Example: +.sp +.nf +.ft C +salt \(aq*\(aq grains.item host sanitize=True .ft P .fi .UNINDENT @@ -11627,7 +13144,7 @@ salt \(aq*\(aq grains.setval key val .UNINDENT .SS salt.modules.groupadd .sp -Manage groups on Linux +Manage groups on Linux and OpenBSD .INDENT 0.0 .TP .B salt.modules.groupadd.add(name, gid=None, system=False) @@ -12008,7 +13525,7 @@ salt \(aq*\(aq hosts.set_host Support for iptables .INDENT 0.0 .TP -.B salt.modules.iptables.append(table=\(aqfilter\(aq, rule=None) +.B salt.modules.iptables.append(table=\(aqfilter\(aq, chain=None, rule=None) Append a rule to the specified table/chain. .INDENT 7.0 .TP @@ -12022,13 +13539,13 @@ CLI Example: .sp .nf .ft C -salt \(aq*\(aq iptables.append filter \(aqINPUT \-m state \-\-state RELATED,ESTABLISHED \-j ACCEPT\(aq +salt \(aq*\(aq iptables.append filter INPUT \(aq\-m state \-\-state RELATED,ESTABLISHED \-j ACCEPT\(aq .ft P .fi .UNINDENT .INDENT 0.0 .TP -.B salt.modules.iptables.delete(table, position=None, rule=None) +.B salt.modules.iptables.delete(table, chain, position=None, rule=None) .INDENT 7.0 .TP .B Delete a rule from the specified table/chain, specifying either the rule @@ -12044,8 +13561,8 @@ CLI Examples: .sp .nf .ft C -salt \(aq*\(aq iptables.delete filter 3 -salt \(aq*\(aq iptables.delete filter rule=\(aqINPUT 3 \-m state \-\-state RELATED,ESTABLISHED \-j ACCEPT\(aq +salt \(aq*\(aq iptables.delete filter INPUT position=3 +salt \(aq*\(aq iptables.delete filter INPUT rule=\(aq\-m state \-\-state RELATED,ESTABLISHED \-j ACCEPT\(aq .ft P .fi .UNINDENT @@ -12117,7 +13634,7 @@ salt \(aq*\(aq iptables.get_saved_rules .UNINDENT .INDENT 0.0 .TP -.B salt.modules.iptables.insert(table=\(aqfilter\(aq, rule=None) +.B salt.modules.iptables.insert(table=\(aqfilter\(aq, chain=None, position=None, rule=None) Insert a rule into the specified table/chain, at the specified position. .INDENT 7.0 .TP @@ -12131,14 +13648,14 @@ CLI Examples: .sp .nf .ft C -salt \(aq*\(aq iptables.insert filter \(aqINPUT \-m state \-\-state RELATED,ESTABLISHED \-j ACCEPT\(aq -salt \(aq*\(aq iptables.insert filter \(aqINPUT 3 \-m state \-\-state RELATED,ESTABLISHED \-j ACCEPT\(aq +salt \(aq*\(aq iptables.insert filter INPUT rule=\(aq\-m state \-\-state RELATED,ESTABLISHED \-j ACCEPT\(aq +salt \(aq*\(aq iptables.insert filter INPUT position=3 rule=\(aq\-m state \-\-state RELATED,ESTABLISHED \-j ACCEPT\(aq .ft P .fi .UNINDENT .INDENT 0.0 .TP -.B salt.modules.iptables.save(filename) +.B salt.modules.iptables.save(filename=None) Save the current in\-memory rules to disk .sp CLI Example: @@ -12253,6 +13770,11 @@ keystone.tenant: admin keystone.tenant_id: f80919baedab48ec8931f200c65a50df keystone.insecure: False #(optional) keystone.auth_url: \(aqhttp://127.0.0.1:5000/v2.0/\(aq + +OR (for token based authentication) + +keystone.token: \(aqADMIN\(aq +keystone.endpoint: \(aqhttp://127.0.0.1:35357/v2.0\(aq .ft P .fi .UNINDENT @@ -12548,8 +14070,16 @@ salt \(aq*\(aq kmod.check_available kvm .UNINDENT .INDENT 0.0 .TP -.B salt.modules.kmod.load(mod) +.B salt.modules.kmod.load(mod, persist=False) Load the specified kernel module +.INDENT 7.0 +.TP +.B mod +Name of module to add +.TP +.B persist +Write module to /etc/modules to make it load on system reboot +.UNINDENT .sp CLI Example: .sp @@ -12574,7 +14104,7 @@ salt \(aq*\(aq kmod.lsmod .UNINDENT .INDENT 0.0 .TP -.B salt.modules.kmod.mod_list() +.B salt.modules.kmod.mod_list(only_persist=False) Return a list of the loaded module names .sp CLI Example: @@ -12587,8 +14117,20 @@ salt \(aq*\(aq kmod.mod_list .UNINDENT .INDENT 0.0 .TP -.B salt.modules.kmod.remove(mod) +.B salt.modules.kmod.remove(mod, persist=False, comment=True) Remove the specified kernel module +.INDENT 7.0 +.TP +.B mod +Name of module to remove +.TP +.B persist +Also remove module from /etc/modules +.TP +.B comment +If persist is set don\(aqt remove line from /etc/modules but only +comment it +.UNINDENT .sp CLI Example: .sp @@ -14160,7 +15702,7 @@ Remove a Mongodb user .UNINDENT .SS salt.modules.monit .sp -Monit service module. This module will create a monit type +Monit service module. This module will create a monit type service watcher. .INDENT 0.0 .TP @@ -14396,11 +15938,6 @@ mysql.default_file: \(aq/etc/mysql/debian.cnf\(aq .UNINDENT .INDENT 0.0 .TP -.B salt.modules.mysql.connect(**kwargs) -wrap authentication credentials here -.UNINDENT -.INDENT 0.0 -.TP .B salt.modules.mysql.db_check(name, table=None) Repairs the full database or just a given table .sp @@ -14508,6 +16045,14 @@ salt \(aq*\(aq mysql.db_tables \(aqdatabase\(aq .TP .B salt.modules.mysql.free_slave() Frees a slave from its master. This is a WIP, do not use. +.sp +CLI Example: +.sp +.nf +.ft C +salt \e* mysql.free_slave +.ft P +.fi .UNINDENT .INDENT 0.0 .TP @@ -14523,10 +16068,15 @@ Retrieves the master status from the mimion. \(aqFile\(aq: \(aqmysql\-bin.000021\(aq, \(aqPosition\(aq: 107}} .UNINDENT -.TP -.B CLI Example: -salt \(aq*\(aq mysql.get_master_status .UNINDENT +.sp +CLI Example: +.sp +.nf +.ft C +salt \(aq*\(aq mysql.get_master_status +.ft P +.fi .UNINDENT .INDENT 0.0 .TP @@ -14606,6 +16156,15 @@ salt \(aq*\(aq mysql.grant_add \(aqSELECT,INSERT,UPDATE,...\(aq \(aqdatabase.*\( .INDENT 0.0 .TP .B salt.modules.mysql.grant_exists(grant, database, user, host=\(aqlocalhost\(aq, grant_option=False, escape=True) +Checks to see if a grant exists in the database +.sp +CLI Example: +.sp +.nf +.ft C +salt \e* mysql.grant_exists \(aqSELECT,INSERT,UPDATE,...\(aq \(aqdatabase.*\(aq \(aqfrank\(aq \(aqlocalhost\(aq +.ft P +.fi .UNINDENT .INDENT 0.0 .TP @@ -14642,10 +16201,15 @@ Retrieves the processlist from the MySQL server via \(aqUser\(aq: \(aqroot\(aq, \(aqdb\(aq: \(aqmysql\(aq} .UNINDENT -.TP -.B CLI Example: -salt \(aq*\(aq mysql.processlist .UNINDENT +.sp +CLI Example: +.sp +.nf +.ft C +salt \(aq*\(aq mysql.processlist +.ft P +.fi .UNINDENT .INDENT 0.0 .TP @@ -14845,8 +16409,29 @@ salt \(aq*\(aq network.dig archlinux.org .UNINDENT .INDENT 0.0 .TP +.B salt.modules.network.hwaddr(iface) +Return the hardware address (a.k.a. MAC address) for a given interface +.sp +CLI Example: +.sp +.nf +.ft C +salt \(aq*\(aq network.hwaddr eth0 +.ft P +.fi +.UNINDENT +.INDENT 0.0 +.TP .B salt.modules.network.in_subnet(cidr) Returns True if host is within specified subnet, otherwise False +.sp +CLI Example: +.sp +.nf +.ft C +salt \(aq*\(aq network.in_subnet 10.0.0.0/16 +.ft P +.fi .UNINDENT .INDENT 0.0 .TP @@ -14867,6 +16452,14 @@ salt \(aq*\(aq network.interfaces Returns a list of IPv4 addresses assigned to the host. 127.0.0.1 is ignored, unless \(aqinclude_loopback=True\(aq is indicated. If \(aqinterface\(aq is provided, then only IP addresses from that interface will be returned. +.sp +CLI Example: +.sp +.nf +.ft C +salt \(aq*\(aq network.ip_addrs +.ft P +.fi .UNINDENT .INDENT 0.0 .TP @@ -14874,6 +16467,14 @@ provided, then only IP addresses from that interface will be returned. Returns a list of IPv6 addresses assigned to the host. ::1 is ignored, unless \(aqinclude_loopback=True\(aq is indicated. If \(aqinterface\(aq is provided, then only IP addresses from that interface will be returned. +.sp +CLI Example: +.sp +.nf +.ft C +salt \(aq*\(aq network.ip_addrs6 +.ft P +.fi .UNINDENT .INDENT 0.0 .TP @@ -14905,6 +16506,14 @@ salt \(aq*\(aq network.ping archlinux.org .TP .B salt.modules.network.subnets() Returns a list of subnets to which the host belongs +.sp +CLI Example: +.sp +.nf +.ft C +salt \(aq*\(aq network.subnets +.ft P +.fi .UNINDENT .INDENT 0.0 .TP @@ -15369,7 +16978,7 @@ salt \(aq*\(aq pkg.list_pkgs .UNINDENT .INDENT 0.0 .TP -.B salt.modules.openbsdpkg.purge(name) +.B salt.modules.openbsdpkg.purge(name, **kwargs) Remove a single package with pkg_delete .sp Returns a list containing the removed packages. @@ -15384,7 +16993,7 @@ salt \(aq*\(aq pkg.purge .UNINDENT .INDENT 0.0 .TP -.B salt.modules.openbsdpkg.remove(name) +.B salt.modules.openbsdpkg.remove(name, **kwargs) Remove a single package with pkg_delete .sp Returns a list containing the removed packages. @@ -15497,6 +17106,19 @@ salt \(aq*\(aq desktop.lock .UNINDENT .INDENT 0.0 .TP +.B salt.modules.osxdesktop.say(*words) +Say some words. +.sp +CLI Example: +.sp +.nf +.ft C +salt \(aq*\(aq desktop.say ... +.ft P +.fi +.UNINDENT +.INDENT 0.0 +.TP .B salt.modules.osxdesktop.screensaver() Launch the screensaver .sp @@ -15546,22 +17168,55 @@ salt \(aq*\(aq pkg.available_version ... .UNINDENT .INDENT 0.0 .TP -.B salt.modules.pacman.compare(version1=\(aq\(aq, version2=\(aq\(aq) -Compare two version strings. Return \-1 if version1 < version2, -0 if version1 == version2, and 1 if version1 > version2. Return None if -there was a problem making the comparison. +.B salt.modules.pacman.compare(pkg1=\(aq\(aq, oper=\(aq==\(aq, pkg2=\(aq\(aq) +Compare two version strings. .sp CLI Example: .sp .nf .ft C -salt \(aq*\(aq pkg.compare \(aq0.2.4\-0\(aq \(aq0.2.4.1\-0\(aq +salt \(aq*\(aq pkg.compare \(aq0.2.4\-0\(aq \(aq<\(aq \(aq0.2.4.1\-0\(aq +salt \(aq*\(aq pkg.compare pkg1=\(aq0.2.4\-0\(aq oper=\(aq<\(aq pkg2=\(aq0.2.4.1\-0\(aq +.ft P +.fi +.UNINDENT +.INDENT 0.0 +.TP +.B salt.modules.pacman.file_dict(*packages) +List the files that belong to a package, grouped by package. Not +specifying any packages will return a list of _every_ file on the system\(aqs +package database (not generally recommended). +.sp +CLI Examples: +.sp +.nf +.ft C +salt \(aq*\(aq pkg.file_list httpd +salt \(aq*\(aq pkg.file_list httpd postfix +salt \(aq*\(aq pkg.file_list .ft P .fi .UNINDENT .INDENT 0.0 .TP -.B salt.modules.pacman.install(name=None, refresh=False, pkgs=None, sources=None, **kwargs) +.B salt.modules.pacman.file_list(*packages) +List the files that belong to a package. Not specifying any packages will +return a list of _every_ file on the system\(aqs package database (not +generally recommended). +.sp +CLI Examples: +.sp +.nf +.ft C +salt \(aq*\(aq pkg.file_list httpd +salt \(aq*\(aq pkg.file_list httpd postfix +salt \(aq*\(aq pkg.file_list +.ft P +.fi +.UNINDENT +.INDENT 0.0 +.TP +.B salt.modules.pacman.install(name=None, refresh=True, pkgs=None, sources=None, **kwargs) Install the passed package, add refresh=True to install with an \-Sy. .INDENT 7.0 .TP @@ -15586,11 +17241,16 @@ Multiple Package Installation Options: .TP .B pkgs A list of packages to install from a software repository. Must be -passed as a python list. +passed as a python list. A specific version number can be specified +by using a single\-element dict representing the package and its +version. As with the \fBversion\fP parameter above, comparison operators +can be used to target a specific version of a package. .INDENT 7.0 .TP -.B CLI Example:: -salt \(aq*\(aq pkg.install pkgs=\(aq["foo","bar"]\(aq +.B CLI Examples:: +salt \(aq*\(aq pkg.install pkgs=\(aq["foo", "bar"]\(aq +salt \(aq*\(aq pkg.install pkgs=\(aq["foo", {"bar": "1.2.3\-4"}]\(aq +salt \(aq*\(aq pkg.install pkgs=\(aq["foo", {"bar": "<1.2.3\-4"}]\(aq .UNINDENT .TP .B sources @@ -15647,7 +17307,23 @@ salt \(aq*\(aq pkg.list_upgrades .UNINDENT .INDENT 0.0 .TP -.B salt.modules.pacman.purge(name) +.B salt.modules.pacman.perform_cmp(pkg1=\(aq\(aq, pkg2=\(aq\(aq) +Do a cmp\-style comparison on two packages. Return \-1 if pkg1 < pkg2, 0 if +pkg1 == pkg2, and 1 if pkg1 > pkg2. Return None if there was a problem +making the comparison. +.sp +CLI Example: +.sp +.nf +.ft C +salt \(aq*\(aq pkg.perform_cmp \(aq0.2.4\-0\(aq \(aq0.2.4.1\-0\(aq +salt \(aq*\(aq pkg.perform_cmp pkg1=\(aq0.2.4\-0\(aq pkg2=\(aq0.2.4.1\-0\(aq +.ft P +.fi +.UNINDENT +.INDENT 0.0 +.TP +.B salt.modules.pacman.purge(name, **kwargs) Recursively remove a package and all dependencies which were installed with it, this will call a \fBpacman \-Rsc\fP .sp @@ -15682,7 +17358,7 @@ salt \(aq*\(aq pkg.refresh_db .UNINDENT .INDENT 0.0 .TP -.B salt.modules.pacman.remove(name) +.B salt.modules.pacman.remove(name, **kwargs) Remove a single package with \fBpacman \-R\fP .sp Return a list containing the removed packages. @@ -15753,6 +17429,14 @@ Support for pam .TP .B salt.modules.pam.read_file(file_name) This is just a test function, to make sure parsing works +.sp +CLI Example: +.sp +.nf +.ft C +salt \(aq*\(aq pam.read_file /etc/pam.d/login +.ft P +.fi .UNINDENT .SS salt.modules.parted .sp @@ -16096,11 +17780,27 @@ Installs one or several pecl extensions. .B pecls The pecl extensions to install. .UNINDENT +.sp +CLI Example: +.sp +.nf +.ft C +salt \(aq*\(aq pecl.install fuse +.ft P +.fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.pecl.list() List installed pecl extensions. +.sp +CLI Example: +.sp +.nf +.ft C +salt \(aq*\(aq pecl.list +.ft P +.fi .UNINDENT .INDENT 0.0 .TP @@ -16111,6 +17811,14 @@ Uninstall one or several pecl extensions. .B pecls The pecl extensions to uninstall. .UNINDENT +.sp +CLI Example: +.sp +.nf +.ft C +salt \(aq*\(aq pecl.uninstall fuse +.ft P +.fi .UNINDENT .INDENT 0.0 .TP @@ -16121,6 +17829,14 @@ Update one or several pecl exntesions. .B pecls The pecl extensions to update. .UNINDENT +.sp +CLI Example: +.sp +.nf +.ft C +salt \(aq*\(aq pecl.update fuse +.ft P +.fi .UNINDENT .SS salt.modules.pillar .sp @@ -16392,129 +18108,566 @@ Support for pkgng .TP .B salt.modules.pkgng.add(pkg_path) Install a package from either a local source or remote one -.INDENT 7.0 -.TP -.B CLI Example:: +.sp +CLI Example: +.sp +.nf +.ft C salt \(aq*\(aq pkgng.add /tmp/package.txz -.UNINDENT +.ft P +.fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.pkgng.audit() Audits installed packages against known vulnerabilities -.INDENT 7.0 -.TP -.B CLI Example:: +.sp +CLI Example: +.sp +.nf +.ft C salt \(aq*\(aq pkgng.audit +.ft P +.fi .UNINDENT +.INDENT 0.0 +.TP +.B salt.modules.pkgng.autoremove(dryrun=False) +Delete packages which were automatically installed as dependencies and are +not required anymore +.sp +CLI Example: +.sp +.nf +.ft C + salt \(aq*\(aq pkgng.autoremove + +dryrun + Dry\-run mode. The list of changes to packages is always printed, + but no changes are actually made. + + CLI Example:: + + salt \(aq*\(aq pkgng.autoremove dryrun=True +.ft P +.fi .UNINDENT .INDENT 0.0 .TP -.B salt.modules.pkgng.available_version(name) +.B salt.modules.pkgng.available_version(pkg_name) The available version of the package in the repository -.INDENT 7.0 -.TP -.B CLI Example:: +.sp +CLI Example: +.sp +.nf +.ft C salt \(aq*\(aq pkgng.available_version -.UNINDENT +.ft P +.fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.pkgng.backup(file_name) Export installed packages into yaml+mtree file +.sp +CLI Example: +.sp +.nf +.ft C +salt \(aq*\(aq pkgng.backup /tmp/pkg +.ft P +.fi +.UNINDENT +.INDENT 0.0 +.TP +.B salt.modules.pkgng.check(depends=False, recompute=False, checksum=False) +Sanity checks installed packages .INDENT 7.0 .TP -.B CLI Example:: -salt \(aq*\(aq pkgng.backup /tmp/pkg +.B depends +Check for and install missing dependencies. +.sp +CLI Example: +.sp +.nf +.ft C +salt \(aq*\(aq pkgng.check recompute=True +.ft P +.fi +.TP +.B recompute +Recompute sizes and checksums of installed packages. +.sp +CLI Example: +.sp +.nf +.ft C +salt \(aq*\(aq pkgng.check depends=True +.ft P +.fi +.TP +.B checksum +Find invalid checksums for installed packages. +.sp +CLI Example: +.sp +.nf +.ft C +salt \(aq*\(aq pkgng.check checksum=True +.ft P +.fi .UNINDENT .UNINDENT .INDENT 0.0 .TP -.B salt.modules.pkgng.compare(version1=\(aq\(aq, version2=\(aq\(aq) -Compare two version strings. Return \-1 if version1 < version2, -0 if version1 == version2, and 1 if version1 > version2. Return None if -there was a problem making the comparison. +.B salt.modules.pkgng.clean() +Cleans the local cache of fetched remote packages +.sp +CLI Example: +.sp +.nf +.ft C +salt \(aq*\(aq pkgng.clean +.ft P +.fi +.UNINDENT +.INDENT 0.0 +.TP +.B salt.modules.pkgng.compare(pkg1=\(aq\(aq, oper=\(aq==\(aq, pkg2=\(aq\(aq) +Compare two version strings. +.sp +CLI Example: +.sp +.nf +.ft C +salt \(aq*\(aq pkg.compare \(aq0.2.4\-0\(aq \(aq<\(aq \(aq0.2.4.1\-0\(aq +salt \(aq*\(aq pkg.compare pkg1=\(aq0.2.4\-0\(aq oper=\(aq<\(aq pkg2=\(aq0.2.4.1\-0\(aq +.ft P +.fi +.UNINDENT +.INDENT 0.0 +.TP +.B salt.modules.pkgng.delete(pkg_name, all_installed=False, force=False, glob=False, dryrun=False, recurse=False, regex=False, pcre=False) +Delete a package from the database and system +.sp +CLI Example: +.sp +.nf +.ft C +salt \(aq*\(aq pkgng.delete + +all_installed + Deletes all installed packages from the system and empties the + database. USE WITH CAUTION! + + CLI Example:: + + salt \(aq*\(aq pkgng.delete all all_installed=True force=True + +force + Forces packages to be removed despite leaving unresolved + dependencies. + + CLI Example:: + + salt \(aq*\(aq pkgng.delete force=True + +glob + Treat the package names as shell glob patterns. + + CLI Example:: + + salt \(aq*\(aq pkgng.delete glob=True + +dryrun + Dry run mode. The list of packages to delete is always printed, but + no packages are actually deleted. + + CLI Example:: + + salt \(aq*\(aq pkgng.delete dryrun=True + +recurse + Delete all packages that require the listed package as well. + + CLI Example:: + + salt \(aq*\(aq pkgng.delete recurse=True + +regex + Treat the package names as regular expressions. + + CLI Example:: + + salt \(aq*\(aq pkgng.delete regex=True + +pcre + Treat the package names as extended regular expressions. + + CLI Example:: + + salt \(aq*\(aq pkgng.delete pcre=True +.ft P +.fi +.UNINDENT +.INDENT 0.0 +.TP +.B salt.modules.pkgng.fetch(pkg_name, all=False, quiet=False, reponame=None, glob=True, regex=False, pcre=False, local=False, depends=False) +Fetches remote packages +.sp +CLI Example: +.sp +.nf +.ft C +salt \(aq*\(aq pkgng.fetch + +all + Fetch all packages. + + CLI Example:: + + salt \(aq*\(aq pkgng.fetch all=True + +quiet + Quiet mode. Show less output. + + CLI Example:: + + salt \(aq*\(aq pkgng.fetch quiet=True + +reponame + Fetches packages from the given reponame if multiple repo support + is enabled. See pkg.conf(5). + + CLI Example:: + + salt \(aq*\(aq pkgng.fetch reponame=repo + +glob + Treat pkg_name as a shell glob pattern. + + CLI Example:: + + salt \(aq*\(aq pkgng.fetch glob=True + +regex + Treat pkg_name as a regular expression. + + CLI Example:: + + salt \(aq*\(aq pkgng.fetch regex=True + +pcre + Treat pkg_name is an extended regular expression. + + CLI Example:: + + salt \(aq*\(aq pkgng.fetch pcre=True + +local + Skip updating the repository catalogues with pkg\-update(8). Use the + local cache only. + + CLI Example:: + + salt \(aq*\(aq pkgng.fetch local=True + +depends + Fetch the package and its dependencies as well. + + CLI Example:: + + salt \(aq*\(aq pkgng.fetch depends=True +.ft P +.fi +.UNINDENT +.INDENT 0.0 +.TP +.B salt.modules.pkgng.info(pkg_name=None) +Returns info on packages installed on system +.sp +CLI Example: +.sp +.nf +.ft C +salt \(aq*\(aq pkgng.info +salt \(aq*\(aq pkgng.info sudo +.ft P +.fi +.UNINDENT +.INDENT 0.0 +.TP +.B salt.modules.pkgng.install(pkg_name, orphan=False, force=False, glob=False, local=False, dryrun=False, quiet=False, require=False, reponame=None, regex=False, pcre=False) +Install package from repositories +.sp +CLI Example: +.sp +.nf +.ft C +salt \(aq*\(aq pkgng.install + +orphan + Mark the installed package as orphan. Will be automatically removed + if no other packages depend on them. For more information please + refer to pkg\-autoremove(8). + + CLI Example:: + + salt \(aq*\(aq pkgng.install orphan=True + +force + Force the reinstallation of the package if already installed. + + CLI Example:: + + salt \(aq*\(aq pkgng.install force=True + +glob + Treat the package names as shell glob patterns. + + CLI Example:: + + salt \(aq*\(aq pkgng.install glob=True + +local + Skip updating the repository catalogues with pkg\-update(8). Use the + locally cached copies only. + + CLI Example:: + + salt \(aq*\(aq pkgng.install local=True + +dryrun + Dru\-run mode. The list of changes to packages is always printed, + but no changes are actually made. + + CLI Example:: + + salt \(aq*\(aq pkgng.install dryrun=True + +quiet + Force quiet output, except when dryrun is used, where pkg install + will always show packages to be installed, upgraded or deleted. + + CLI Example:: + + salt \(aq*\(aq pkgng.install quiet=True + +require + When used with force, reinstalls any packages that require the + given package. + + CLI Example:: + + salt \(aq*\(aq pkgng.install require=True force=True + +reponame + In multi\-repo mode, override the pkg.conf ordering and only attempt + to download packages from the named repository. + + CLI Example:: + + salt \(aq*\(aq pkgng.install reponame=repo + +regex + Treat the package names as a regular expression + + CLI Example:: + + salt \(aq*\(aq pkgng.install regex=True + +pcre + Treat the package names as extended regular expressions. + + CLI Example:: + + salt \(aq*\(aq pkgng.install pcre=True +.ft P +.fi +.UNINDENT +.INDENT 0.0 +.TP +.B salt.modules.pkgng.parse_config(file_name=\(aq/usr/local/etc/pkg.conf\(aq) +Return dict of uncommented global variables. .sp CLI Example: .sp .nf .ft C -salt \(aq*\(aq pkg.compare \(aq0.2.4\-0\(aq \(aq0.2.4.1\-0\(aq +salt \(aq*\(aq pkgng.parse_config +*NOTE* not working right .ft P .fi .UNINDENT .INDENT 0.0 .TP -.B salt.modules.pkgng.delete(pkg_name) -Delete a package from the database and system -.INDENT 7.0 -.TP -.B CLI Example:: -salt \(aq*\(aq pkgng.delete bash -.UNINDENT -.UNINDENT -.INDENT 0.0 -.TP -.B salt.modules.pkgng.info(pkg=None) -Returns info on packages installed on system -.INDENT 7.0 -.TP -.B CLI Example:: -salt \(aq*\(aq pkgng.info +.B salt.modules.pkgng.perform_cmp(pkg1=\(aq\(aq, pkg2=\(aq\(aq) +Do a cmp\-style comparison on two packages. Return \-1 if pkg1 < pkg2, 0 if +pkg1 == pkg2, and 1 if pkg1 > pkg2. Return None if there was a problem +making the comparison. .sp -For individual info +CLI Example: .sp -salt \(aq*\(aq pkgng.info sudo -.UNINDENT +.nf +.ft C +salt \(aq*\(aq pkg.perform_cmp \(aq0.2.4\-0\(aq \(aq0.2.4.1\-0\(aq +salt \(aq*\(aq pkg.perform_cmp pkg1=\(aq0.2.4\-0\(aq pkg2=\(aq0.2.4.1\-0\(aq +.ft P +.fi .UNINDENT .INDENT 0.0 .TP -.B salt.modules.pkgng.install(pkg_name) -Install package from repositories -.INDENT 7.0 -.TP -.B CLI Example:: -salt \(aq*\(aq pkgng.install bash -.UNINDENT +.B salt.modules.pkgng.restore(file_name) +Reads archive created by pkg backup \-d and recreates the database. +.sp +salt \(aq*\(aq pkgng.restore /tmp/pkg .UNINDENT .INDENT 0.0 .TP -.B salt.modules.pkgng.parse_config(file_name=\(aq/usr/local/etc/pkg.conf\(aq) -Return dict of uncommented global variables. +.B salt.modules.pkgng.search(pkg_name, exact=False, glob=False, regex=False, pcre=False, comment=False, desc=False, full=False, depends=False, size=False, quiet=False, origin=False, prefix=False) +Searches in remote package repositories .sp CLI Example: .sp .nf .ft C -salt \(aq*\(aq pkgng.parse_config -*NOTE* not working right +salt \(aq*\(aq pkgng.search pattern + +exact + Treat pattern as exact pattern. + + CLI Example:: + + salt \(aq*\(aq pkgng.search pattern exact=True + +glob + Treat pattern as a shell glob pattern. + + CLI Example:: + + salt \(aq*\(aq pkgng.search pattern glob=True + +regex + Treat pattern as a regular expression. + + CLI Example:: + + salt \(aq*\(aq pkgng.search pattern regex=True + +pcre + Treat pattern as an extended regular expression. + + CLI Example:: + + salt \(aq*\(aq pkgng.search pattern pcre=True + +comment + Search for pattern in the package comment one\-line description. + + CLI Example:: + + salt \(aq*\(aq pkgng.search pattern comment=True + +desc + Search for pattern in the package description. + + CLI Example:: + + salt \(aq*\(aq pkgng.search pattern desc=True + +full + Displays full information about the matching packages. + + CLI Example:: + + salt \(aq*\(aq pkgng.search pattern full=True + +depends + Displays the dependencies of pattern. + + CLI Example:: + + salt \(aq*\(aq pkgng.search pattern depends=True + +size + Displays the size of the package + + CLI Example:: + + salt \(aq*\(aq pkgng.search pattern size=True + +quiet + Be quiet. Prints only the requested information without displaying + many hints. + + CLI Example:: + + salt \(aq*\(aq pkgng.search pattern quiet=True + +origin + Displays pattern origin. + + CLI Example:: + + salt \(aq*\(aq pkgng.search pattern origin=True + +prefix + Displays the installation prefix for each package matching pattern. + + CLI Example:: + + salt \(aq*\(aq pkgng.search pattern prefix=True .ft P .fi .UNINDENT .INDENT 0.0 .TP -.B salt.modules.pkgng.restore(file_name) -Reads archive created by pkg backup \-d and recreates the database. -.UNINDENT -.INDENT 0.0 -.TP -.B salt.modules.pkgng.stats() +.B salt.modules.pkgng.stats(local=False, remote=False) Return pkgng stats. -.INDENT 7.0 -.TP -.B CLI Example:: +.sp +CLI Example: +.sp +.nf +.ft C salt \(aq*\(aq pkgng.stats -.UNINDENT + +local + Display stats only for the local package database. + + CLI Example:: + + salt \(aq*\(aq pkgng.stats local=True + +remote + Display stats only for the remote package database(s). + + CLI Example:: + + salt \(aq*\(aq pkgng.stats remote=True +.ft P +.fi .UNINDENT .INDENT 0.0 .TP -.B salt.modules.pkgng.update() +.B salt.modules.pkgng.update(force=False) Refresh PACKAGESITE contents -.INDENT 7.0 -.TP -.B CLI Example:: +.sp +CLI Example: +.sp +.nf +.ft C salt \(aq*\(aq pkgng.update -.UNINDENT + +force + Force a full download of the repository catalogue without regard to + the respective ages of the local and remote copies of the + catalogue. + + CLI Example:: + + salt \(aq*\(aq pkgng.update force=True +.ft P +.fi .UNINDENT .INDENT 0.0 .TP @@ -16522,31 +18675,119 @@ salt \(aq*\(aq pkgng.update Updates remote package repo url, PACKAGESITE var to be exact. .sp Must be using \fI\%http://\fP, \fI\%ftp://\fP, or https// protos -.INDENT 7.0 -.TP -.B CLI Example:: -salt \(aq*\(aq pkgng.update_package_site \fI\%http://127.0.0.1/\fP +.sp +CLI Example: +.sp +.nf +.ft C +salt \(aq*\(aq pkgng.update_package_site http://127.0.0.1/ +.ft P +.fi .UNINDENT +.INDENT 0.0 +.TP +.B salt.modules.pkgng.updating(pkg_name, filedate=None, filename=None) +\(aq +Displays UPDATING entries of software packages +.sp +CLI Example: +.sp +.nf +.ft C +salt \(aq*\(aq pkgng.updating foo + +filedate + Only entries newer than date are shown. Use a YYYYMMDD date format. + + CLI Example:: + + salt \(aq*\(aq pkgng.updating foo filedate=20130101 + +filename + Defines an alternative location of the UPDATING file. + + CLI Example:: + + salt \(aq*\(aq pkgng.updating foo filename=/tmp/UPDATING +.ft P +.fi .UNINDENT .INDENT 0.0 .TP -.B salt.modules.pkgng.upgrade() +.B salt.modules.pkgng.upgrade(force=False, local=False, dryrun=False) Upgrade all packages -.INDENT 7.0 -.TP -.B CLI Example:: +.sp +CLI Example: +.sp +.nf +.ft C salt \(aq*\(aq pkgng.upgrade -.UNINDENT + +force + Force reinstalling/upgrading the whole set of packages. + + CLI Example:: + + salt \(aq*\(aq pkgng.upgrade force=True + +local + Skip updating the repository catalogues with pkg\-update(8). Use the + local cache only. + + CLI Example:: + + salt \(aq*\(aq pkgng.update local=True + +dryrun + Dry\-run mode: show what packages have updates available, but do not + perform any upgrades. Repository catalogues will be updated as + usual unless the local option is also given. + + CLI Example:: + + salt \(aq*\(aq pkgng.update dryrun=True +.ft P +.fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.pkgng.version() Displays the current version of pkg -.INDENT 7.0 -.TP -.B CLI Example:: +.sp +CLI Example: +.sp +.nf +.ft C salt \(aq*\(aq pkgng.version +.ft P +.fi .UNINDENT +.INDENT 0.0 +.TP +.B salt.modules.pkgng.which(file_name, origin=False, quiet=False) +Displays which package installed a specific file +.sp +CLI Example: +.sp +.nf +.ft C +salt \(aq*\(aq pkgng.which + +origin + Shows the origin of the package instead of name\-version. + + CLI Example:: + + salt \(aq*\(aq pkgng.which origin=True + +quiet + Quiet output. + + CLI Example:: + + salt \(aq*\(aq pkgng.which quiet=True +.ft P +.fi .UNINDENT .SS salt.modules.pkg_resource .sp @@ -16555,35 +18796,77 @@ Resources needed by pkg providers .TP .B salt.modules.pkg_resource.add_pkg(pkgs, name, version) Add a package to a dict of installed packages. +.sp +CLI Example: +.sp +.nf +.ft C +salt \(aq*\(aq pkg_resource.add_pkg \(aq{}\(aq bind 9 +.ft P +.fi .UNINDENT .INDENT 0.0 .TP -.B salt.modules.pkg_resource.check_targets(targets=None) -Examines target package names to make sure they were formatted properly. +.B salt.modules.pkg_resource.check_desired(desired=None) +Examines desired package names to make sure they were formatted properly. Returns a list of problems encountered. +.sp +CLI Examples: +.sp +.nf +.ft C +salt \(aq*\(aq pkg_resource.check_desired +.ft P +.fi .UNINDENT .INDENT 0.0 .TP -.B salt.modules.pkg_resource.compare(pkg1=\(aq\(aq, pkg2=\(aq\(aq) -Compares two version strings using distutils.version.LooseVersion. This is -a fallback for providers which don\(aqt have a version comparison utility -built into them. Return \-1 if version1 < version2, 0 if version1 == -version2, and 1 if version1 > version2. Return None if there was a problem -making the comparison. +.B salt.modules.pkg_resource.compare(pkg1=\(aq\(aq, oper=\(aq==\(aq, pkg2=\(aq\(aq) +Package version comparison function. +.sp +CLI Example: +.sp +.nf +.ft C +salt \(aq*\(aq pkg_resource.compare +.ft P +.fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.pkg_resource.find_changes(old=None, new=None) Compare before and after results from pkg.list_pkgs() to determine what changes were made to the packages installed on the minion. +.sp +CLI Example: +.sp +.nf +.ft C +salt \(aq*\(aq pkg_resource.find_changes +.ft P +.fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.pkg_resource.pack_pkgs(pkgs) -Accepts list (or a string representing a list) and returns back either the -list passed, or the list represenation of the string passed. +Accepts a list of packages or package/version pairs (or a string +representing said list) and returns a dict of name/version pairs. For a +given package, if no version was specified (i.e. the value is a string and +not a dict, then the dict returned will use None as the value for that +package. +.INDENT 7.0 +.TP +.B Example: \(aq["foo", {"bar": 1.2}, "baz"]\(aq would become +{\(aqfoo\(aq: None, \(aqbar\(aq: 1.2, \(aqbaz\(aq: None} +.UNINDENT .sp -Example: \(aq["foo","bar","baz"]\(aq would become ["foo","bar","baz"] +CLI Example: +.sp +.nf +.ft C +salt \(aq*\(aq pkg_resource.pack_pkgs \(aq["foo", {"bar": 1.2}, "baz"]\(aq +.ft P +.fi .UNINDENT .INDENT 0.0 .TP @@ -16593,6 +18876,14 @@ the key/value pairs into a single dict. .sp Example: \(aq[{"foo": "salt://foo.rpm"}, {"bar": "salt://bar.rpm"}]\(aq would become {"foo": "salt://foo.rpm", "bar": "salt://bar.rpm"} +.sp +CLI Example: +.sp +.nf +.ft C +salt \(aq*\(aq pkg_resource.pack_sources \(aq[{"foo": "salt://foo.rpm"}, {"bar": "salt://bar.rpm"}]\(aq +.ft P +.fi .UNINDENT .INDENT 0.0 .TP @@ -16600,6 +18891,31 @@ become {"foo": "salt://foo.rpm", "bar": "salt://bar.rpm"} Parses the input to pkg.install and returns back the package(s) to be installed. Returns a list of packages, as well as a string noting whether the packages are to come from a repository or a binary package. +.sp +CLI Example: +.sp +.nf +.ft C +salt \(aq*\(aq pkg_resource.parse_targets +.ft P +.fi +.UNINDENT +.INDENT 0.0 +.TP +.B salt.modules.pkg_resource.perform_cmp(pkg1=\(aq\(aq, pkg2=\(aq\(aq) +Compares two version strings using distutils.version.LooseVersion. This is +a fallback for providers which don\(aqt have a version comparison utility +built into them. Return \-1 if version1 < version2, 0 if version1 == +version2, and 1 if version1 > version2. Return None if there was a problem +making the comparison. +.sp +CLI Example: +.sp +.nf +.ft C +salt \(aq*\(aq pkg_resource.perform_cmp +.ft P +.fi .UNINDENT .INDENT 0.0 .TP @@ -16607,6 +18923,14 @@ the packages are to come from a repository or a binary package. Accepts a dict obtained from pkg.list_pkgs() and sorts in place the list of versions for any packages that have multiple versions installed, so that two package lists can be compared to one another. +.sp +CLI Example: +.sp +.nf +.ft C +salt \(aq*\(aq pkg_resource.sort_pkglist \(aq["3.45", "2.13"]\(aq +.ft P +.fi .UNINDENT .SS salt.modules.pkgutil .sp @@ -16626,16 +18950,15 @@ salt \(aq*\(aq pkgutil.available_version CSWpython .UNINDENT .INDENT 0.0 .TP -.B salt.modules.pkgutil.compare(version1=\(aq\(aq, version2=\(aq\(aq) -Compare two version strings. Return \-1 if version1 < version2, -0 if version1 == version2, and 1 if version1 > version2. Return None if -there was a problem making the comparison. +.B salt.modules.pkgutil.compare(pkg1=\(aq\(aq, oper=\(aq==\(aq, pkg2=\(aq\(aq) +Compare two version strings. .sp CLI Example: .sp .nf .ft C -salt \(aq*\(aq pkg.compare \(aq0.2.4\-0\(aq \(aq0.2.4.1\-0\(aq +salt \(aq*\(aq pkg.compare \(aq0.2.4\-0\(aq \(aq<\(aq \(aq0.2.4.1\-0\(aq +salt \(aq*\(aq pkg.compare pkg1=\(aq0.2.4\-0\(aq oper=\(aq<\(aq pkg2=\(aq0.2.4.1\-0\(aq .ft P .fi .UNINDENT @@ -16683,7 +19006,7 @@ salt \(aq*\(aq pkgutil.list_pkgs .UNINDENT .INDENT 0.0 .TP -.B salt.modules.pkgutil.list_upgrades() +.B salt.modules.pkgutil.list_upgrades(refresh=True) List all available package upgrades on this system .sp CLI Example: @@ -16696,6 +19019,22 @@ salt \(aq*\(aq pkgutil.list_upgrades .UNINDENT .INDENT 0.0 .TP +.B salt.modules.pkgutil.perform_cmp(pkg1=\(aq\(aq, pkg2=\(aq\(aq) +Do a cmp\-style comparison on two packages. Return \-1 if pkg1 < pkg2, 0 if +pkg1 == pkg2, and 1 if pkg1 > pkg2. Return None if there was a problem +making the comparison. +.sp +CLI Example: +.sp +.nf +.ft C +salt \(aq*\(aq pkg.perform_cmp \(aq0.2.4\-0\(aq \(aq0.2.4.1\-0\(aq +salt \(aq*\(aq pkg.perform_cmp pkg1=\(aq0.2.4\-0\(aq pkg2=\(aq0.2.4.1\-0\(aq +.ft P +.fi +.UNINDENT +.INDENT 0.0 +.TP .B salt.modules.pkgutil.purge(name, **kwargs) Remove a package and all its dependencies which are not in use by other packages. @@ -16868,7 +19207,47 @@ salt \(aq*\(aq postgres.db_remove \(aqdbname\(aq .UNINDENT .INDENT 0.0 .TP -.B salt.modules.postgres.user_create(username, user=None, host=None, port=None, createdb=False, createuser=False, encrypted=False, superuser=False, replication=False, password=None, runas=None) +.B salt.modules.postgres.group_create(groupname, user=None, host=None, port=None, createdb=False, createuser=False, encrypted=False, superuser=False, replication=False, password=None, groups=None, runas=None) +Creates a Postgres group. A group is postgres is similar to a user, but +cannot login. +.sp +CLI Example: +.sp +.nf +.ft C +salt \(aq*\(aq postgres.group_create \(aqgroupname\(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.group_remove(groupname, user=None, host=None, port=None, runas=None) +Removes a group from the Postgres server. +.sp +CLI Example: +.sp +.nf +.ft C +salt \(aq*\(aq postgres.group_remove \(aqgroupname\(aq +.ft P +.fi +.UNINDENT +.INDENT 0.0 +.TP +.B salt.modules.postgres.group_update(groupname, user=None, host=None, port=None, createdb=False, createuser=False, encrypted=False, replication=False, password=None, groups=None, runas=None) +Updated a postgres group +.sp +CLI Examples: +.sp +.nf +.ft C +salt \(aq*\(aq postgres.group_update \(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.user_create(username, user=None, host=None, port=None, createdb=False, createuser=False, encrypted=False, superuser=False, replication=False, password=None, groups=None, runas=None) Creates a Postgres user. .sp CLI Examples: @@ -16920,7 +19299,7 @@ salt \(aq*\(aq postgres.user_remove \(aqusername\(aq .UNINDENT .INDENT 0.0 .TP -.B salt.modules.postgres.user_update(username, user=None, host=None, port=None, createdb=False, createuser=False, encrypted=False, replication=False, password=None, runas=None) +.B salt.modules.postgres.user_update(username, user=None, host=None, port=None, createdb=False, createuser=False, encrypted=False, replication=False, password=None, groups=None, runas=None) Creates a Postgres user. .sp CLI Examples: @@ -17340,10 +19719,6 @@ salt system.example.com publish.full_data \(aq*\(aq cmd.run \(aqls \-la /tmp\(aq .UNINDENT .INDENT 0.0 .TP -.B salt.modules.publish.normalize_arg(arg) -.UNINDENT -.INDENT 0.0 -.TP .B salt.modules.publish.publish(tgt, fun, arg=None, expr_form=\(aqglob\(aq, returner=\(aq\(aq, timeout=5) Publish a command from the minion out to other minions, publications need to be enabled on the Salt master and the minion needs to have permission @@ -17351,6 +19726,17 @@ to publish the command. The Salt master will also prevent a recursive publication loop, this means that a minion cannot command another minion to command another minion as that would create an infinite command loop. .sp +The expr_form argument is used to pass a target other than a glob into +the execution, the available options are: +glob +pcre +grain +grain_pcre +pillar +ipcidr +range +compound +.sp The arguments sent to the minion publish function are separated with commas. This means that for a minion executing a command with multiple args it will look like this: @@ -17358,6 +19744,7 @@ args it will look like this: .nf .ft C salt system.example.com publish.publish \(aq*\(aq user.add \(aqfoo,1020,1020\(aq +salt system.example.com publish.publish \(aqos:Fedora\(aq network.interfaces \(aq\(aq grain .ft P .fi .sp @@ -18287,6 +20674,14 @@ The command to execute. None The user to run rvm as. .UNINDENT +.sp +CLI Example: +.sp +.nf +.ft C +salt \(aq*\(aq rvm.do 2.0.0 +.ft P +.fi .UNINDENT .INDENT 0.0 .TP @@ -18304,6 +20699,14 @@ The destination gemset. None The user to run rvm as. .UNINDENT +.sp +CLI Example: +.sp +.nf +.ft C +salt \(aq*\(aq rvm.gemset_copy foobar bazquo +.ft P +.fi .UNINDENT .INDENT 0.0 .TP @@ -18321,6 +20724,14 @@ The name of the gemset to create. None The user to run rvm as. .UNINDENT +.sp +CLI Example: +.sp +.nf +.ft C +salt \(aq*\(aq rvm.gemset_create 2.0.0 foobar +.ft P +.fi .UNINDENT .INDENT 0.0 .TP @@ -18338,6 +20749,14 @@ The gemset to delete. None The user to run rvm as. .UNINDENT +.sp +CLI Example: +.sp +.nf +.ft C +salt \(aq*\(aq rvm.gemset_delete 2.0.0 foobar +.ft P +.fi .UNINDENT .INDENT 0.0 .TP @@ -18355,6 +20774,14 @@ The gemset to empty. None The user to run rvm as. .UNINDENT +.sp +CLI Example: +.sp +.nf +.ft C +salt \(aq*\(aq rvm.gemset_empty 2.0.0 foobar +.ft P +.fi .UNINDENT .INDENT 0.0 .TP @@ -18370,6 +20797,14 @@ The ruby version to list the gemsets for None The user to run rvm as. .UNINDENT +.sp +CLI Example: +.sp +.nf +.ft C +salt \(aq*\(aq rvm.gemset_list +.ft P +.fi .UNINDENT .INDENT 0.0 .TP @@ -18383,6 +20818,14 @@ Note that you must have set a default ruby before this can work. None The user to run rvm as. .UNINDENT +.sp +CLI Example: +.sp +.nf +.ft C +salt \(aq*\(aq rvm.gemset_list_all +.ft P +.fi .UNINDENT .INDENT 0.0 .TP @@ -18397,11 +20840,27 @@ Which version of RVM to install, e.g. stable or head. .B ruby The version of ruby to reinstall. .UNINDENT +.sp +CLI Example: +.sp +.nf +.ft C +salt \(aq*\(aq rvm.get +.ft P +.fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.rvm.install() Install RVM system wide. +.sp +CLI Example: +.sp +.nf +.ft C +salt \(aq*\(aq rvm.install +.ft P +.fi .UNINDENT .INDENT 0.0 .TP @@ -18416,11 +20875,27 @@ The version of ruby to install. None The user to run rvm as. .UNINDENT +.sp +CLI Example: +.sp +.nf +.ft C +salt \(aq*\(aq rvm.install_ruby 1.9.3\-p385 +.ft P +.fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.rvm.is_installed() Check if RVM is installed. +.sp +CLI Example: +.sp +.nf +.ft C +salt \(aq*\(aq rvm.is_installed +.ft P +.fi .UNINDENT .INDENT 0.0 .TP @@ -18432,6 +20907,14 @@ List all rvm installed rubies. None The user to run rvm as. .UNINDENT +.sp +CLI Example: +.sp +.nf +.ft C +salt \(aq*\(aq rvm.list +.ft P +.fi .UNINDENT .INDENT 0.0 .TP @@ -18446,6 +20929,14 @@ The version of ruby to reinstall. None The user to run rvm as. .UNINDENT +.sp +CLI Example: +.sp +.nf +.ft C +salt \(aq*\(aq rvm.reinstall_ruby 1.9.3\-p385 +.ft P +.fi .UNINDENT .INDENT 0.0 .TP @@ -18463,6 +20954,14 @@ The version of rubygems to install or \(aqremove\(aq to use the version that shi None The user to run rvm as. .UNINDENT +.sp +CLI Example: +.sp +.nf +.ft C +salt \(aq*\(aq rvm.rubygems 2.0.0 1.8.24 +.ft P +.fi .UNINDENT .INDENT 0.0 .TP @@ -18477,6 +20976,14 @@ The version of ruby to make the default. None The user to run rvm as. .UNINDENT +.sp +CLI Example: +.sp +.nf +.ft C +salt \(aq*\(aq rvm.set_default 2.0.0 +.ft P +.fi .UNINDENT .INDENT 0.0 .TP @@ -18498,6 +21005,14 @@ The user to run rvm as. None The names of the binaries to create wrappers for. When nothing is given, wrappers for ruby, gem, rake, irb, rdoc, ri and testrb are generated. .UNINDENT +.sp +CLI Example: +.sp +.nf +.ft C +salt \(aq*\(aq rvm.wrapper +.ft P +.fi .UNINDENT .SS salt.modules.saltutil .sp @@ -18638,6 +21153,22 @@ salt \(aq*\(aq saltutil.sync_modules .UNINDENT .INDENT 0.0 .TP +.B salt.modules.saltutil.sync_outputters(env=None) +Sync the outputters from the _outputters directory on the salt master file +server. This function is environment aware, pass the desired environment +to grab the contents of the _outputters directory, base is the default +environment. +.sp +CLI Example: +.sp +.nf +.ft C +salt \(aq*\(aq saltutil.sync_outputters +.ft P +.fi +.UNINDENT +.INDENT 0.0 +.TP .B salt.modules.saltutil.sync_renderers(env=None) Sync the renderers from the _renderers directory on the salt master file server. This function is environment aware, pass the desired environment @@ -19216,16 +21747,15 @@ package. .UNINDENT .INDENT 0.0 .TP -.B salt.modules.solarispkg.compare(version1=\(aq\(aq, version2=\(aq\(aq) -Compare two version strings. Return \-1 if version1 < version2, -0 if version1 == version2, and 1 if version1 > version2. Return None if -there was a problem making the comparison. +.B salt.modules.solarispkg.compare(pkg1=\(aq\(aq, oper=\(aq==\(aq, pkg2=\(aq\(aq) +Compare two version strings. .sp CLI Example: .sp .nf .ft C -salt \(aq*\(aq pkg.compare \(aq0.2.4\-0\(aq \(aq0.2.4.1\-0\(aq +salt \(aq*\(aq pkg.compare \(aq0.2.4\-0\(aq \(aq<\(aq \(aq0.2.4.1\-0\(aq +salt \(aq*\(aq pkg.compare pkg1=\(aq0.2.4\-0\(aq oper=\(aq<\(aq pkg2=\(aq0.2.4.1\-0\(aq .ft P .fi .UNINDENT @@ -19398,6 +21928,22 @@ salt \(aq*\(aq pkg.list_pkgs .UNINDENT .INDENT 0.0 .TP +.B salt.modules.solarispkg.perform_cmp(pkg1=\(aq\(aq, pkg2=\(aq\(aq) +Do a cmp\-style comparison on two packages. Return \-1 if pkg1 < pkg2, 0 if +pkg1 == pkg2, and 1 if pkg1 > pkg2. Return None if there was a problem +making the comparison. +.sp +CLI Example: +.sp +.nf +.ft C +salt \(aq*\(aq pkg.perform_cmp \(aq0.2.4\-0\(aq \(aq0.2.4.1\-0\(aq +salt \(aq*\(aq pkg.perform_cmp pkg1=\(aq0.2.4\-0\(aq pkg2=\(aq0.2.4.1\-0\(aq +.ft P +.fi +.UNINDENT +.INDENT 0.0 +.TP .B salt.modules.solarispkg.purge(name, **kwargs) Remove a single package with pkgrm .sp @@ -20608,6 +23154,14 @@ salt \(aq*\(aq ssh.check_key .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 +.sp +CLI Example: +.sp +.nf +.ft C +salt \(aq*\(aq root salt://ssh/keyfile +.ft P +.fi .UNINDENT .INDENT 0.0 .TP @@ -20846,6 +23400,14 @@ salt \(aq*\(aq state.show_sls core,edit.vim dev .TP .B salt.modules.state.show_top() Return the top data that the minion will use for a highstate +.sp +CLI Example: +.sp +.nf +.ft C +salt \(aq*\(aq state.show_top +.ft P +.fi .UNINDENT .INDENT 0.0 .TP @@ -20868,7 +23430,7 @@ salt \(aq*\(aq state.single pkg.installed name=vim .UNINDENT .INDENT 0.0 .TP -.B salt.modules.state.sls(mods, env=\(aqbase\(aq, test=None, **kwargs) +.B salt.modules.state.sls(mods, env=\(aqbase\(aq, test=None, exclude=None, **kwargs) Execute a set list of state modules from an environment, default environment is base .sp @@ -21153,6 +23715,46 @@ salt \(aq*\(aq status.w Provide the service module for supervisord .INDENT 0.0 .TP +.B salt.modules.supervisord.add(name, user=None) +Activates any updates in config for process/group +.INDENT 7.0 +.TP +.B CLI Example:: +salt \(aq*\(aq supervisord.add +.UNINDENT +.UNINDENT +.INDENT 0.0 +.TP +.B salt.modules.supervisord.custom(command, user=None) +Run any custom supervisord command +.INDENT 7.0 +.TP +.B CLI Example:: +salt \(aq*\(aq supervisord.custom "mstop \(aq\fIgunicorn\fP\(aq" +.UNINDENT +.UNINDENT +.INDENT 0.0 +.TP +.B salt.modules.supervisord.remove(name, user=None) +Removes process/group from active config +.INDENT 7.0 +.TP +.B CLI Example:: +salt \(aq*\(aq supervisord.remove +.UNINDENT +.UNINDENT +.INDENT 0.0 +.TP +.B salt.modules.supervisord.reread(user=None) +Reload the daemon\(aqs configuration files +.INDENT 7.0 +.TP +.B CLI Example:: +salt \(aq*\(aq supervisord.reread +.UNINDENT +.UNINDENT +.INDENT 0.0 +.TP .B salt.modules.supervisord.restart(name=\(aqall\(aq, user=None) Restart the named service. .INDENT 7.0 @@ -21174,6 +23776,25 @@ salt \(aq*\(aq supervisord.start .INDENT 0.0 .TP .B salt.modules.supervisord.status(name=None, user=None) +List programms and its state +.INDENT 7.0 +.TP +.B CLI Example:: +salt \(aq*\(aq supervisord.status +.UNINDENT +.UNINDENT +.INDENT 0.0 +.TP +.B salt.modules.supervisord.status_raw(name=None, user=None) +Display the raw output of status +.sp +CLI Example: +.sp +.nf +.ft C +salt \(aq*\(aq supervisord.status_raw +.ft P +.fi .UNINDENT .INDENT 0.0 .TP @@ -21185,6 +23806,16 @@ Stop the named service. salt \(aq*\(aq supervisord.stop .UNINDENT .UNINDENT +.INDENT 0.0 +.TP +.B salt.modules.supervisord.update(user=None) +Reload config and add/remove as necessary +.INDENT 7.0 +.TP +.B CLI Example:: +salt \(aq*\(aq supervisord.update +.UNINDENT +.UNINDENT .SS salt.modules.svn .sp Subversion SCM @@ -21205,6 +23836,14 @@ files and directories to pass to the command as arguments None Run svn as a user other than what the minion runs as .UNINDENT +.sp +CLI Example: +.sp +.nf +.ft C +salt \(aq*\(aq svn.add /path/to/repo /path/to/new/file +.ft P +.fi .UNINDENT .INDENT 0.0 .TP @@ -21233,6 +23872,14 @@ Run svn as a user other than what the minion runs as None Connect to the Subversion server as another user .UNINDENT +.sp +CLI Example: +.sp +.nf +.ft C +salt \(aq*\(aq svn.checkout /path/to/repo svn://remote/repo +.ft P +.fi .UNINDENT .INDENT 0.0 .TP @@ -21261,6 +23908,46 @@ Run svn as a user other than what the minion runs as None Connect to the Subversion server as another user .UNINDENT +.sp +CLI Example: +.sp +.nf +.ft C +salt \(aq*\(aq svn.commit /path/to/repo +.ft P +.fi +.UNINDENT +.INDENT 0.0 +.TP +.B salt.modules.svn.diff(cwd, targets=None, user=None, username=None, *opts) +Return the diff of the current directory, files, or directories from +the remote Subversion repository +.INDENT 7.0 +.TP +.B cwd +The path to the Subversion repository +.TP +.B targets +None +files and directories to pass to the command as arguments +Default: svn uses \(aq.\(aq +.TP +.B user +None +Run svn as a user other than what the minion runs as +.TP +.B username +None +Connect to the Subversion server as another user +.UNINDENT +.sp +CLI Example: +.sp +.nf +.ft C +salt \(aq*\(aq svn.diff /path/to/repo +.ft P +.fi .UNINDENT .INDENT 0.0 .TP @@ -21289,6 +23976,14 @@ str How to fmt the output from info. (str, xml, list, dict) .UNINDENT +.sp +CLI Example: +.sp +.nf +.ft C +salt \(aq*\(aq svn.info /path/to/svn/repo +.ft P +.fi .UNINDENT .INDENT 0.0 .TP @@ -21315,6 +24010,14 @@ Run svn as a user other than what the minion runs as None Connect to the Subversion server as another user .UNINDENT +.sp +CLI Example: +.sp +.nf +.ft C +salt \(aq*\(aq svn.remove /path/to/repo /path/to/repo/remove +.ft P +.fi .UNINDENT .INDENT 0.0 .TP @@ -21339,6 +24042,14 @@ Run svn as a user other than what the minion runs as None Connect to the Subversion server as another user .UNINDENT +.sp +CLI Example: +.sp +.nf +.ft C +salt \(aq*\(aq svn.status /path/to/repo +.ft P +.fi .UNINDENT .INDENT 0.0 .TP @@ -21363,6 +24074,14 @@ Run svn as a user other than what the minion runs as None Connect to the Subversion server as another user .UNINDENT +.sp +CLI Example: +.sp +.nf +.ft C +salt \(aq*\(aq svn.update /path/to/repo +.ft P +.fi .UNINDENT .SS salt.modules.sysbench .sp @@ -21464,27 +24183,34 @@ minion. .INDENT 0.0 .TP .B salt.modules.sysmod.doc(module=\(aq\(aq) -Return the docstrings for all modules, these strings are aggregated into -a single document on the master for easy reading. +Return the docstrings for all modules. Optionally, specify a module or a +function to narrow te selection. +.sp +The strings are aggregated into a single document on the master for easy +reading. .sp CLI Example: .sp .nf .ft C salt \e* sys.doc +salt \e* sys.doc sys +salt \e* sys.doc sys.doc .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.sysmod.list_functions(module=\(aq\(aq) -List the functions. Optionally, specify a module to list from. +List the functions for all modules. Optionally, specify a module to list +from. .sp CLI Example: .sp .nf .ft C salt \e* sys.list_functions +salt \e* sys.list_functions sys .ft P .fi .UNINDENT @@ -21522,6 +24248,14 @@ Provide the service module for systemd .B salt.modules.systemd.available(name) Check that the given service is available taking into account template units. +.sp +CLI Example: +.sp +.nf +.ft C +salt \(aq*\(aq service.available sshd +.ft P +.fi .UNINDENT .INDENT 0.0 .TP @@ -21920,7 +24654,11 @@ salt \(aq*\(aq timezone.set_hwclock UTC .INDENT 0.0 .TP .B salt.modules.timezone.set_zone(timezone) -Unlinks, then symlinks /etc/localtime to the set timezone +Unlinks, then symlinks /etc/localtime to the set timezone. +.sp +The timezone is crucial to several system processes, each of which SHOULD +be restarted (for instance, whatever you system uses as its cron and +syslog daemons). This will not be magically done for you! .sp CLI Example: .sp @@ -21930,6 +24668,21 @@ salt \(aq*\(aq timezone.set_zone \(aqAmerica/Denver\(aq .ft P .fi .UNINDENT +.INDENT 0.0 +.TP +.B salt.modules.timezone.zone_compare(timezone) +Checks the md5sum between the given timezone, and the one set in +/etc/localtime. Returns True if they match, and False if not. Mostly useful +for running state checks. +.sp +Example: +.sp +.nf +.ft C +salt \(aq*\(aq timezone.zone_compare \(aqAmerica/Denver\(aq +.ft P +.fi +.UNINDENT .SS salt.modules.tls .sp A salt module for SSL/TLS. @@ -22006,6 +24759,14 @@ the resulting CA would be written in the following location: /etc/pki/koji/koji_ca_cert.crt .ft P .fi +.sp +CLI Example: +.sp +.nf +.ft C +salt \(aq*\(aq tls.create_ca test_ca +.ft P +.fi .UNINDENT .INDENT 0.0 .TP @@ -22018,7 +24779,7 @@ named Certificate Authority (CA) name of the CA .TP .B CN -common name matching the the certificate signing request +common name matching the certificate signing request .TP .B days number of days certficate is valid, default is 365 (1 year) @@ -22029,6 +24790,14 @@ exists, the function just returns assuming the CERT already exists. .sp The CN \fImust\fP match an existing CSR generated by create_csr. If it does not, this method does nothing. +.sp +CLI Example: +.sp +.nf +.ft C +salt \(aq*\(aq tls.create_ca_signed_cert test localhost +.ft P +.fi .UNINDENT .INDENT 0.0 .TP @@ -22080,6 +24849,14 @@ following location: .sp /etc/pki/koji/certs/test.egavas.org.csr /etc/pki/koji/certs/test.egavas.org.key +.sp +CLI Example: +.sp +.nf +.ft C +salt \(aq*\(aq tls.create_csr test +.ft P +.fi .UNINDENT .INDENT 0.0 .TP @@ -22096,6 +24873,14 @@ common name matching the the certificate signing request .B passphrase used to unlock the PKCS#12 certificate when loaded into the browser .UNINDENT +.sp +CLI Example: +.sp +.nf +.ft C +salt \(aq*\(aq tls.create_pkcs12 test localhost +.ft P +.fi .UNINDENT .INDENT 0.0 .TP @@ -22146,6 +24931,14 @@ following location: .sp /etc/pki/tls/certs/test.egavas.org.crt /etc/pki/tls/certs/test.egavas.org.key +.sp +CLI Example: +.sp +.nf +.ft C +salt \(aq*\(aq tls.create_self_signed_cert +.ft P +.fi .UNINDENT .SS salt.modules.tomcat .sp @@ -23998,16 +26791,15 @@ salt \(aq*\(aq pkg.available_version .UNINDENT .INDENT 0.0 .TP -.B salt.modules.win_pkg.compare(version1=\(aq\(aq, version2=\(aq\(aq) -Compare two version strings. Return \-1 if version1 < version2, -0 if version1 == version2, and 1 if version1 > version2. Return None if -there was a problem making the comparison. +.B salt.modules.win_pkg.compare(pkg1=\(aq\(aq, oper=\(aq==\(aq, pkg2=\(aq\(aq) +Compare two version strings. .sp CLI Example: .sp .nf .ft C -salt \(aq*\(aq pkg.compare \(aq0.2.4\-0\(aq \(aq0.2.4.1\-0\(aq +salt \(aq*\(aq pkg.compare \(aq0.2.4\-0\(aq \(aq<\(aq \(aq0.2.4.1\-0\(aq +salt \(aq*\(aq pkg.compare pkg1=\(aq0.2.4\-0\(aq oper=\(aq<\(aq pkg2=\(aq0.2.4.1\-0\(aq .ft P .fi .UNINDENT @@ -24054,7 +26846,7 @@ salt \(aq*\(aq pkg.list_pkgs .UNINDENT .INDENT 0.0 .TP -.B salt.modules.win_pkg.list_upgrades() +.B salt.modules.win_pkg.list_upgrades(refresh=True) List all available package upgrades on this system .sp CLI Example: @@ -24067,7 +26859,23 @@ salt \(aq*\(aq pkg.list_upgrades .UNINDENT .INDENT 0.0 .TP -.B salt.modules.win_pkg.purge(name) +.B salt.modules.win_pkg.perform_cmp(pkg1=\(aq\(aq, pkg2=\(aq\(aq) +Do a cmp\-style comparison on two packages. Return \-1 if pkg1 < pkg2, 0 if +pkg1 == pkg2, and 1 if pkg1 > pkg2. Return None if there was a problem +making the comparison. +.sp +CLI Example: +.sp +.nf +.ft C +salt \(aq*\(aq pkg.perform_cmp \(aq0.2.4\-0\(aq \(aq0.2.4.1\-0\(aq +salt \(aq*\(aq pkg.perform_cmp pkg1=\(aq0.2.4\-0\(aq pkg2=\(aq0.2.4.1\-0\(aq +.ft P +.fi +.UNINDENT +.INDENT 0.0 +.TP +.B salt.modules.win_pkg.purge(name, **kwargs) Recursively remove a package and all dependencies which were installed with it .sp @@ -24102,7 +26910,7 @@ salt \(aq*\(aq pkg.refresh_db .UNINDENT .INDENT 0.0 .TP -.B salt.modules.win_pkg.remove(name, version=None) +.B salt.modules.win_pkg.remove(name, version=None, **kwargs) Remove a single package .sp Return a list containing the removed packages. @@ -24117,7 +26925,7 @@ salt \(aq*\(aq pkg.remove .UNINDENT .INDENT 0.0 .TP -.B salt.modules.win_pkg.upgrade() +.B salt.modules.win_pkg.upgrade(refresh=True) Run a full system upgrade .sp Return a dict containing the new package names and versions: @@ -24554,16 +27362,15 @@ salt \(aq*\(aq pkg.available_version ... .UNINDENT .INDENT 0.0 .TP -.B salt.modules.yumpkg5.compare(version1=\(aq\(aq, version2=\(aq\(aq) -Compare two version strings. Return \-1 if version1 < version2, -0 if version1 == version2, and 1 if version1 > version2. Return None if -there was a problem making the comparison. +.B salt.modules.yumpkg5.compare(pkg1=\(aq\(aq, oper=\(aq==\(aq, pkg2=\(aq\(aq) +Compare two version strings. .sp CLI Example: .sp .nf .ft C -salt \(aq*\(aq pkg.compare \(aq0.2.4\-0\(aq \(aq0.2.4.1\-0\(aq +salt \(aq*\(aq pkg.compare \(aq0.2.4\-0\(aq \(aq<\(aq \(aq0.2.4.1\-0\(aq +salt \(aq*\(aq pkg.compare pkg1=\(aq0.2.4\-0\(aq oper=\(aq<\(aq pkg2=\(aq0.2.4.1\-0\(aq .ft P .fi .UNINDENT @@ -24587,13 +27394,13 @@ salt \(aq*\(aq pkg.install .UNINDENT .TP .B refresh -Whether or not to clean the yum database before executing. +Whether or not to update the yum database before executing. .TP .B skip_verify Skip the GPG verification check (e.g., \fB\-\-nogpgcheck\fP) .TP .B version -Install a specific version of the package, e.g. 1.0.9. Ignored +Install a specific version of the package, e.g. 1.2.3\-4.el5. Ignored if "pkgs" or "sources" is passed. .UNINDENT .sp @@ -24618,11 +27425,14 @@ Multiple Package Installation Options: .TP .B pkgs A list of packages to install from a software repository. Must be -passed as a python list. +passed as a python list. A specific version number can be specified +by using a single\-element dict representing the package and its +version. .INDENT 7.0 .TP -.B CLI Example:: -salt \(aq*\(aq pkg.install pkgs=\(aq["foo","bar"]\(aq +.B CLI Examples:: +salt \(aq*\(aq pkg.install pkgs=\(aq["foo", "bar"]\(aq +salt \(aq*\(aq pkg.install pkgs=\(aq["foo", {"bar": "1.2.3\-4.el5"}]\(aq .UNINDENT .TP .B sources @@ -24666,7 +27476,7 @@ salt \(aq*\(aq pkg.list_pkgs .UNINDENT .INDENT 0.0 .TP -.B salt.modules.yumpkg5.list_upgrades() +.B salt.modules.yumpkg5.list_upgrades(refresh=True) Check whether or not an upgrade is available for all packages .sp CLI Example: @@ -24679,7 +27489,23 @@ salt \(aq*\(aq pkg.list_upgrades .UNINDENT .INDENT 0.0 .TP -.B salt.modules.yumpkg5.purge(pkg) +.B salt.modules.yumpkg5.perform_cmp(pkg1=\(aq\(aq, pkg2=\(aq\(aq) +Do a cmp\-style comparison on two packages. Return \-1 if pkg1 < pkg2, 0 if +pkg1 == pkg2, and 1 if pkg1 > pkg2. Return None if there was a problem +making the comparison. +.sp +CLI Example: +.sp +.nf +.ft C +salt \(aq*\(aq pkg.perform_cmp \(aq0.2.4\-0\(aq \(aq0.2.4.1\-0\(aq +salt \(aq*\(aq pkg.perform_cmp pkg1=\(aq0.2.4\-0\(aq pkg2=\(aq0.2.4.1\-0\(aq +.ft P +.fi +.UNINDENT +.INDENT 0.0 +.TP +.B salt.modules.yumpkg5.purge(pkg, **kwargs) Yum does not have a purge, this function calls remove .sp Return a list containing the removed packages: @@ -24708,7 +27534,7 @@ salt \(aq*\(aq pkg.refresh_db .UNINDENT .INDENT 0.0 .TP -.B salt.modules.yumpkg5.remove(pkg) +.B salt.modules.yumpkg5.remove(pkg, **kwargs) Remove a single package with yum remove .sp Return a list containing the removed packages: @@ -24723,7 +27549,7 @@ salt \(aq*\(aq pkg.remove .UNINDENT .INDENT 0.0 .TP -.B salt.modules.yumpkg5.upgrade() +.B salt.modules.yumpkg5.upgrade(refresh=True) Run a full system upgrade, a yum upgrade .sp Return a dict containing the new package names and versions: @@ -24823,16 +27649,15 @@ salt \(aq*\(aq pkg.clean_metadata .UNINDENT .INDENT 0.0 .TP -.B salt.modules.yumpkg.compare(version1=\(aq\(aq, version2=\(aq\(aq) -Compare two version strings. Return \-1 if version1 < version2, -0 if version1 == version2, and 1 if version1 > version2. Return None if -there was a problem making the comparison. +.B salt.modules.yumpkg.compare(pkg1=\(aq\(aq, oper=\(aq==\(aq, pkg2=\(aq\(aq) +Compare two version strings. .sp CLI Example: .sp .nf .ft C -salt \(aq*\(aq pkg.compare \(aq0.2.4\-0\(aq \(aq0.2.4.1\-0\(aq +salt \(aq*\(aq pkg.compare \(aq0.2.4\-0\(aq \(aq<\(aq \(aq0.2.4.1\-0\(aq +salt \(aq*\(aq pkg.compare pkg1=\(aq0.2.4\-0\(aq oper=\(aq<\(aq pkg2=\(aq0.2.4.1\-0\(aq .ft P .fi .UNINDENT @@ -24855,6 +27680,40 @@ salt \(aq*\(aq pkg.del_repo myrepo basedir=/path/to/dir .UNINDENT .INDENT 0.0 .TP +.B salt.modules.yumpkg.file_dict(*packages) +List the files that belong to a package, grouped by package. Not +specifying any packages will return a list of _every_ file on the system\(aqs +rpm database (not generally recommended). +.sp +CLI Examples: +.sp +.nf +.ft C +salt \(aq*\(aq pkg.file_list httpd +salt \(aq*\(aq pkg.file_list httpd postfix +salt \(aq*\(aq pkg.file_list +.ft P +.fi +.UNINDENT +.INDENT 0.0 +.TP +.B salt.modules.yumpkg.file_list(*packages) +List the files that belong to a package. Not specifying any packages will +return a list of _every_ file on the system\(aqs rpm database (not generally +recommended). +.sp +CLI Examples: +.sp +.nf +.ft C +salt \(aq*\(aq pkg.file_list httpd +salt \(aq*\(aq pkg.file_list httpd postfix +salt \(aq*\(aq pkg.file_list +.ft P +.fi +.UNINDENT +.INDENT 0.0 +.TP .B salt.modules.yumpkg.get_repo(repo, basedir=\(aq/etc/yum.repos.d\(aq) Display a repo from (default basedir: /etc/yum.repos.d). .sp @@ -24869,7 +27728,20 @@ salt \(aq*\(aq pkg.get_repo myrepo basedir=/path/to/dir .UNINDENT .INDENT 0.0 .TP -.B salt.modules.yumpkg.groupinfo(groupname) +.B salt.modules.yumpkg.group_diff(groupname) +Lists packages belonging to a certain group, and which are installed +.sp +CLI Example: +.sp +.nf +.ft C +salt \(aq*\(aq pkg.group_diff \(aqPerl Support\(aq +.ft P +.fi +.UNINDENT +.INDENT 0.0 +.TP +.B salt.modules.yumpkg.group_info(groupname) Lists packages belonging to a certain group .sp CLI Example: @@ -24882,14 +27754,71 @@ salt \(aq*\(aq pkg.groupinfo \(aqPerl Support\(aq .UNINDENT .INDENT 0.0 .TP -.B salt.modules.yumpkg.grouplist() +.B salt.modules.yumpkg.group_install(name=None, groups=None, skip=None, include=None, **kwargs) +Install the passed package group(s). This is basically a wrapper around +pkg.install, which performs package group resolution for the user. This +function is currently considered "experimental", and should be expected to +undergo changes before it becomes official. +.INDENT 7.0 +.TP +.B name +The name of a single package group to install. Note that this option is +ignored if "groups" is passed. +.TP +.B groups +The names of multiple packages which are to be installed. +.sp +CLI Example: +.sp +.nf +.ft C +salt \(aq*\(aq pkg.groupinstall groups=\(aq["Group 1", "Group 2"]\(aq +.ft P +.fi +.TP +.B skip +The name(s), in a list, of any packages that would normally be +installed by the package group ("default" packages), which should not +be installed. +.sp +CLI Examples: +.sp +.nf +.ft C +salt \(aq*\(aq pkg.groupinstall \(aqMy Group\(aq skip=\(aq["foo", "bar"]\(aq +.ft P +.fi +.TP +.B include +The name(s), in a list, of any packages which are included in a group, +which would not normally be installed ("optional" packages). Note that +this will nor enforce group membership; if you include packages which +are not members of the specified groups, they will still be installed. +.sp +CLI Examples: +.sp +.nf +.ft C +salt \(aq*\(aq pkg.groupinstall \(aqMy Group\(aq include=\(aq["foo", "bar"]\(aq +.ft P +.fi +.TP +.B other arguments +Because this is essentially a wrapper around pkg.install, any argument +which can be passed to pkg.install may also be included here, and it +will be passed along wholesale. +.UNINDENT +.UNINDENT +.INDENT 0.0 +.TP +.B salt.modules.yumpkg.group_list() Lists all groups known by yum on this system .sp CLI Example: .sp .nf .ft C -salt \(aq*\(aq pkg.grouplist +salt \(aq*\(aq pkg.group_list .ft P .fi .UNINDENT @@ -24913,13 +27842,13 @@ salt \(aq*\(aq pkg.install .UNINDENT .TP .B refresh -Whether or not to clean the yum database before executing. +Whether or not to update the yum database before executing. .TP .B skip_verify Skip the GPG verification check. (e.g., \fB\-\-nogpgcheck\fP) .TP .B version -Install a specific version of the package, e.g. 1.0.9. Ignored +Install a specific version of the package, e.g. 1.2.3\-4.el6. Ignored if "pkgs" or "sources" is passed. .UNINDENT .sp @@ -24944,11 +27873,14 @@ Multiple Package Installation Options: .TP .B pkgs A list of packages to install from a software repository. Must be -passed as a python list. +passed as a python list. A specific version number can be specified +by using a single\-element dict representing the package and its +version. .INDENT 7.0 .TP -.B CLI Example:: -salt \(aq*\(aq pkg.install pkgs=\(aq["foo","bar"]\(aq +.B CLI Examples:: +salt \(aq*\(aq pkg.install pkgs=\(aq["foo", "bar"]\(aq +salt \(aq*\(aq pkg.install pkgs=\(aq["foo", {"bar": "1.2.3\-4.el6"}]\(aq .UNINDENT .TP .B sources @@ -25005,7 +27937,7 @@ salt \(aq*\(aq pkg.list_repos .UNINDENT .INDENT 0.0 .TP -.B salt.modules.yumpkg.list_upgrades(*args) +.B salt.modules.yumpkg.list_upgrades(refresh=True) Check whether or not an upgrade is available for all packages .sp CLI Example: @@ -25046,7 +27978,23 @@ salt \(aq*\(aq pkg.mod_repo reponame baseurl= mirrorlist=http://host.com/ .UNINDENT .INDENT 0.0 .TP -.B salt.modules.yumpkg.purge(pkgs) +.B salt.modules.yumpkg.perform_cmp(pkg1=\(aq\(aq, pkg2=\(aq\(aq) +Do a cmp\-style comparison on two packages. Return \-1 if pkg1 < pkg2, 0 if +pkg1 == pkg2, and 1 if pkg1 > pkg2. Return None if there was a problem +making the comparison. +.sp +CLI Example: +.sp +.nf +.ft C +salt \(aq*\(aq pkg.perform_cmp \(aq0.2.4\-0\(aq \(aq0.2.4.1\-0\(aq +salt \(aq*\(aq pkg.perform_cmp pkg1=\(aq0.2.4\-0\(aq pkg2=\(aq0.2.4.1\-0\(aq +.ft P +.fi +.UNINDENT +.INDENT 0.0 +.TP +.B salt.modules.yumpkg.purge(pkgs, **kwargs) Yum does not have a purge, this function calls remove .sp Return a list containing the removed packages: @@ -25075,7 +28023,7 @@ salt \(aq*\(aq pkg.refresh_db .UNINDENT .INDENT 0.0 .TP -.B salt.modules.yumpkg.remove(pkgs) +.B salt.modules.yumpkg.remove(pkgs, **kwargs) Removes packages with yum remove .sp Return a list containing the removed packages: @@ -25090,7 +28038,7 @@ salt \(aq*\(aq pkg.remove .UNINDENT .INDENT 0.0 .TP -.B salt.modules.yumpkg.upgrade() +.B salt.modules.yumpkg.upgrade(refresh=True) Run a full system upgrade, a yum upgrade .sp Return a dict containing the new package names and versions: @@ -25290,16 +28238,15 @@ salt \(aq*\(aq pkg.available_version ... .UNINDENT .INDENT 0.0 .TP -.B salt.modules.zypper.compare(version1=\(aq\(aq, version2=\(aq\(aq) -Compare two version strings. Return \-1 if version1 < version2, -0 if version1 == version2, and 1 if version1 > version2. Return None if -there was a problem making the comparison. +.B salt.modules.zypper.compare(pkg1=\(aq\(aq, oper=\(aq==\(aq, pkg2=\(aq\(aq) +Compare two version strings. .sp CLI Example: .sp .nf .ft C -salt \(aq*\(aq pkg.compare \(aq0.2.4\-0\(aq \(aq0.2.4.1\-0\(aq +salt \(aq*\(aq pkg.compare \(aq0.2.4\-0\(aq \(aq<\(aq \(aq0.2.4.1\-0\(aq +salt \(aq*\(aq pkg.compare pkg1=\(aq0.2.4\-0\(aq oper=\(aq<\(aq pkg2=\(aq0.2.4.1\-0\(aq .ft P .fi .UNINDENT @@ -25324,6 +28271,11 @@ salt \(aq*\(aq pkg.install .TP .B refresh Whether or not to refresh the package database before installing. +.TP +.B version +Can be either a version number, or the combination of a comparison +operator (<, >, <=, >=, =) and a version number (ex. \(aq>1.2.3\-4\(aq). +This parameter is ignored if "pkgs" or "sources" is passed. .UNINDENT .sp Multiple Package Installation Options: @@ -25331,11 +28283,16 @@ Multiple Package Installation Options: .TP .B pkgs A list of packages to install from a software repository. Must be -passed as a python list. +passed as a python list. A specific version number can be specified +by using a single\-element dict representing the package and its +version. As with the \fBversion\fP parameter above, comparison operators +can be used to target a specific version of a package. .INDENT 7.0 .TP -.B CLI Example:: -salt \(aq*\(aq pkg.install pkgs=\(aq["foo","bar"]\(aq +.B CLI Examples:: +salt \(aq*\(aq pkg.install pkgs=\(aq["foo", "bar"]\(aq +salt \(aq*\(aq pkg.install pkgs=\(aq["foo", {"bar": "1.2.3\-4"}]\(aq +salt \(aq*\(aq pkg.install pkgs=\(aq["foo", {"bar": "<1.2.3\-4"}]\(aq .UNINDENT .TP .B sources @@ -25379,7 +28336,7 @@ salt \(aq*\(aq pkg.list_pkgs .UNINDENT .INDENT 0.0 .TP -.B salt.modules.zypper.list_upgrades() +.B salt.modules.zypper.list_upgrades(refresh=True) List all available package upgrades on this system .sp CLI Example: @@ -25392,7 +28349,23 @@ salt \(aq*\(aq pkg.list_upgrades .UNINDENT .INDENT 0.0 .TP -.B salt.modules.zypper.purge(name) +.B salt.modules.zypper.perform_cmp(pkg1=\(aq\(aq, pkg2=\(aq\(aq) +Do a cmp\-style comparison on two packages. Return \-1 if pkg1 < pkg2, 0 if +pkg1 == pkg2, and 1 if pkg1 > pkg2. Return None if there was a problem +making the comparison. +.sp +CLI Example: +.sp +.nf +.ft C +salt \(aq*\(aq pkg.perform_cmp \(aq0.2.4\-0\(aq \(aq0.2.4.1\-0\(aq +salt \(aq*\(aq pkg.perform_cmp pkg1=\(aq0.2.4\-0\(aq pkg2=\(aq0.2.4.1\-0\(aq +.ft P +.fi +.UNINDENT +.INDENT 0.0 +.TP +.B salt.modules.zypper.purge(name, **kwargs) Recursively remove a package and all dependencies which were installed with it, this will call a \fBzypper remove \-u\fP .sp @@ -25427,7 +28400,7 @@ salt \(aq*\(aq pkg.refresh_db .UNINDENT .INDENT 0.0 .TP -.B salt.modules.zypper.remove(name) +.B salt.modules.zypper.remove(name, **kwargs) Remove a single package with \fBzypper remove\fP .sp Return a list containing the removed packages. @@ -25442,7 +28415,7 @@ salt \(aq*\(aq pkg.remove .UNINDENT .INDENT 0.0 .TP -.B salt.modules.zypper.upgrade() +.B salt.modules.zypper.upgrade(refresh=True) Run a full system upgrade, a zypper upgrade .sp Return a dict containing the new package names and versions: @@ -25870,6 +28843,20 @@ Save the load to the specified jid id .SS salt.returners.postgres .sp Return data to a postgresql server +.INDENT 0.0 +.TP +.B maintainer +None +.TP +.B maturity +New +.TP +.B depends +psycopg2 +.TP +.B platform +all +.UNINDENT .sp To enable this returner the minion will need the psycopg2 installed and the following values configured in the minion or master config: @@ -25906,32 +28893,20 @@ CREATE TABLE jids ( ); \-\- -\-\- Table structure for table \(aqreturns\(aq +\-\- Table structure for table \(aqsalt_returns\(aq \-\- -DROP TABLE IF EXISTS returns; -CREATE TABLE returns ( +DROP TABLE IF EXISTS salt_returns; +CREATE TABLE salt_returns ( fun text NOT NULL, jid varchar(20) NOT NULL, return text NOT NULL, id text NOT NULL, success boolean ); -CREATE INDEX ON returns (id); -CREATE INDEX ON returns (jid); -CREATE INDEX ON returns (fun); - -DROP TABLE IF EXISTS highstate; -\-\- CREATE TABLE highstate ( -\-\- jid bigint PRIMARY KEY, -\-\- resource text NOT NULL, -\-\- return hstore -\-\- ); -CREATE INDEX return_idx_gist - ON highstate - USING gist - (return); -EOF +CREATE INDEX ON salt_returns (id); +CREATE INDEX ON salt_returns (jid); +CREATE INDEX ON salt_returns (fun); .ft P .fi .sp @@ -27147,7 +30122,7 @@ all: .ft P .fi .sp -The above defined over state will execute the msql stage first because it is +The above defined over state will execute the mysql stage first because it is required by the webservers stage. The webservers stage will then be executed only if the mysql stage executes without any issues. The webservers stage will execute state.highstate on the matched minions, while the mysql stage @@ -27698,7 +30673,7 @@ state. .sp State Modules are the components that map to actual enforcement and management of Salt states. -.SS States are \- Easy to Write! +.SS States are Easy to Write! .sp State Modules should be easy to write and straightforward. The information passed to the SLS data structures will map directly to the states modules. @@ -27729,8 +30704,8 @@ directly define the user interface. Place your custom state modules inside a \fB_states\fP directory within the \fBfile_roots\fP specified by the master config file. These custom state modules can then be distributed in a number of ways. Custom state modules -are distributed when \fI\%state.highstate\fP is run, or by executing the -\fI\%saltutil.sync_states\fP or \fI\%saltutil.sync_all\fP functions. +are distributed when \fBstate.highstate\fP is +run, or by executing the \fBsaltutil.sync_states\fP or \fBsaltutil.sync_all\fP functions. .SS Cross Calling Modules .sp As with Execution Modules, State Modules can also make use of the \fB__salt__\fP @@ -28039,6 +31014,12 @@ Management of PostgreSQL users (roles). T} _ T{ +\fBpostgres_group\fP +T} T{ +Management of PostgreSQL groups (roles). +T} +_ +T{ \fBrabbitmq_user\fP T} T{ Manage RabbitMQ Users. @@ -28303,7 +31284,7 @@ echo "Working hard..." # writing the state line echo # an empty line here so the next line will be the last. -echo "changed=yes comment='something has changed' whatever=123" +echo "changed=yes comment=\(aqsomething has changed\(aq whatever=123" .ft P .fi .sp @@ -28351,7 +31332,35 @@ my\-project: .fi .INDENT 0.0 .TP -.B salt.states.cmd.call(name, func, args=(), kws=None, onlyif=None, unless=None, stateful=False, **kwargs) +.B salt.states.cmd.call(name, func, args=(), kws=None, onlyif=None, unless=None, **kwargs) +Invoke a pre\-defined Python function with arguments specified in the state +declaration. This function is mainly used by the \fBsalt.renderers.pydsl\fP +renderer. +.sp +The intepretation of \fIonlyif\fP and \fIunless\fP arguments are identical to those +of \fBsalt.states.cmd.run()\fP, and all other arguments(\fIcwd\fP, \fIrunas\fP, ...) +allowed by \fIcmd.run\fP are allowed here, except that their effects apply only +to the commands specified in \fIonlyif\fP and \fIunless\fP rather than to the function +to be invoked. +.sp +In addition the \fIstateful\fP argument has no effects here. +.sp +The return value of the invoked function will be interpreted as follows. +.sp +If it\(aqs a dictionary then it will be passed through to the state system, which +expects it to have the usual structure returned by any salt state function. +.sp +Otherwise, the return value(denoted as \fBresult\fP in the code below) is +expected to be a JSON serializable object, and this dictionary is returned: +.sp +.nf +.ft C +{ \(aqchanges\(aq: { \(aqretval\(aq: result }, + \(aqresult\(aq: True if result is None else bool(result), + \(aqcomment\(aq: result if isinstance(result, basestring) else \(aq\(aq +} +.ft P +.fi .UNINDENT .INDENT 0.0 .TP @@ -28488,6 +31497,10 @@ a state .UNINDENT .INDENT 0.0 .TP +.B salt.states.cmd.wait_call(name, func, args=(), kws=None, onlyif=None, unless=None, stateful=False, **kwargs) +.UNINDENT +.INDENT 0.0 +.TP .B salt.states.cmd.wait_script(name, source=None, template=None, onlyif=None, unless=None, cwd=\(aq/root\(aq, user=None, group=None, shell=None, env=None, stateful=False, **kwargs) Download a script from a remote source and execute it only if a watch statement calls it. @@ -29062,8 +32075,14 @@ The file can contain checksums for several files, in this case every line must consist of full name of the file and checksum separated by space: .sp +Example: +.sp +.nf +.ft C /etc/rc.conf md5=ef6e82e4006dee563d98ada2a2a80a27 /etc/resolv.conf sha256=c8525aee419eb649f0233be91c151178b30f0dff8ebbdcc8de71b1d5c8bcc06a +.ft P +.fi .TP .B user The user to own the file, this defaults to the user salt is running as @@ -29444,7 +32463,7 @@ https://github.com/saltstack/salt.git: .fi .INDENT 0.0 .TP -.B salt.states.git.latest(name, rev=None, target=None, runas=None, force=None, submodules=False) +.B salt.states.git.latest(name, rev=None, target=None, runas=None, force=None, submodules=False, mirror=False, bare=False) Make sure the repository is cloned to the given directory and is up to date .INDENT 7.0 .TP @@ -29466,6 +32485,14 @@ Force git to clone into pre\-existing directories (deletes contents) .TP .B submodules Update submodules on clone or branch change (Default: False) +.TP +.B mirror +True if the repository is to be a mirror of the remote repository. +This implies bare, and thus is incompatible with rev. +.TP +.B bare +True if the repository is to be a bare clone of the remote repository. +This is incompatible with rev, as nothing will be checked out. .UNINDENT .UNINDENT .INDENT 0.0 @@ -29675,22 +32702,31 @@ pcspkr: .fi .INDENT 0.0 .TP -.B salt.states.kmod.absent(name) +.B salt.states.kmod.absent(name, persist=False, comment=True) Verify that the named kernel module is not loaded .INDENT 7.0 .TP .B name The name of the kernel module to verify is not loaded +.TP +.B persist +Delete module from /etc/modules +.TP +.B comment +Don\(aqt remove module from /etc/modules, only comment it .UNINDENT .UNINDENT .INDENT 0.0 .TP -.B salt.states.kmod.present(name) +.B salt.states.kmod.present(name, persist=False) Ensure that the specified kernel module is loaded .INDENT 7.0 .TP .B name The name of the kernel module to verify is loaded +.TP +.B persist +Also add module to /etc/modules .UNINDENT .UNINDENT .SS salt.states.layman @@ -30377,8 +33413,7 @@ A state module to manage system installed python packages .nf .ft C virtualenvwrapper: - pip.installed: - \- version: 3.0.1 + pip.installed .ft P .fi .INDENT 0.0 @@ -30471,7 +33506,13 @@ Skip the GPG verification check for the package to be installed .TP .B version Install a specific version of a package. This option is ignored if -either "pkgs" or "sources" is used. +either "pkgs" or "sources" is used. Currently, this option is supported +for the following pkg providers: \fBapt\fP, +\fBebuild\fP, +\fBpacman\fP, +\fByumpkg\fP, +\fByumpkg5\fP, and +\fBzypper\fP. .UNINDENT .sp Usage: @@ -30486,7 +33527,7 @@ httpd: .ft P .fi .sp -Multiple Package Installation Options: (not supported in Windows) +Multiple Package Installation Options: (not supported in Windows or pkgng) .INDENT 7.0 .TP .B pkgs @@ -30505,6 +33546,44 @@ mypkgs: \- baz .ft P .fi +.sp +\fBNOTE:\fP For \fBapt\fP, +\fBebuild\fP, +\fBpacman\fP, \fByumpkg\fP, +\fByumpkg5\fP, +and \fBzypper\fP, version numbers can be specified +in the \fBpkgs\fP argument. Example: +.sp +.nf +.ft C +mypkgs: + pkg.installed: + \- pkgs: + \- foo + \- bar: 1.2.3\-4 + \- baz +.ft P +.fi +.sp +Additionally, \fBebuild\fP, +\fBpacman\fP and +\fBzypper\fP support the \fB<\fP, \fB<=\fP, \fB>=\fP, and +\fB>\fP operators for more control over what versions will be installed. +Example: +.sp +.nf +.ft C +mypkgs: + pkg.installed: + \- pkgs: + \- foo + \- bar: \(aq>=1.2.3\-4\(aq + \- baz +.ft P +.fi +.sp +\fBNOTE:\fP When using comparison operators, the expression must be enclosed +in quotes to avoid a YAML render error. .INDENT 7.0 .TP .B sources @@ -30531,9 +33610,10 @@ mypkgs: .B salt.states.pkg.latest(name, refresh=False, fromrepo=None, skip_verify=False, pkgs=None, **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 \fBinstalled\fP function to be -used, as \fBlatest\fP will update 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 @@ -30572,7 +33652,7 @@ mypkgs: .UNINDENT .INDENT 0.0 .TP -.B salt.states.pkg.purged(name) +.B salt.states.pkg.purged(name, **kwargs) Verify that the package is purged, this will call the purge function in the salt pkg module for the platform. .INDENT 7.0 @@ -30583,7 +33663,7 @@ The name of the package to be purged .UNINDENT .INDENT 0.0 .TP -.B salt.states.pkg.removed(name) +.B salt.states.pkg.removed(name, **kwargs) Verify that the package is removed, this will remove the package via the remove function in the salt pkg module for the platform. .INDENT 7.0 @@ -30655,6 +33735,61 @@ Sometimes you want to supply additional information, but not as enabled configuration. Anything supplied for this list will be saved in the repo configuration with a comment marker (#) in front. .UNINDENT +.sp +Additional configuration values, such as gpgkey or gpgcheck, are used +verbatim to update the options for the yum repo in question. +.sp +For apt\-based systems, take note of the following configuration values: +.INDENT 7.0 +.TP +.B name: +on apt\-based systems this must be the complete entry as it would be +seen in the sources.list file. This can have a limited subset of +components (i.e. \(aqmain\(aq) which can be added/modified with the +"comps" option. +.INDENT 7.0 +.INDENT 3.5 +EXAMPLE: deb \fI\%http://us.archive.ubuntu.com/ubuntu/\fP precise main +.UNINDENT +.UNINDENT +.TP +.B disabled +On apt\-based systems, disabled toggles whether or not the repo is +used for resolving dependancies and/or installing packages +.TP +.B comps +On apt\-based systems, comps dictate the types of packages to be +installed from the repository (e.g. main, nonfree, ...). For +purposes of this, comps should be a comma\-separated list. +.TP +.B file +The filename for the .list that the repository is configured in. +It is important to include the full\-path AND make sure it is in +a directory that APT will look in when handling packages +.TP +.B dist +This dictates the release of the distro the packages should be built +for. (e.g. unstable) +.TP +.B keyid +The KeyID of the GPG key to install. This option also requires +the \(aqkeyserver\(aq option to be set. +.TP +.B keyserver +This is the name of the keyserver to retrieve gpg keys from. The +keyid option must also be set for this option to work. +.TP +.B key_url +A web url to retreive the GPG key from. +.TP +.B consolidate: +If set to true, this will consolidate all sources definitions to +the sources.list file, cleanup the now unused files, consolidate +components (e.g. main) for the same uri, type, and architecture +to a single line, and finally remove comments from the sources.list +file. The consolidate will run every time the state is processed. The +option only needs to be set on one repo managed by salt to take effect. +.UNINDENT .UNINDENT .SS salt.states.postgres_database .SS Management of PostgreSQL databases. @@ -30742,7 +33877,7 @@ System user all operation should be preformed on behalf of .UNINDENT .INDENT 0.0 .TP -.B salt.states.postgres_user.present(name, createdb=False, createuser=False, encrypted=False, superuser=False, replication=False, password=None, runas=None) +.B salt.states.postgres_user.present(name, createdb=False, createuser=False, encrypted=False, superuser=False, replication=False, password=None, groups=None, runas=None) Ensure that the named user is present with the specified privileges .INDENT 7.0 .TP @@ -30767,6 +33902,67 @@ Should the new user be allowed to initiate streaming replication .B password The user\(aqs pasword .TP +.B groups +A string of comma seperated groups the user should be in +.TP +.B runas +System user all operation should be preformed on behalf of +.UNINDENT +.UNINDENT +.SS salt.states.postgres_group +.SS Management of PostgreSQL groups (roles). +.sp +The postgres_group module is used to create and manage Postgres groups. +.sp +.nf +.ft C +frank: + postgres_group.present +.ft P +.fi +.INDENT 0.0 +.TP +.B salt.states.postgres_group.absent(name, runas=None) +Ensure that the named group is absent +.INDENT 7.0 +.TP +.B name +The groupname of the group to remove +.TP +.B runas +System user all operation should be preformed on behalf of +.UNINDENT +.UNINDENT +.INDENT 0.0 +.TP +.B salt.states.postgres_group.present(name, createdb=False, createuser=False, encrypted=False, superuser=False, replication=False, password=None, groups=None, runas=None) +Ensure that the named group is present with the specified privileges +.INDENT 7.0 +.TP +.B name +The name of the group to manage +.TP +.B createdb +Is the group allowed to create databases? +.TP +.B createuser +Is the group allowed to create other users? +.TP +.B encrypted +Should the password be encrypted in the system catalog? +.TP +.B superuser +Should the new group be a "superuser" +.TP +.B replication +Should the new group be allowed to initiate streaming replication +.TP +.B password +The group\(aqs pasword +.TP +.B groups +A string of comma seperated groups the group should be in +.TP .B runas System user all operation should be preformed on behalf of .UNINDENT @@ -31236,7 +34432,7 @@ The ssh key to manage 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 +Defines what type of key is being used, can be ecdsa ssh\-rsa, ssh\-dss .TP .B comment The comment to be placed with the ssh public key @@ -31294,6 +34490,10 @@ directory, defaults to ".ssh/known_hosts" .TP .B salt.states.ssh_known_hosts.present(name, user, fingerprint=None, port=None, enc=None, config=\(aq.ssh/known_hosts\(aq, hash_hostname=True) Verifies that the specified host is known by the specified user +.sp +On many systems, specifically those running with openssh 4 or older, the +\fBenc\fP option must be set, only openssh 5 and above can detect the key +type. .INDENT 7.0 .TP .B name @@ -31471,14 +34671,14 @@ The timezone can be managed for the system: .nf .ft C America/Denver: - timezone.system - utc: True + timezone.system: + \- utc: True .ft P .fi .INDENT 0.0 .TP .B salt.states.timezone.system(name, utc=\(aq\(aq) -Set the timezone for the system +Set the timezone for the system. .INDENT 7.0 .TP .B name @@ -31611,7 +34811,7 @@ The user\(aqs home phone number .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) +.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, index_url=None, extra_index_url=None) Create a virtualenv and optionally manage it with pip .INDENT 7.0 .TP @@ -31794,8 +34994,23 @@ Pure python state renderer T} _ T{ +\fBpydsl\fP +T} T{ +.INDENT 0.0 +.TP +.B maintainer +Jack Kuan <\fI\%kjkuan@gmail.com\fP> +.UNINDENT +T} +_ +T{ \fBstateconf\fP T} T{ +.INDENT 0.0 +.TP +.B maintainer +Jack Kuan <\fI\%kjkuan@gmail.com\fP> +.UNINDENT T} _ T{ @@ -31810,6 +35025,173 @@ T} _ .TE .SS salt.renderers.jinja +.SS Jinja in States +.sp +The most basic usage of Jinja in state files is using control structures to wrap +conditional or redundant state elements: +.sp +.nf +.ft C +{% if grains[\(aqos\(aq] != \(aqFreeBSD\(aq %} +tcsh: + pkg: + \- installed +{% endif %} + +motd: + file.managed: + {% if grains[\(aqos\(aq] == \(aqFreeBSD\(aq %} + \- name: /etc/motd + {% elif grains[\(aqos\(aq] == \(aqDebian\(aq %} + \- name: /etc/motd.tail + {% endif %} + \- source: salt://motd +.ft P +.fi +.sp +In this example, the first if block will only be evaluated on minions that +aren\(aqt running FreeBSD, and the second block changes the file name based on the +\fIos\fP grain. +.sp +Writing \fBif\-else\fP blocks can lead to very redundant state files however. In +this case, using \fBpillars\fP, or using a previously +defined variable might be easier: +.sp +.nf +.ft C +{% set motd = [\(aq/etc/motd\(aq] %} +{% if grains[\(aqos\(aq] == \(aqDebian\(aq %} + {% set motd = [\(aq/etc/motd.tail\(aq, \(aq/var/run/motd\(aq] %} +{% endif %} + +{% for motdfile in motd %} +{{ motdfile }}: + file.managed: + \- source: salt://motd +{% endfor %} +.ft P +.fi +.sp +Using a variable set by the template, the \fI\%for loop\fP will iterate over the +list of MOTD files to update, adding a state block for each file. +.SS Passing Variables +.sp +It is also possible to pass additional variable context directly into a +template, using the \fBdefaults\fP and \fBcontext\fP mappings of the +\fBfile.managed\fP state: +.sp +.nf +.ft C +/etc/motd: + file.managed: + \- source: salt://motd + \- template: jinja + \- defaults: + message: \(aqFoo\(aq + {% if grains[\(aqos\(aq] == \(aqFreeBSD\(aq %} + \- context: + message: \(aqBar\(aq + {% endif %} +.ft P +.fi +.sp +The template will receive a variable \fBmessage\fP, which would be accessed in the +template using \fB{{ message }}\fP. If the operating system is FreeBSD, the value +of the variable \fBmessage\fP would be \fIBar\fP, otherwise it is the default +\fIFoo\fP +.SS Include and Import +.sp +Includes and \fI\%imports\fP can be used to share common, reusable state configuration +between state files and between files. +.sp +.nf +.ft C +{% from \(aqlib.sls\(aq import test %} +.ft P +.fi +.sp +This would import the \fBtest\fP template variable or macro, not the \fBtest\fP +state element, from the file \fBlib.sls\fP. In the case that the included file +performs checks again grains, or something else that requires context, passing +the context into the included file is required: +.sp +.nf +.ft C +{% from \(aqlib.sls\(aq import test with context %} +.ft P +.fi +.SS Macros +.sp +\fI\%Macros\fP are helpful for eliminating redundant code, however stripping whitespace +from the template block, as well as contained blocks, may be necessary to +emulate a variable return from the macro. +.sp +.nf +.ft C +# init.sls +{% from \(aqlib.sls\(aq import pythonpkg with context %} + +python\-virtualenv: + pkg.installed: + \- name: {{ pythonpkg(\(aqvirtualenv\(aq) }} + +python\-fabric: + pkg.installed: + \- name: {{ pythonpkg(\(aqfabric\(aq) }} +.ft P +.fi +.sp +.nf +.ft C +# lib.sls +{% macro pythonpkg(pkg) \-%} + {%\- if grains[\(aqos\(aq] == \(aqFreeBSD\(aq \-%} + py27\-{{ pkg }} + {%\- elif grains[\(aqos\(aq] == \(aqDebian\(aq \-%} + python\-{{ pkg }} + {%\- endif \-%} +{%\- endmacro %} +.ft P +.fi +.sp +This would define a \fI\%macro\fP that would return a string of the full package name, +depending on the packaging system\(aqs naming convention. The whitespace of the +macro was eliminated, so that the macro would return a string without line +breaks, using \fI\%whitespace control\fP. +.SS Jinja in Files +.sp +\fI\%Jinja\fP can be used in the same way in managed files: +.sp +.nf +.ft C +# redis.sls +/etc/redis/redis.conf: + file.managed: + \- source: salt://redis.conf + \- template: jinja + \- context: + bind: 127.0.0.1 +.ft P +.fi +.sp +.nf +.ft C +# lib.sls +{% set port = 6379 %} +.ft P +.fi +.sp +.nf +.ft C +# redis.conf +{% from \(aqlib.sls\(aq import port with context %} +port {{ port }} +bind {{ bind }} +.ft P +.fi +.sp +As an example, configuration was pulled from the file context and from an +external template file. .INDENT 0.0 .TP .B salt.renderers.jinja.render(template_file, env=\(aq\(aq, sls=\(aq\(aq, argline=\(aq\(aq, context=None, tmplpath=None, **kws) @@ -31861,7 +35243,377 @@ Render the python module\(aqs components string .UNINDENT .UNINDENT +.SS salt.renderers.pydsl +.INDENT 0.0 +.TP +.B maintainer +Jack Kuan <\fI\%kjkuan@gmail.com\fP> +.TP +.B maturity +new +.TP +.B platform +all +.UNINDENT +.sp +The \fIpydsl\fP renderer allows one to author salt formulas(.sls files) in pure +Python using a DSL that\(aqs easy to write and easy to read. Here\(aqs an example: +.sp +.nf +.ft C + #!pydsl + + apache = state(\(aqapache\(aq) + apache.pkg.installed() + apache.service.running() + state(\(aq/var/www/index.html\(aq) \e + .file(\(aqmanaged\(aq, + source=\(aqsalt://webserver/index.html\(aq) \e + .require(pkg=\(aqapache\(aq) +.ft P +.fi +.sp +Notice that any Python code is allow in the file as it\(aqs really a Python +module, so you have the full power of Python at your disposal. In this module, +a few objects are defined for you, including the usual(with \fB__\fP added) +\fB__salt__\fP dictionary, \fB__grains__\fP, \fB__pillar__\fP, \fB__opts__\fP, +\fB__env__\fP, and \fB__sls__\fP, plus a few more: +.INDENT 0.0 +.INDENT 3.5 +\fB__file__\fP +.INDENT 0.0 +.INDENT 3.5 +local file system path to the sls module. +.UNINDENT +.UNINDENT +.sp +\fB__pydsl__\fP +.INDENT 0.0 +.INDENT 3.5 +Salt PyDSL object, useful for configuring DSL behavior per sls rendering. +.UNINDENT +.UNINDENT +.sp +\fBinclude\fP +.INDENT 0.0 +.INDENT 3.5 +Salt PyDSL function for creating \fIinclude declaration\fP\(aqs. +.UNINDENT +.UNINDENT +.sp +\fBextend\fP +.INDENT 0.0 +.INDENT 3.5 +Salt PyDSL function for creating \fIextend declaration\fP\(aqs. +.UNINDENT +.UNINDENT +.sp +\fBstate\fP +.INDENT 0.0 +.INDENT 3.5 +Salt PyDSL function for creating \fIID declaration\fP\(aqs. +.UNINDENT +.UNINDENT +.UNINDENT +.UNINDENT +.sp +A state \fIID declaration\fP is created with a \fBstate(id)\fP function call. +Subsequent \fBstate(id)\fP call with the same id returns the same object. This +singleton access pattern applys to all declaration objects created with the DSL. +.sp +.nf +.ft C +state(\(aqexample\(aq) +assert state(\(aqexample\(aq) is state(\(aqexample\(aq) +assert state(\(aqexample\(aq).cmd is state(\(aqexample\(aq).cmd +assert state(\(aqexample\(aq).cmd.running is state(\(aqexample\(aq).cmd.running +.ft P +.fi +.sp +The \fIid\fP argument is optional. If ommitted, an UUID will be generated and used as +the \fIid\fP. +.sp +\fBstate(id)\fP returns an object under which you can create a \fIstate declaration\fP +object by accessing an attribute named after \fIany\fP state module available in Salt. +.sp +.nf +.ft C +state(\(aqexample\(aq).cmd +state(\(aqexample\(aq).file +state(\(aqexample\(aq).pkg +\&... +.ft P +.fi +.sp +Then, a \fIfunction declaration\fP object can be created from a +\fIstate declaration\fP object by one of the following two ways: +.INDENT 0.0 +.IP 1. 3 +by directly calling the attribute named for the \fIstate declaration\fP, and +supplying the state function name as the first argument. +.UNINDENT +.sp +.nf +.ft C +state(\(aqexample\(aq).file(\(aqmanaged\(aq, ...) +.ft P +.fi +.INDENT 0.0 +.IP 2. 3 +by calling a method named after the state function on the \fIstate declaration\fP +object. +.UNINDENT +.sp +.nf +.ft C +state(\(aqexample\(aq).file.managed(...) +.ft P +.fi +.sp +With either way of creating a \fIfunction declaration\fP object, any +\fIfunction arg declaration\fP\(aqs can be passed as keyword arguments to the call. +Subsequent calls of a \fIfunction declaration\fP will update the arg declarations. +.sp +.nf +.ft C +state(\(aqexample\(aq).file(\(aqmanaged\(aq, source=\(aqsalt://webserver/index.html\(aq) +state(\(aqexample\(aq).file.managed(source=\(aqsalt://webserver/index.html\(aq) +.ft P +.fi +.sp +As a shortcut, the special \fIname\fP argument can also be passed as the first(second if +calling using the first way) positional argument. +.sp +.nf +.ft C +state(\(aqexample\(aq).cmd(\(aqrun\(aq, \(aqls \-la\(aq, cwd=\(aq/\(aq) +state(\(aqexample\(aq).cmd.run(\(aqls \-la\(aq, cwd=\(aq/\(aq) +.ft P +.fi +.sp +Finally, a \fIrequisite declaration\fP object with its \fIrequisite reference\fP\(aqs +can be created by invoking one of the requisite methods(\fBrequire\fP, \fBwatch\fP, \fBuse\fP, +\fBrequire_in\fP, \fBwatch_in\fP, and \fBuse_in\fP) on either a \fIfunction declaration\fP +object or a \fIstate declaration\fP object. The return value of a requisite call is +also a \fIfunction declaration\fP object, so you can chain several requisite calls +together. +.sp +Arguments to a requisite call can be a list of \fIstate declaration\fP objects and/or +a set of keyword arguments whose names are state modules and values are IDs of +\fIID declaration\fP\(aqs or names of \fIname declaration\fP\(aqs. +.sp +.nf +.ft C +apache2 = state(\(aqapache2\(aq) +apache2.pkg.installed() +state(\(aqlibapache2\-mod\-wsgi\(aq).pkg.installed() + +# you can call requisites on function declaration +apache2.service.running() \e + .require(apache2.pkg, + pkg=\(aqlibapache2\-mod\-wsgi\(aq) \e + .watch(file=\(aq/etc/apache2/httpd.conf\(aq) + +# or you can call requisites on state declaration. +# this actually creates an anonymous function declaration object +# to add the requisites. +apache2.service.require(state(\(aqlibapache2\-mod\-wsgi\(aq).pkg, + pkg=\(aqapache2\(aq) \e + .watch(file=\(aq/etc/apache2/httpd.conf\(aq) + +# we still need to set the name of the function declaration. +apache2.service.running() +.ft P +.fi +.sp +\fIinclude declaration\fP objects can be created with the \fBinclude\fP function, +while \fIextend declaration\fP objects can be created with the \fBextend\fP function, +whose arguments are just \fIfunction declaration\fP objects. +.sp +.nf +.ft C +include(\(aqedit.vim\(aq, \(aqhttp.server\(aq) +extend(state(\(aqapache2\(aq).service.watch(file=\(aq/etc/httpd/httpd.conf\(aq) +.ft P +.fi +.sp +The \fBinclude\fP function, by default, causes the included sls file to be rendered +as soon as the \fBinclude\fP function is called. It returns a list of rendered module +objects; sls files not rendered with the pydsl renderer return \fBNone\fP\(aqs. +This behavior creates no \fIinclude declaration\fP\(aqs in the resulting high state +data structure. +.sp +.nf +.ft C +import types + +# including multiple sls returns a list. +_, mod = include(\(aqa\-non\-pydsl\-sls\(aq, \(aqa\-pydsl\-sls\(aq) + +assert _ is None +assert isinstance(slsmods[1], types.ModuleType) + +# including a single sls returns a single object +mod = include(\(aqa\-pydsl\-sls\(aq) + +# myfunc is a function that calls state(...) to create more states. +mod.myfunc(1, 2, "three") +.ft P +.fi +.sp +Notice how you can define a reusable function in your pydsl sls module and then +call it via the module returned by \fBinclude\fP. +.sp +It\(aqs still possible to do late includes by passing the \fBdelayed=True\fP keyword +argument to \fBinclude\fP. +.sp +.nf +.ft C +include(\(aqedit.vim\(aq, \(aqhttp.server\(aq, delayed=True) +.ft P +.fi +.sp +Above will just create a \fIinclude declaration\fP in the rendered result, and +such call always returns \fBNone\fP. +.SS Special integration with the \fIcmd\fP state +.sp +Taking advantage of rendering a Python module, PyDSL allows you to declare a +state that calls a pre\-defined Python function when the state is executed. +.sp +.nf +.ft C +greeting = "hello world" +def helper(something, *args, **kws): + print greeting # hello world + print something, args, kws # test123 [\(aqa\(aq, \(aqb\(aq, \(aqc\(aq] {\(aqx\(aq: 1, \(aqy\(aq: 2} + +state().cmd.call(helper, "test123", \(aqa\(aq, \(aqb\(aq, \(aqc\(aq, x=1, y=2) +.ft P +.fi +.sp +The \fIcmd.call\fP state function takes care of calling our \fBhelper\fP function +with the arguments we specified in the states, and translates the return value +of our function into a structure expected by the state system. +See \fBsalt.states.cmd.call()\fP for more information. +.SS Implicit ordering of states +.sp +Salt states are explicitly ordered via \fIrequisite declaration\fP\(aqs. +However, with \fIpydsl\fP it\(aqs possible to let the renderer track the order +of creation for \fIfunction declaration\fP objects, and implicitly add +\fBrequire\fP requisites for your states to enforce the ordering. This feature +is enabled by setting the \fBordered\fP option on \fB__pydsl__\fP. +.IP Note +this feature is only available if your minions are using Python >= 2.7. +.RE +.sp +.nf +.ft C +include(\(aqsome.sls.file\(aq) + +A = state(\(aqA\(aq).cmd.run(cwd=\(aq/var/tmp\(aq) +extend(A) + +__pydsl__.set(ordered=True) + +for i in range(10): + i = str(i) + state(i).cmd.run(\(aqecho \(aq+i, cwd=\(aq/\(aq) +state(\(aq1\(aq).cmd.run(\(aqecho one\(aq) +state(\(aq2\(aq).cmd.run(name=\(aqecho two\(aq) +.ft P +.fi +.sp +Notice that the \fBordered\fP option needs to be set after any \fBextend\fP calls. +This is to prevent \fIpydsl\fP from tracking the creation of a state function that\(aqs +passed to an \fBextend\fP call. +.sp +Above example should create states from \fB0\fP to \fB9\fP that will output \fB0\fP, +\fBone\fP, \fBtwo\fP, \fB3\fP, ... \fB9\fP, in that order. +.sp +It\(aqs important to know that \fIpydsl\fP tracks the \fIcreations\fP of +\fIfunction declaration\fP objects, and automatically adds a \fBrequire\fP requisite +to a \fIfunction declaration\fP object that requires the last +\fIfunction declaration\fP object created before it in the sls file. +.sp +This means later calls(perhaps to update the function\(aqs \fIfunction arg declaration\fP) to a previously created function declaration will not change the order. +.SS Render time state execution +.sp +When Salt processes a salt formula file(\fI.sls\fP), the file is rendered to salt\(aqs +high state data representation by a renderer before the states can be executed. +In the case of the \fIpydsl\fP renderer, the .sls file is executed as a python module +as it is being rendered which makes it easy to execute a state at render time. +In \fIpydsl\fP, executing one or more states at render time can be done by calling a +configured \fIID declaration\fP object. +.sp +.nf +.ft C +#!pydsl + +s = state() # save for later invocation + +# configure it +s.cmd.run(\(aqecho at render time\(aq, cwd=\(aq/\(aq) +s.file.managed(\(aqtarget.txt\(aq, source=\(aqsalt://source.txt\(aq) + +s() # execute the two states now +.ft P +.fi +.sp +Once an \fIID declaration\fP is called at render time it is detached from the +sls module as if it was never defined. +.IP Note +If \fIimplicit ordering\fP is enabled(ie, via \fB__pydsl__.set(ordered=True)\fP) then +the \fIfirst\fP invocation of a \fIID declaration\fP object must be done before a +new \fIfunction declaration\fP is created. +.RE +.SS Integration with the stateconf renderer +.sp +The \fBsalt.renderers.stateconf\fP renderer offers a few interesting features that +can be leveraged by the \fIpydsl\fP renderer. In particular, when using with the \fIpydsl\fP +renderer, we are interested in \fIstateconf\fP\(aqs sls namespacing feature(via dot\-prefixed +id declarations), as well as, the automatic \fIstart\fP and \fIgoal\fP states generation. +.sp +Now you can use \fIpydsl\fP with \fIstateconf\fP like this: +.sp +.nf +.ft C +#!pydsl|stateconf \-ps + +include(\(aqxxx\(aq, \(aqyyy\(aq) + +# ensure that states in xxx run BEFORE states in this file. +extend(state(\(aq.start\(aq).stateconf.require(stateconf=\(aqxxx::goal\(aq)) + +# ensure that states in yyy run AFTER states in this file. +extend(state(\(aq.goal\(aq).stateconf.require_in(stateconf=\(aqyyy::start\(aq)) + +__pydsl__.set(ordered=True) + +\&... +.ft P +.fi +.sp +\fB\-s\fP enables the generation of a stateconf \fIstart\fP state, and \fB\-p\fP lets us pipe +high state data rendered by \fIpydsl\fP to \fIstateconf\fP. This example shows that by +\fBrequire\fP\-ing or \fBrequire_in\fP\-ing the included sls\(aq \fIstart\fP or \fIgoal\fP states, +it\(aqs possible to ensure that the included sls files can be made to execute before +or after a state in the including sls file. +.INDENT 0.0 +.TP +.B salt.renderers.pydsl.render(template, env=\(aq\(aq, sls=\(aq\(aq, tmplpath=None, rendered_sls=None, **kws) +.UNINDENT .SS salt.renderers.stateconf +.INDENT 0.0 +.TP +.B maintainer +Jack Kuan <\fI\%kjkuan@gmail.com\fP> +.TP +.B maturity +new +.TP +.B platform +all +.UNINDENT .sp This module provides a custom renderer that process a salt file with a specified templating engine(eg, jinja) and a chosen data renderer(eg, yaml), @@ -32564,6 +36316,11 @@ Print a list of all the down or unresponsive salt minions .UNINDENT .INDENT 0.0 .TP +.B salt.runners.manage.status(output=True) +Print the status of all known salt minions +.UNINDENT +.INDENT 0.0 +.TP .B salt.runners.manage.up() Print a list of all of the minions that are up .UNINDENT @@ -32656,11 +36413,6 @@ center; |l|l|. _ T{ -\fBauth\fP -T} T{ -T} -_ -T{ \fBconfig\fP T} T{ Manage the master configuration file @@ -33859,8 +37611,8 @@ def get_file(path, dest, env=\(aqbase\(aq): # Values that are commented out but have no space after the comment are # defaults that need not be set in the config. If there is a space after the # comment that the value is presented as an example and is not the default. -# -# Per default the master will automatically include all config files + +# Per default, the master will automatically include all config files # from master.d/*.conf (master.d is a directory in the same directory # as the main master config file) #default_include: master.d/*.conf @@ -33988,11 +37740,10 @@ def get_file(path, dest, env=\(aqbase\(aq): # master or minion as root, but have a non\-root group be given access to # your pki_dir. To make the access explicit, root must belong to the group # you\(aqve given access to. This is potentially quite insecure. -# -# If an autosign_file is specified permissive access will allow group access +# If an autosign_file is specified, enabling permissive_pki_access will allow group access # to that specific file. #permissive_pki_access: False -# + # Allow users on the master access to execute specific commands on minions. # This setting should be treated with care since it opens up execution # capabilities to non root users. By default this capability is completely @@ -34003,6 +37754,21 @@ def get_file(path, dest, env=\(aqbase\(aq): # \- test.ping # \- network.* # + +# Blacklist any of the following users or modules +# +# This example would blacklist all non sudo users, including root from +# running any commands. It would also blacklist any use of the "cmd" +# module. +# This is completely disabled by default. +# +# client_acl_blacklist: +# users: +# \- root +# \- \(aq^(?!sudo_).*$\(aq # all non sudo users +# modules: +# \- cmd + # The external auth system uses the Salt auth modules to authenticate and # validate users to access areas of the Salt system # @@ -34014,16 +37780,17 @@ def get_file(path, dest, env=\(aqbase\(aq): # Time (in seconds) for a newly generated token to live. Default: 12 hours # token_expire: 43200 + ##### 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 ##### ########################################## @@ -34031,42 +37798,42 @@ def get_file(path, dest, env=\(aqbase\(aq): # use and what modules to use. The state_top file is defined relative to the # root of the base environment as defined in "File Server settings" below. #state_top: top.sls -# + # The master_tops option replaces the external_nodes option by creating # a plugable system for the generation of external top data. The external_nodes # option is deprecated by the master_tops option. -# To gain the capabilities of the classic external_nodes system use the -# following configuration -# +# To gain the capabilities of the classic external_nodes system, use the +# following configuration: # master_tops: # ext_nodes: # #master_tops: {} -# + # The external_nodes option allows Salt to gather data that would normally be # placed in a top file. The external_nodes option is the executable that will # return the ENC data. Remember that Salt will look for external nodes AND top # files and combine the results if both are enabled! #external_nodes: None -# + # The renderer to use on the minions to render the state data #renderer: yaml_jinja -# + # The failhard option tells the minions to stop immediately after the first # failure detected in the state execution, defaults to False #failhard: False -# + # The state_verbose and state_output settings can be used to change the way # state system data is printed to the display. By default all data is printed. # The state_verbose setting can be set to True or False, when set to False # all data that has a result of True and no changes will be suppressed. #state_verbose: True -# + # The state_output setting changes if the output is the full multi line # output for each changed state if set to \(aqfull\(aq, but if set to \(aqterse\(aq # the output will be shortened to a single line. #state_output: full + ##### File Server settings ##### ########################################## # Salt runs a lightweight file server written in zeromq to deliver files to @@ -34087,8 +37854,7 @@ def get_file(path, dest, env=\(aqbase\(aq): # prod: # \- /srv/salt/prod/services # \- /srv/salt/prod/states -# -# Default: + #file_roots: # base: # \- /srv/salt @@ -34107,67 +37873,66 @@ def get_file(path, dest, env=\(aqbase\(aq): # For example, if you manage your custom modules and states in subversion # and don\(aqt want all the \(aq.svn\(aq folders and content synced to your minions, # you could set this to \(aq/\e.svn($|/)\(aq. By default nothing is ignored. -#file_ignore_regex: -# \- \(aq/\e.svn($|/)\(aq -# \- \(aq/\e.git($|/)\(aq +# file_ignore_regex: +# \- \(aq/\e.svn($|/)\(aq +# \- \(aq/\e.git($|/)\(aq # A file glob (or list of file globs) that will be matched against the file # path before syncing the modules and states to the minions. This is similar # to file_ignore_regex above, but works on globs instead of regex. By default # nothing is ignored. -#file_ignore_glob: -# \- \(aq*.pyc\(aq -# \- \(aq*/somefolder/*.bak\(aq +# file_ignore_glob: +# \- \(aq*.pyc\(aq +# \- \(aq*/somefolder/*.bak\(aq # File Server Backend # Salt supports a modular fileserver backend system, this system allows # the salt master to link directly to third party systems to gather and # manage the files available to minions. Multiple backends can be # configured and will be searched for the requested file in the order in which -# they are defined here. The defult setting only enables the standard backend +# they are defined here. The default setting only enables the standard backend # "roots" which uses the "file_roots" option. -# To enable the git backend change the option to look like this: -# fileserver_backend: -# \- git +#fileserver_backend: +# \- roots # To use multiple backends list them in the order they are searched: # fileserver_backend: # \- git # \- roots -#fileserver_backend: -# \- roots -# + # Git fileserver backend configuration # When using the git fileserver backend at least one git remote needs to be # defined. The user running the salt master will need read access to the repo. # gitfs_remotes: # \- git://github.com/saltstack/salt\-states.git -# \- git://github.com/saltstack/prod\-states.git +# \- file:///var/git/saltmaster # The repos will be searched in order to find the file requested by a client # and the first repo to have the file will return it. # When using the git backend branches and tags are translated into salt # environments. -# Pillar Configurations: -# The Salt Pillar, is a system that allows for the building of global data -# that is refined based on minion. Basically, the pillar creates data that -# can be generated to be specific based on the grains of the minion. Pillar -# is laid out in the same fashion as the file server, with environments, a top -# file and sls files. The difference is that the data does not need to be -# in the highstate format, and is generally just key/value pairs. -# + +##### Pillar settings ##### +########################################## +# Salt Pillars allow for the building of global data that can be made selectively +# available to different minions based on minion grain filtering. The Salt +# Pillar is laid out in the same fashion as the file server, with environments, +# a top file and sls files. However, pillar data does not need to be in the +# highstate format, and is generally just key/value pairs. + #pillar_roots: # base: # \- /srv/pillar -# + # ext_pillar: # \- hiera: /etc/hiera.yaml # \- cmd_yaml: cat /etc/salt/yaml -# + # The pillar_opts option adds the master configuration file data to a dict in # the pillar called "master". This is used to set simple configurations in the # master config file that can then be used on minions. #pillar_opts: True + ##### Syndic settings ##### ########################################## # The Salt syndic is used to pass commands through a master from a higher @@ -34176,22 +37941,23 @@ def get_file(path, dest, env=\(aqbase\(aq): # 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 receive commands from. -# + # Set the order_masters setting to True if this master will command lower # masters\(aq syndic interfaces. #order_masters: False -# + # If this master will be running a salt syndic daemon, syndic_master tells # this master where to receive commands from. #syndic_master: masterofmaster + ##### Peer Publish settings ##### ########################################## # Salt minions can send commands to other minions, but only if the minion is # allowed to. By default "Peer Publication" is disabled, and when enabled it # is enabled for specific minions and specific commands. This allows secure # compartmentalization of commands based on individual minions. -# + # The configuration uses regular expressions to match minions and then a list # of regular expressions to match functions. The following will allow the # minion authenticated as foo.example.com to execute functions from the test @@ -34207,7 +37973,7 @@ def get_file(path, dest, env=\(aqbase\(aq): # \- .* # 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 @@ -34225,7 +37991,7 @@ def get_file(path, dest, env=\(aqbase\(aq): # peer_run: # foo.example.com: # \- manage.up -# + ##### Logging settings ##### ########################################## @@ -34237,30 +38003,28 @@ def get_file(path, dest, env=\(aqbase\(aq): # log_file: /var/log/salt/master # log_file: file:///dev/log # log_file: udp://loghost:10514 -# + #log_file: /var/log/salt/master #key_logfile: /var/log/salt/key -# + # The level of messages to send to the console. # One of \(aqgarbage\(aq, \(aqtrace\(aq, \(aqdebug\(aq, info\(aq, \(aqwarning\(aq, \(aqerror\(aq, \(aqcritical\(aq. -# Default: \(aqwarning\(aq #log_level: warning -# + # The level of messages to send to the log file. # One of \(aqgarbage\(aq, \(aqtrace\(aq, \(aqdebug\(aq, info\(aq, \(aqwarning\(aq, \(aqerror\(aq, \(aqcritical\(aq. -# Default: \(aqwarning\(aq -#log_level_logfile: +#log_level_logfile: warning # The date and time format used in log messages. Allowed date/time formating # can be seen here: http://docs.python.org/library/time.html#time.strftime #log_datefmt: \(aq%H:%M:%S\(aq #log_datefmt_logfile: \(aq%Y\-%m\-%d %H:%M:%S\(aq -# + # The format of the console logging messages. Allowed formatting options can # be seen here http://docs.python.org/library/logging.html#logrecord\-attributes #log_fmt_console: \(aq[%(levelname)\-8s] %(message)s\(aq #log_fmt_logfile: \(aq%(asctime)s,%(msecs)03.0f [%(name)\-17s][%(levelname)\-8s] %(message)s\(aq -# + # This can be used to control logging levels more specificically. This # example sets the main salt library at the \(aqwarning\(aq level, but sets # \(aqsalt.modules\(aq to log at the \(aqdebug\(aq level: @@ -34280,6 +38044,7 @@ def get_file(path, dest, env=\(aqbase\(aq): # group1: \(aqL@foo.domain.com,bar.domain.com,baz.domain.com and bl*.domain.com\(aq # group2: \(aqG@os:Debian and foo.domain.com\(aq + ##### Range Cluster settings ##### ########################################## # The range server (and optional port) that serves your cluster information @@ -34292,10 +38057,10 @@ def get_file(path, dest, env=\(aqbase\(aq): ############################################## # Location of the repo on the master # win_repo: \(aq/srv/salt/win/repo\(aq -# + # Location of the master\(aqs repo cache file # win_repo_mastercachefile: \(aq/srv/salt/win/repo/winrepo.p\(aq -# + # List of git repositories to include with the local repo # win_gitrepos: # \- \(aqhttps://github.com/saltstack/salt\-winrepo.git\(aq @@ -34510,11 +38275,11 @@ def get_file(path, dest, env=\(aqbase\(aq): # Run states when the minion daemon starts. To enable, set startup_states to: # \(aqhighstate\(aq \-\- Execute state.highstate # \(aqsls\(aq \-\- Read in the sls_list option and execute the named sls files -# \(aqtop\(aq \-\- Read top_file option and execute based on that file on the Master +# \(aqtop\(aq \-\- Read top_file option and execute based on that file on the Master #startup_states: \(aq\(aq # # list of states to run when the minion starts up if startup_states is \(aqsls\(aq -#sls_list: +#sls_list: # \- edit.vim # \- hyper # @@ -34636,7 +38401,7 @@ def get_file(path, dest, env=\(aqbase\(aq): #log_fmt_logfile: \(aq%(asctime)s,%(msecs)03.0f [%(name)\-17s][%(levelname)\-8s] %(message)s\(aq # # This can be used to control logging levels more specificically. This -# example sets the main salt library at the \(aqwarning\(aq level, but sets +# example sets the main salt library at the \(aqwarning\(aq level, but sets # \(aqsalt.modules\(aq to log at the \(aqdebug\(aq level: # log_granular_levels: # \(aqsalt\(aq: \(aqwarning\(aq, @@ -34687,12 +38452,12 @@ def get_file(path, dest, env=\(aqbase\(aq): # without informing either party that their connection has been taken away. # Enabling TCP Keepalives prevents this from happening. # -# Overall state of TCP Keepalives, enable (1 or True), disable (0 or False) +# Overall state of TCP Keepalives, enable (1 or True), disable (0 or False) # or leave to the OS defaults (\-1), on linux, typically disabled. Default True, enabled. #tcp_keepalive: True # # How long before the first keepalive should be sent in seconds. Default 300 -# to send the first keepalive after 5 minutes, OS default (\-1) is typically 7200 seconds +# to send the first keepalive after 5 minutes, OS default (\-1) is typically 7200 seconds # on Linux see /proc/sys/net/ipv4/tcp_keepalive_time. #tcp_keepalive_idle: 300 # @@ -34700,8 +38465,8 @@ def get_file(path, dest, env=\(aqbase\(aq): # to use OS defaults, typically 9 on Linux, see /proc/sys/net/ipv4/tcp_keepalive_probes. #tcp_keepalive_cnt: \-1 # -# How often, in seconds, to send keepalives after the first one. Default \-1 to -# use OS defaults, typically 75 seconds on Linux, see +# How often, in seconds, to send keepalives after the first one. Default \-1 to +# use OS defaults, typically 75 seconds on Linux, see # /proc/sys/net/ipv4/tcp_keepalive_intvl. #tcp_keepalive_intvl: \-1 @@ -34880,6 +38645,20 @@ 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 \fBext_job_cache\fP +.sp +Default: \(aq\(aq +.sp +Used to specify a default returner for all minions, when this option is set +the specified returner needs to be properly configured and the minions will +always default to sending returns to this returner. This will also disable the +local job cache on the master +.sp +.nf +.ft C +ext_job_cache: redis +.ft P +.fi .SS \fBsock_dir\fP .sp Default:: \fB/tmp/salt\-unix\fP @@ -36165,6 +39944,33 @@ Thrown when a salt master request call fails to return within the timeout This exception is raised when an unsolvable problem is found. There\(aqs nothing else to do, salt should just exit. .UNINDENT +.SH NETWORK TOPOLOGY +.sp +Salt is based on a powerful, asynchronous, network topology using ZeroMQ. Many +ZeroMQ systems are in place to enable communication. The central idea is to +have the fastest communication possible. +.SS Servers +.sp +The Salt Master runs 2 network services. First is the ZeroMQ PUB system. This +service by default runs on port \fB4505\fP and can be configured via the +\fBpublish_port\fP option in the master configuration. +.sp +Second is the ZeroMQ REP system. This is a seperate interface used for all +bi\-directional communication with minions. By default this system binds to +port \fB4506\fP and can be configured via the \fBret_port\fP option in the master. +.SS PUB/SUB +.sp +The commands sent out via the salt client are broadcast out to the minions via +ZeroMQ PUB/SUB. This is done by allowing the minions to maintain a connection +back to the Salt Master and then all connecions are informed to download the +command data at once. The command data is kept extreamly small (usually less +than 1K) so it is not a burden on the network. +.SS Return +.sp +The PUB/SUB system is a one way communication, so once a publish is sent out +the PUB interface on the master has no further communication with the minion. +The minion, after running the command, then sends the command\(aqs return data +back to the master via the \fBret_port\fP. .SH WINDOWS SOFTWARE REPOSITORY .sp The Salt Windows Software Repository provides a package manager and software @@ -36506,7 +40312,9 @@ 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. The +timeout number specifes how long the command line client will wait to +query the minions and check on running jobs. .UNINDENT .INDENT 0.0 .TP @@ -37216,93 +41024,6 @@ on most systems is /etc/salt. \fIsalt(1)\fP \fIsalt\-master(1)\fP \fIsalt\-minion(1)\fP -.SH ABSTRACT ON SALT AUTHENTICATION AND ENCRYPTION -.sp -The Salt authentication and encryption system uses Public Key authentication -and AES encryption to facilitate both authentication and high speed encryption. -.sp -The core components of this system can be separated into a few sections, -Message Formatting, PubKey Handshake, AES key management, and encryption. -.SS Message Formatting -.sp -All messages passed within Salt are formatted with a clear header and a "load". -The header is always clear, and specifies the encryption used by the load. The -load can be encrypted with the private key of the sending system, or with the -shared, rotating, AES key. -.sp -The message itself is abstracted as a Python dict in this fashion: -.sp -.nf -.ft C -{\(aqenc\(aq: \(aqaes\(aq, - \(aqload\(aq: } -.ft P -.fi -.sp -When this message is received the load can be decrypted using the shared AES -key. The \(aqenc\(aq dict key can also be "pub" for pubkey encryption, or "clear" -for passing messages in the clear. -.SS PubKey Handshake -.sp -RSA Public keys are generated on the Salt master and on the Salt minion. When -A salt minion establishes an initial connection to the salt master the minion -sends its public key in the clear to the salt master, along with the id of -the minion, and the command to execute on the master, in this case "_auth": -.sp -.nf -.ft C -{\(aqenc\(aq: \(aqclear\(aq, - \(aqload\(aq: - {\(aqcmd\(aq: \(aq_auth\(aq, - \(aqid\(aq: , - \(aqpub\(aq: }} -.ft P -.fi -.sp -If this is the first time this minion has authenticated, then the salt master -returns a clear message informing the minion that it is pending authentication. -The minion then queries the master every ten seconds awaiting authentication. -When the public key of the minion has been approved by the master, then the -master\(aqs public key is returned, with the AES key used to encrypt messages and -information on how to connect to the salt master publish interface. -.sp -The returned AES key is encrypted with the minion\(aqs public key, and can -therefore only be decrypted by the minion that sent out the public key. -.sp -Once the minion has authenticated and is in possession of the revolving master -AES key (The AES key is regenerated when the master restarts) then it attaches -the minion subscriber to the master publisher. -.sp -All messages sent from the publisher are encrypted using the revolving AES key, -in the event that the master restarts the minions will all have an invalid -AES key because it has been regenerated on the master. The master will then -send out a publication that the minions cannot decrypt. If the minion receives -a publication that cannot be decrypted then the minion will re\-authenticate, -obtain the correct AES key, and decrypt the message. This means that the -AES key on the salt master can safely revolve without interrupting the minion -connection. -.SS Regular Communication -.sp -Once the minion has authenticated, then all messages sent between the minion -and the master are encrypted using the revolving AES key and the {\(aqenc\(aq: \(aqaes\(aq} -header. -.SS Source Files Implimenting Components -.sp -The pubkey authentication is managed via the salt.master module: -\fI\%https://github.com/saltstack/salt/blob/develop/salt/master.py\fP -The regular minion authentication is managed via the salt.crypt module: -\fI\%https://github.com/saltstack/salt/blob/develop/salt/crypt.py\fP -The salt.crypt module contains a class "SAuth" that can be used for -standalone authentication with the Salt master, this is most likely the best -place to start when looking into how the authentication mechanism works -The encrypted "load" portion of the messages are encrypted and decrypted using -the Crypticle class in the crypt module. -.SS Conclusion -.sp -In the end Salt uses formatted messages with clear header data to specify how -the message data is encrypted. Asymetric encryption via RSA keys is only used -for authentication and to securely retrieve the master AES key. All further -communications are are encrypted with 256 bit AES. .SH RELEASE NOTES AND UPGRADE INSTRUCTIONS .SS Salt 0.10.0 Release Notes .sp @@ -38124,6 +41845,14 @@ schedule: minutes: 30 .ft P .fi +.SS Optional DSL for SLS Formulas +.sp +Jack Kuan, our renderer expert, has created something that is astonishing. +Salt, now comes with an optional Python based DSL, this is a very powerful +interface that makes writing SLS files in pure python easier than it was +with the raw py renderer. As usual this can be used with the renderer shebang +line, so a single sls can be written with the DSL if pure python power is +needed while keeping other sls files simple with YAML. .SS Set Grains Remotely .sp A new execution function and state module have been added that allows for @@ -38135,6 +41864,70 @@ functions. Major additions to Gentoo specific components have been made. The encompasses executions modules and states ranging from supporting the make.conf file to tools like layman. +.SS Salt 0.13.0 Release Notes +.sp +The lucky number 13 has turned the corner! From cli notifications when quitting +a salt command, to substantial improvements on Windows, Salt 0.13.0 has +arrived! +.SS Major Features +.SS Improved file.recuse Performance +.sp +The file.recurse system has been deployed and used in a vast array of +situations. Fixes to the file state and module have led towards opening up +new ways of running file.recurse to make it faster. Now the file.recurse +state will download fewer files and will run substantially faster. +.SS Windows Improvements +.sp +Minion stability on Windows has improved. Many file operations, including +file.recurse, have been fixed and improved. The network module works better, to +include network.interfaces. Both 32bit and 64bit installers are now available. +.SS Nodegroup Targeting in Peer System +.sp +In the past, nodegroups were not available for targeting via the peer system. +This has been fixed, allowing the new nodegroup expr_form argument for the +publish.publish function: +.INDENT 0.0 +.INDENT 3.5 +salt\-call publish.publish group1 test.ping expr_form=nodegroup +.UNINDENT +.UNINDENT +.SS Blacklist Additions +.sp +Additions allowing more granular blacklisting are available in 0.13.0. The +ability to blacklist users and functions in client_acl have been added, as +well as the ability to exclude state formulas from the command line. +.SS Command Line Pillar Embedding +.sp +Pillar data can now be embedded on the command line when calling \fBstate.sls\fP +and \fBstate.highstate\fP. This allows for on the fly changes or settings to +pillar and makes parameterizing state formulas even easier. This is done via +the keyword argument: +.INDENT 0.0 +.INDENT 3.5 +salt * state.highstate pillar=\(aq{"cheese": "spam"}\(aq +.UNINDENT +.UNINDENT +.sp +The above example will extend the existing pillar to hold the \fIcheese\fP key +with a value of \fIspam\fP. If the \fIcheese\fP key is already specified in the +minion\(aqs pillar then it will be overwritten. +.SS CLI Notifications +.sp +In the past hitting ctrl\-C and quitting from the \fBsalt\fP command would just +drop to a shell prompt, this caused confusion with users who expected the +remote executions to also quit. Now a message is displayed showing what +command can be used to track the execution and what the job id is for the +execution. +.SS Noteworthy Changes +.sp +The configuration subsystem in Salt has been overhauled to make the \fBopts\fP +dict used by Salt applications more portable, the problem is that this is an +incompatible change with salt\-cloud, and salt\-cloud will need to be updated +to the latest git to work with Salt 0.13.0. Salt Cloud 0.8.5 will also require +Salt 0.13.0 or later to function. +.sp +The Salt Stack team is sorry for the inconvenience here, we work hard to make +sure these sorts of things do not happen, but sometimes hard changes get in. .SS Salt 0.6.0 release notes .sp The Salt remote execution manager has reached initial functionality! Salt is a @@ -40469,5 +44262,4 @@ Thomas S. Hatch and many others, please see the Authors fil .SH COPYRIGHT 2013, Thomas S. Hatch .\" Generated by docutils manpage writer. -.\" .