.TH "SALT" "7" "February 12, 2013" "0.13.0" "Salt" .SH NAME salt \- Salt Documentation . .nr rst2man-indent-level 0 . .de1 rstReportMargin \\$1 \\n[an-margin] level \\n[rst2man-indent-level] level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] - \\n[rst2man-indent0] \\n[rst2man-indent1] \\n[rst2man-indent2] .. .de1 INDENT .\" .rstReportMargin pre: . RS \\$1 . nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin] . nr rst2man-indent-level +1 .\" .rstReportMargin post: .. .de UNINDENT . RE .\" indent \\n[an-margin] .\" old: \\n[rst2man-indent\\n[rst2man-indent-level]] .nr rst2man-indent-level -1 .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. .\" Man page generated from reStructuredText. . .SH INTRODUCTION TO SALT We’re not just talking about NaCl..SS The 30 second summary .sp Salt is: .INDENT 0.0 .IP \(bu 2 a configuration management system, capable of maintaining remote nodes in defined states (for example, ensuring that specific packages are installed and specific services are running) .IP \(bu 2 a distributed remote execution system used to execute commands and query data on remote nodes, either individually or by arbitrary selection criteria .UNINDENT .sp It was developed in order to bring the best solutions found in the world of remote execution together and make them better, faster, and more malleable. Salt accomplishes this through its ability to handle large loads of information, and not just dozens but hundreds and even thousands of individual servers quickly through a simple and manageable interface. .SS Simplicity .sp Providing versatility between massive scale deployments and smaller systems may seem daunting, but Salt is very simple to set up and maintain, regardless of the size of the project. The architecture of Salt is designed to work with any number of servers, from a handful of local network systems to international deployments across different datacenters. The topology is a simple server/client model with the needed functionality built into a single set of daemons. While the default configuration will work with little to no modification, Salt can be fine tuned to meet specific needs. .SS Parallel execution .sp The core functions of Salt: .INDENT 0.0 .IP \(bu 2 enable commands to remote systems to be called in parallel rather than serially .IP \(bu 2 use a secure and encrypted protocol .IP \(bu 2 use the smallest and fastest network payloads possible .IP \(bu 2 provide a simple programming interface .UNINDENT .sp Salt also introduces more granular controls to the realm of remote execution, allowing systems to be targeted not just by hostname, but also by system properties. .SS Building on proven technology .sp Salt takes advantage of a number of technologies and techniques. The networking layer is built with the excellent \fI\%ZeroMQ\fP networking library, so the Salt daemon includes a viable and transparent AMQ broker. Salt uses public keys for authentication with the master daemon, then uses faster \fI\%AES\fP encryption for payload communication; authentication and encryption are integral to Salt. Salt takes advantage of communication via \fI\%msgpack\fP, enabling fast and light network traffic. .SS Python client interface .sp In order to allow for simple expansion, Salt execution routines can be written as plain Python modules. The data collected from Salt executions can be sent back to the master server, or to any arbitrary program. Salt can be called from a simple Python API, or from the command line, so that Salt can be used to execute one\-off commands as well as operate as an integral part of a larger application. .SS Fast, flexible, scalable .sp The result is a system that can execute commands at high speed on target server groups ranging from one to very many servers. Salt is very fast, easy to set up, amazingly malleable and provides a single remote execution architecture that can manage the diverse requirements of any number of servers. The Salt infrastructure brings together the best of the remote execution world, amplifies its capabilities and expands its range, resulting in a system that is as versatile as it is practical, suitable for any network. .SS Open .sp Salt is developed under the \fI\%Apache 2.0 licence\fP, and can be used for open and proprietary projects. Please submit your expansions back to the Salt project so that we can all benefit together as Salt grows. Please feel free to sprinkle Salt around your systems and let the deliciousness come forth. .SH INSTALLATION .sp The Salt system setup is amazingly simple, as this is one of the central design goals of Salt. .IP "See also" .sp \fBInstalling Salt for development\fP and contributing to the project. .RE .SS Quick Install .sp Many popular distributions will be able to install the salt minion by executing the bootstrap script: .sp .nf .ft C wget \-O \- http://bootstrap.saltstack.org | sudo sh .ft P .fi .sp The script should also make it simple to install a salt master, if desired. .sp Currently the install script has been tested to work on: .INDENT 0.0 .IP \(bu 2 Ubuntu 10.x/11.x/12.x .IP \(bu 2 Debian 6.x .IP \(bu 2 CentOS 6.3 .IP \(bu 2 Fedora .IP \(bu 2 Arch .IP \(bu 2 FreeBSD 9.0 .UNINDENT .sp See \fI\%Salt Bootstrap\fP for more information. .SS Platform\-specific installation instructions .sp These guides go into detail how to install salt on a given platform. .SS Arch Linux .SS Installation .sp Salt is currently available via the Arch User Repository (AUR). There are currently stable and \-git packages available. .SS Stable Release .sp Install Salt stable releases from the Arch Linux AUR as follows: .sp .nf .ft C wget https://aur.archlinux.org/packages/sa/salt/salt.tar.gz tar xf salt.tar.gz cd salt/ makepkg \-is .ft P .fi .sp A few of Salt\(aqs dependencies are currently only found within the AUR, so it is necessary to download and run \fBmakepkg \-is\fP on these as well. As a reference, Salt currently relies on the following packages which are only available via the AUR: .INDENT 0.0 .IP \(bu 2 \fI\%https://aur.archlinux.org/packages/py/python2-msgpack/python2-msgpack.tar.gz\fP .IP \(bu 2 \fI\%https://aur.archlinux.org/packages/py/python2-psutil/python2-psutil.tar.gz\fP .UNINDENT .IP Note yaourt .sp If a tool such as \fI\%Yaourt\fP is used, the dependencies will be gathered and built automatically. .sp The command to install salt using the yaourt tool is: .sp .nf .ft C yaourt salt .ft P .fi .RE .SS Tracking develop .sp To install the bleeding edge version of Salt (\fBmay include bugs!\fP), use the \-git package. Installing the \-git package as follows: .sp .nf .ft C wget https://aur.archlinux.org/packages/sa/salt\-git/salt\-git.tar.gz tar xf salt\-git.tar.gz cd salt\-git/ makepkg \-is .ft P .fi .sp See the note above about Salt\(aqs dependencies. .SS Post\-installation tasks .sp \fBConfiguration files\fP .sp The Salt package installs two template configuration files, \fB/etc/salt/master.template\fP and \fB/etc/salt/minion.template\fP. These files need to be copied as follows: .sp .nf .ft C cp /etc/salt/master.template /etc/salt/master cp /etc/salt/minion.template /etc/salt/minion .ft P .fi .sp Note: only the configuration files for the services to be run need be copied. .sp \fBsystemd\fP .sp Activate the Salt Master and/or Minion via \fBsystemctl\fP as follows: .sp .nf .ft C systemctl enable salt\-master.service systemctl enable salt\-minion.service .ft P .fi .sp \fBStart the Master\fP .sp Once you\(aqve completed all of these steps you\(aqre ready to start your Salt Master. You should be able to start your Salt Master now using the command seen here: .sp .nf .ft C systemctl start salt\-master .ft P .fi .sp Now go to the \fBConfiguring Salt\fP page. .SS Debian Installation .sp Currently the latest packages for Debian are published in Martin F. Krafft\(aqs personal debian.org repository. .SS Confiure Apt .sp Setup apt to install Salt from the repository and use Debian\(aqs stable (squeeze) backports for dependencies: .sp .nf .ft C 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 Add the repository to the list of sources: .sp .nf .ft C cat <<_eof > /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 Import the repository key. .sp .nf .ft C wget \-q \-O\- "http://debian.madduck.net/repo/gpg/archive.key" | apt\-key add \- .ft P .fi .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 echo "8b1983fc2d2c55c83e2bbc15d93c3fc090c8e0e92c04ece555a6b6d8ff26de8b4fc2ccbe1bbd16a6357ff86b8b69fd261e90d61350e07a518d50fc9f5f0a1eb3 archive.key" | sha512sum \-c .ft P .fi .RE .sp Update the package database: .sp .nf .ft C 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 apt\-get install salt\-master .ft P .fi .sp .nf .ft C apt\-get install salt\-minion .ft P .fi .sp .nf .ft C apt\-get install salt\-syndic .ft P .fi .SS Post\-installation tasks .sp 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 cat <.deb salt\-minion.deb apt\-get \-f install .ft P .fi .sp 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! .SS Installation .sp Salt can be installed using \fByum\fP and is available in the standard Fedora repositories. .SS Stable Release .sp Salt is packaged separately for the minion and the master. 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 .nf .ft C yum install salt\-master 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 systemctl enable salt\-master.service .ft P .fi .sp To start the Master: .sp .nf .ft C systemctl start salt\-master.service .ft P .fi .sp \fBMinion\fP .sp To have the Minion start automatically at boot time: .sp .nf .ft C systemctl enable salt\-minion.service .ft P .fi .sp To start the Minion: .sp .nf .ft C systemctl start salt\-minion.service .ft P .fi .sp 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, 9.0 and 9.1 releases. .sp Salt is dependent on the following additional ports. These will be installed as dependencies of the \fBsysutils/py\-salt\fP port. .sp .nf .ft C /devel/py\-yaml /devel/py\-pyzmq /devel/py\-Jinja2 /devel/py\-msgpack /security/py\-pycrypto /security/py\-m2crypto .ft P .fi .SS Installation .sp To install Salt from the FreeBSD ports tree, use the command: .sp .nf .ft C make \-C /usr/ports/sysutils/py\-salt install clean .ft P .fi .SS Post\-installation tasks .sp \fBMaster\fP .sp Copy the sample configuration file: .sp .nf .ft C cp /usr/local/etc/salt/master.sample /usr/local/etc/salt/master .ft P .fi .sp \fBrc.conf\fP .sp Activate the Salt Master in \fB/etc/rc.conf\fP or \fB/etc/rc.conf.local\fP and add: .sp .nf .ft C + salt_master_enable="YES" .ft P .fi .sp \fBStart the Master\fP .sp Start the Salt Master as follows: .sp .nf .ft C service salt_master start .ft P .fi .sp \fBMinion\fP .sp Copy the sample configuration file: .sp .nf .ft C cp /usr/local/etc/salt/minion.sample /usr/local/etc/salt/minion .ft P .fi .sp \fBrc.conf\fP .sp Activate the Salt Minion in \fB/etc/rc.conf\fP or \fB/etc/rc.conf.local\fP and add: .sp .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 \fBStart the Minion\fP .sp Start the Salt Minion as follows: .sp .nf .ft C service salt_minion start .ft P .fi .sp Now go to the \fBConfiguring Salt\fP page. .SS Gentoo .sp Salt can be easily installed on Gentoo via Portage: .sp .nf .ft C emerge app\-admin/salt .ft P .fi .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 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 Many of the standard Salt modules have been ported to work on Windows and many of the Salt States currently work on Windows, as well. .SS Windows Installer .sp A Salt Minion Windows installer can be found here: .IP "Download here" .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 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 then start the minion. .sp The \fIsalt\-minion\fP service will appear in the Windows Service Manager and can be started and stopped there or with the command line program \fIsc\fP like any other Windows service. .sp If the minion won\(aqt start, try installing the Microsoft Visual C++ 2008 x64 redistributable. .sp Make sure that the minion config file has the line \fIipc_mode: tcp\fP .SS Silent Installer option .sp The installer can be run silently by providing the \fI/S\fP option at the command line. The options \fI/master\fP and \fI/minion\-name\fP allow for configuring the master hostname and minion name, respectively. Here\(aqs an example of using the silent installer: .sp .nf .ft C Salt\-Minion\-0.11.1\-Setup\-amd64.exe /S /master=yoursaltmaster /minion\-name=yourminionname .ft P .fi .SS Installer Source .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. 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 The NSIS installer can be found here: \fI\%http://nsis.sourceforge.net/Main_Page\fP .SS Installation from source .sp To install Salt from source one must install each dependency separately and configure Salt to run on your Windows host. .sp Rather than send you on a wild goose chase across the Internet, we\(aqve collected some of the more difficult to find installers in our github repo for you. .SS Install on Windows XP 32bit .INDENT 0.0 .IP 1. 3 Install \fI\%msysgit\fP .INDENT 3.0 .IP 1. 3 Clone the Salt git repository from github .UNINDENT .UNINDENT .sp .nf .ft C git clone git://github.com/saltstack/salt.git .ft P .fi .INDENT 0.0 .IP 2. 4 Install \fI\%Microsoft Visual Studio 2008 Express\fP. You must use Visual Studio 2008 Express, \fBnot\fP Visual Studio 2010 Express. .IP 3. 4 Install \fI\%Python 2.7.x\fP .IP 4. 4 Add c:\ePython27 to your system path .IP 5. 4 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 .IP 1. 3 Choose first option to install in Windows system directory .UNINDENT .IP 7. 4 Install \fI\%pyzmq-2.1.11.win32-py2.7.msi\fP .IP 8. 4 Install \fI\%pycrypto-2.3.win32-py2.7.msi\fP .IP 9. 4 Install \fI\%PyYAML-3.10.win32-py2.7.msi\fP .IP 10. 4 Install \fI\%Cython-0.15.1.win32-py2.79.exe\fP .IP 11. 4 Download and run \fI\%distribute_setup.py\fP .UNINDENT .sp .nf .ft C python distribute_setup.py .ft P .fi .INDENT 0.0 .IP 12. 4 Download and run \fI\%pip\fP .UNINDENT .sp .nf .ft C python get\-pip.py .ft P .fi .INDENT 0.0 .IP 13. 4 Add c:\epython27\escripts to your path .IP 14. 4 Close terminal window and open a new terminal window (\fIcmd\fP) .IP 15. 4 Install jinja2 .UNINDENT .sp .nf .ft C pip install jinja2 .ft P .fi .INDENT 0.0 .IP 16. 4 Install Messagepack .UNINDENT .sp .nf .ft C pip install msgpack\-python .ft P .fi .INDENT 0.0 .IP 17. 4 Install Salt .UNINDENT .sp .nf .ft C cd ./salt python setup.py install .ft P .fi .INDENT 0.0 .IP 18. 4 Edit c:\eetc\esalt\eminon .UNINDENT .sp .nf .ft C master: ipaddress or hostname of your salt\-master master_port: 4506 ipc_mode: tcp root_dir: c:\e pki_dir: /etc/salt/pki cachedir: /var/cache/salt renderer: yaml_jinja open_mode: False multiprocessing: False .ft P .fi .INDENT 0.0 .IP 19. 4 Start the salt\-minion .UNINDENT .sp .nf .ft C cd c:\epython27\escripts python salt\-minion .ft P .fi .INDENT 0.0 .IP 20. 4 On the salt\-master accept the new minion\(aqs key .UNINDENT .sp .nf .ft C sudo salt\-key \-A (This accepts all unaccepted keys. If you\(aqre concerned about security just accept the key for this specific minion) .ft P .fi .INDENT 0.0 .IP 21. 4 Test that your minion is responding .INDENT 4.0 .INDENT 3.5 .INDENT 0.0 .IP a. 3 On the salt\-master run: .UNINDENT .UNINDENT .UNINDENT .UNINDENT .sp .nf .ft C sudo salt \(aq*\(aq test.ping .ft P .fi .sp You should get the following response: {\(aqyour minion hostname\(aq: True} .SS Single command bootstrap script .sp On a 64 bit Windows host the following script makes an unattended install of salt, including all dependencies: .sp .nf .ft C "PowerShell (New\-Object System.Net.WebClient).DownloadFile(\(aqhttp://csa\-net.dk/salt/bootstrap64.bat\(aq,\(aqC:\ebootstrap.bat\(aq);(New\-Object \-com Shell.Application).ShellExecute(\(aqC:\ebootstrap.bat\(aq);" (All in one line.) .ft P .fi .sp You can execute the above command remotely from a Linux host using winexe: .sp .nf .ft C winexe \-U "administrator" //fqdn "PowerShell (New\-Object ......);" .ft P .fi .sp For more info check \fI\%http://csa-net.dk/salt\fP .SS Dependencies .sp Salt should run on any Unix\-like platform so long as the dependencies are met. .INDENT 0.0 .IP \(bu 2 \fI\%Python 2.6\fP >= 2.6 <3.0 .IP \(bu 2 \fI\%ZeroMQ\fP >= 2.1.9 .IP \(bu 2 \fI\%pyzmq\fP >= 2.1.9 \- ZeroMQ Python bindings .IP \(bu 2 \fI\%PyCrypto\fP \- The Python cryptography toolkit .IP \(bu 2 \fI\%msgpack-python\fP \- High\-performance message interchange format .IP \(bu 2 \fI\%YAML\fP \- Python YAML bindings .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\%mako\fP \- an optional parser for Salt States (configurable in the master settings) .IP \(bu 2 gcc \- dynamic \fI\%Cython\fP module compiling .UNINDENT .SH CONFIGURING SALT .sp Salt configuration is very simple. The default configuration for the \fImaster\fP will work for most installations and the only requirement for setting up a \fIminion\fP is to set the location of the master in the minion configuration file. .INDENT 0.0 .TP .B master The Salt master is the central server that all minions connect to. Commands are run on the minions through the master, and minions send data back to the master (unless otherwise redirected with a \fBreturner\fP). It is started with the \fBsalt\-master\fP program. .TP .B minion Salt minions are the potentially hundreds or thousands of servers that may be queried and controlled from the master. .UNINDENT .sp The configuration files will be installed to \fB/etc/salt\fP and are named after the respective components, \fB/etc/salt/master\fP and \fB/etc/salt/minion\fP. .SS Master Configuration .sp By default the Salt master listens on ports 4505 and 4506 on all interfaces (0.0.0.0). To bind Salt to a specific IP, redefine the "interface" directive in the master configuration file, typically \fB/etc/salt/master\fP, as follows: .sp .nf .ft C \- #interface: 0.0.0.0 + interface: 10.0.0.1 .ft P .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 a Salt Minion is very simple. By default a Salt Minion will try to connect to the DNS name "salt"; if the Minion is able to resolve that name correctly, no configuration is needed. .sp If the DNS name "salt" does not resolve to point to the correct location of the Master, redefine the "master" directive in the minion configuration file, typically \fB/etc/salt/minion\fP, as follows: .sp .nf .ft C \- #master: salt + master: 10.0.0.1 .ft P .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 Start the master in the foreground (to daemonize the process, pass the \fI\-d flag\fP): .sp .nf .ft C # salt\-master .ft P .fi .IP 2. 3 Start the minion in the foreground (to daemonize the process, pass the \fI\-d flag\fP): .sp .nf .ft C # salt\-minion .ft P .fi .UNINDENT .IP "Having trouble?" .sp The simplest way to troubleshoot Salt is to run the master and minion in the foreground with \fIlog level\fP set to \fBdebug\fP: .sp .nf .ft C salt\-master \-\-log\-level=debug .ft P .fi .RE .IP "Run as an unprivileged (non\-root) user?" .sp To run Salt as another user, specify \fB\-\-user\fP in the command line or assign \fBuser\fP in the \fBconfiguration file\fP. .RE .sp There is also a full \fBtroubleshooting guide\fP available. .SS Key Management .sp Salt uses AES encryption for all communication between the Master and the Minion. This ensures that the commands sent to the Minions cannot be tampered with, and that communication between Master and Minion is authenticated through trusted, accepted keys. .sp Before commands can be sent to a Minion, its key must be accepted on the Master. Run the \fBsalt\-key\fP command to list the keys known to the Salt Master: .sp .nf .ft C [root@master ~]# salt\-key \-L Unaccepted Keys: alpha bravo charlie delta Accepted Keys: .ft P .fi .sp This example shows that the Salt Master is aware of four Minions, but none of the keys has been accepted. To accept the keys and allow the Minions to be controlled by the Master, again use the \fBsalt\-key\fP command: .sp .nf .ft C [root@master ~]# salt\-key \-A [root@master ~]# salt\-key \-L Unaccepted Keys: Accepted Keys: alpha bravo charlie delta .ft P .fi .sp The \fBsalt\-key\fP command allows for signing keys individually or in bulk. The example above, using \fB\-A\fP bulk\-accepts all pending keys. To accept keys individually use the lowercase of the same option, \fB\-a keyname\fP. .IP "See also" .sp \fBsalt\-key manpage\fP .RE .SS Sending Commands .sp Communication between the Master and a Minion may be verified by running the \fBtest.ping\fP remote command. .sp .nf .ft C [root@master ~]# salt \(aqalpha\(aq test.ping {\(aqalpha\(aq: True} .ft P .fi .sp Communication between the Master and all Minions may be tested in a similar way. .sp .nf .ft C [root@master ~]# salt \(aq*\(aq test.ping {\(aqalpha\(aq: True} {\(aqbravo\(aq: True} {\(aqcharlie\(aq: True} {\(aqdelta\(aq: True} .ft P .fi .sp Each of the Minions should send a "True" response as shown above. .SS What\(aqs Next? .sp Depending on the primary way you want to manage your machines you may either want to visit the section regarding Salt States, or the section on Modules. .SH DEVELOPING SALT .sp 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 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 changes to the fork, and then open up a pull request. .sp 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 First, make a local clone of your github fork of the salt github repo and make edits and changes locally. .sp Then, create a new branch on your clone by entering the following commands: .sp .nf .ft C git checkout \-b fixed\-broken\-thing Switched to a new branch \(aqfixed\-broken\-thing\(aq .ft P .fi .sp Choose a name for your branch that describes its purpose. .sp Now commit your changes to this new branch with the following command: .sp .nf .ft C #add and commit all changes at once git commit \-a \-m \(aqdescription of my fixes for the broken thing\(aq .ft P .fi .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 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 .nf .ft C virtualenv /path/to/your/virtualenv .ft P .fi .sp On Arch Linux, where Python 3 is the default installation of Python, use the \fBvirtualenv2\fP command instead of \fBvirtualenv\fP. .IP Note 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: .sp .nf .ft C source /path/to/your/virtualenv/bin/activate .ft P .fi .sp Install Salt (and dependencies) into the virtualenv: .sp .nf .ft C pip install M2Crypto # Don\(aqt install on Debian/Ubuntu (see below) pip install pyzmq PyYAML pycrypto msgpack\-python jinja2 psutil pip install \-e ./salt # the path to the salt git clone from above .ft P .fi .IP Note Installing M2Crypto .sp \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 env SWIG_FEATURES="\-cpperraswarn \-includeall \-D__\(gauname \-m\(ga__ \-I/usr/include/openssl" pip install M2Crypto .ft P .fi .sp 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: .sp .nf .ft C apt\-get install python\-m2crypto .ft P .fi .sp 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 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: .INDENT 0.0 .IP \(bu 2 \fI\%RHEL\fP and \fI\%CentOS\fP releases 6 and later .IP \(bu 2 \fI\%Fedora Linux\fP releases 11 and later .IP \(bu 2 \fI\%Amazon Linux\fP .UNINDENT .sp 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 During development it is easiest to be able to run the Salt master and minion that are installed in the virtualenv you created above, and also to have all the configuration, log, and cache files contained in the virtualenv as well. .sp Copy the master and minion config files into your virtualenv: .sp .nf .ft C mkdir \-p /path/to/your/virtualenv/etc/salt cp ./salt/conf/master /path/to/your/virtualenv/etc/salt/master cp ./salt/conf/minion /path/to/your/virtualenv/etc/salt/minion .ft P .fi .sp Edit the master config file: .INDENT 0.0 .IP 1. 3 Uncomment and change the \fBuser: root\fP value to your own user. .IP 2. 3 Uncomment and change the \fBroot_dir: /\fP value to point to \fB/path/to/your/virtualenv\fP. .IP 3. 3 If you are running version 0.11.1 or older, uncomment and change the \fBpidfile: /var/run/salt\-master.pid\fP value to point to \fB/path/to/your/virtualenv/salt\-master.pid\fP. .IP 4. 3 If you are also running a non\-development version of Salt you will have to change the \fBpublish_port\fP and \fBret_port\fP values as well. .UNINDENT .sp Edit the minion config file: .INDENT 0.0 .IP 1. 3 Repeat the edits you made in the master config for the \fBuser\fP and \fBroot_dir\fP values as well as any port changes. .IP 2. 3 If you are running version 0.11.1 or older, uncomment and change the \fBpidfile: /var/run/salt\-minion.pid\fP value to point to \fB/path/to/your/virtualenv/salt\-minion.pid\fP. .IP 3. 3 Uncomment and change the \fBmaster: salt\fP value to point at \fBlocalhost\fP. .IP 4. 3 Uncomment and change the \fBid:\fP value to something descriptive like "saltdev". This isn\(aqt strictly necessary but it will serve as a reminder of which Salt installation you are working with. .UNINDENT .IP Note Using \fIsalt\-call\fP with a \fBStandalone Minion\fP .sp If you plan to run \fIsalt\-call\fP with this self\-contained development environment in a masterless setup, you should invoke \fIsalt\-call\fP with \fB\-c /path/to/your/virtualenv/etc/salt\fP so that salt can find the minion config file. Without the \fB\-c\fP option, Salt finds its config files in \fI/etc/salt\fP. .RE .sp Start the master and minion, accept the minon\(aqs key, and verify your local Salt installation is working: .sp .nf .ft C cd /path/to/your/virtualenv salt\-master \-c ./etc/salt \-d salt\-minion \-c ./etc/salt \-d salt\-key \-c ./etc/salt \-L salt\-key \-c ./etc/salt \-A salt \-c ./etc/salt \(aq*\(aq test.ping .ft P .fi .sp Running the master and minion in debug mode can be helpful when developing. To do this, add \fB\-l debug\fP to the calls to \fBsalt\-master\fP and \fBsalt\-minion\fP. If you would like to log to the console instead of to the log file, remove the \fB\-d\fP. .sp Once the minion starts, you may see an error like the following: .sp .nf .ft C zmq.core.error.ZMQError: ipc path "/path/to/your/virtualenv/var/run/salt/minion/minion_event_7824dcbcfd7a8f6755939af70b96249f_pub.ipc" is longer than 107 characters (sizeof(sockaddr_un.sun_path)). .ft P .fi .sp This means the the path to the socket the minion is using is too long. This is a system limitation, so the only workaround is to reduce the length of this path. This can be done in a couple different ways: .INDENT 0.0 .IP 1. 3 Create your virtualenv in a path that is short enough. .IP 2. 3 Edit the \fBsock_dir\fP minion config variable and reduce its length. Remember that this path is relative to the value you set in \fBroot_dir\fP. .UNINDENT .sp \fBNOTE:\fP The socket path is limited to 107 characters on Solaris and Linux, and 103 characters on BSD\-based systems. .IP Note File descriptor limits .sp Ensure that the system open file limit is raised to at least 2047: .sp .nf .ft C # check your current limit ulimit \-n # raise the limit. persists only until reboot # use \(aqlimit descriptors 2047\(aq for c\-shell ulimit \-n 2047 .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: .sp .nf .ft C pip install mock .ft P .fi .sp If you are on Python < 2.7 then you will also need unittest2: .sp .nf .ft C pip install unittest2 .ft P .fi .sp Finally you use setup.py to run the tests with the following command: .sp .nf .ft C \&./setup.py test .ft P .fi .sp For greater control while running the tests, please try: .sp .nf .ft C \&./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 .B Targeting Specifying which minions should run a command or execute a state by matching against hostnames, or system information, or defined groups, or even combinations thereof. .UNINDENT .sp For example the command \fBsalt web1 apache.signal restart\fP to restart the Apache httpd server specifies the machine \fBweb1\fP as the target and the command will only be run on that one minion. .sp Similarly when using States, the following \fItop file\fP specifies that only the \fBweb1\fP minion should execute the contents of \fBwebserver.sls\fP: .sp .nf .ft C base: \(aqweb1\(aq: \- webserver .ft P .fi .sp There are many ways to target individual minions or groups of minions in Salt: .SS Matching the \fBminion id\fP .INDENT 0.0 .TP .B minion id A unique identifier for a given minion. By default the minion id is the FQDN of that host but this can be overridden. .UNINDENT .sp Each minion needs a unique identifier. By default when a minion starts for the first time it chooses its FQDN as that identifier. The minion id can be overridden via the minion\(aqs \fBid\fP configuration setting. .IP Tip minion id and minion keys .sp The \fIminion id\fP is used to generate the minion\(aqs public/private keys and if it ever changes the master must then accept the new key as though the minion was a new host. .RE .SS Globbing .sp The default matching that Salt utilizes is \fI\%shell-style globbing\fP around the \fIminion id\fP. This also works for states in the \fItop file\fP. .IP Note You must wrap \fBsalt\fP calls that use globbing in single\-quotes to prevent the shell from expanding the globs before Salt is invoked. .RE .sp Match all minions: .sp .nf .ft C salt \(aq*\(aq test.ping .ft P .fi .sp Match all minions in the example.net domain or any of the example domains: .sp .nf .ft C salt \(aq*.example.net\(aq test.ping salt \(aq*.example.*\(aq test.ping .ft P .fi .sp Match all the \fBwebN\fP minions in the example.net domain (\fBweb1.example.net\fP, \fBweb2.example.net\fP … \fBwebN.example.net\fP): .sp .nf .ft C salt \(aqweb?.example.net\(aq test.ping .ft P .fi .sp Match the \fBweb1\fP through \fBweb5\fP minions: .sp .nf .ft C salt \(aqweb[1\-5]\(aq test.ping .ft P .fi .sp Match the \fBweb\-x\fP, \fBweb\-y\fP, and \fBweb\-z\fP minions: .sp .nf .ft C salt \(aqweb\-[x\-z]\(aq test.ping .ft P .fi .SS Regular Expressions .sp Minions can be matched using Perl\-compatible \fI\%regular expressions\fP (which is globbing on steroids and a ton of caffeine). .sp Match both \fBweb1\-prod\fP and \fBweb1\-devel\fP minions: .sp .nf .ft C salt \-E \(aqweb1\-(prod|devel)\(aq test.ping .ft P .fi .sp When using regular expressions in a State\(aqs \fItop file\fP, you must specify the matcher as the first option. The following example executes the contents of \fBwebserver.sls\fP on the above\-mentioned minions. .sp .nf .ft C base: \(aqweb1\-(prod|devel)\(aq: \- match: pcre \- webserver .ft P .fi .SS Lists .sp At the most basic level, you can specify a flat list of minion IDs: .sp .nf .ft C salt \-L \(aqweb1,web2,web3\(aq test.ping .ft P .fi .SS Grains .sp Salt comes with an interface to derive information about the underlying system. This is called the grains interface, because it presents salt with grains of information. .INDENT 0.0 .TP .B Grains Static bits of information that a minion collects about the system when the minion first starts. .UNINDENT .sp The grains interface is made available to Salt modules and components so that the right salt minion commands are automatically available on the right systems. .sp It is important to remember that grains are bits of information loaded when the salt minion starts, so this information is static. This means that the information in grains is unchanging, therefore the nature of the data is static. So grains information are things like the running kernel, or the operating system. .sp Match all CentOS minions: .sp .nf .ft C salt \-G \(aqos:CentOS\(aq test.ping .ft P .fi .sp Match all minions with 64\-bit CPUs and return number of available cores: .sp .nf .ft C salt \-G \(aqcpuarch:x86_64\(aq grains.item num_cpus .ft P .fi .SS Grains in the Minion Config .sp Grains can also be statically assigned within the minion configuration file. Just add the option \fBgrains\fP and pass options to it: .sp .nf .ft C grains: roles: \- webserver \- memcache deployment: datacenter4 cabinet: 13 cab_u: 14\-15 .ft P .fi .sp Then status data specific to your servers can be retrieved via Salt, or used inside of the State system for matching. It also makes targeting, in the case of the example above, simply based on specific data about your deployment. .SS Writing Grains .sp Grains are easy to write. The grains interface is derived by executing all of the "public" functions found in the modules located in the grains package or the custom grains directory. The functions in the modules of the grains must return a Python \fI\%dict\fP, where the keys in the dict are the names of the grains and the values are the values. .sp Custom grains should be placed in a \fB_grains\fP directory located under the \fBfile_roots\fP specified by the master config file. They will be 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 change, consider using \fBPillar\fP instead. .SS Examples of Grains .sp The core module in the grains package is where the main grains are loaded by the Salt minion and provides the principal example of how to write grains: .sp \fI\%https://github.com/saltstack/salt/blob/develop/salt/grains/core.py\fP .SS Syncing Grains .sp Syncing grains can be done a number of ways, they are automatically synced when state.highstate is called, or the grains can be synced and reloaded by calling the saltutil.sync_grains or saltutil.sync_all functions. .SS Node groups .INDENT 0.0 .TP .B Node group A predefined group of minions declared in the master configuration file \fBnodegroups\fP setting as a compound target. .UNINDENT .sp Nodegroups are declared using a compound target specification. The compount target documentation can be found here: .sp \fBCompound Matchers\fP .sp For example, in the master config file \fBnodegroups\fP setting: .sp .nf .ft C nodegroups: group1: \(aqL@foo.domain.com,bar.domain.com,baz.domain.com or bl*.domain.com\(aq group2: \(aqG@os:Debian and foo.domain.com\(aq .ft P .fi .sp Specify a nodegroup via the \fB\-N\fP option at the command\-line: .sp .nf .ft C salt \-N group1 test.ping .ft P .fi .sp Specify a nodegroup with \fB\- match: nodegroup\fP in a \fItop file\fP: .sp .nf .ft C base: group1: \- match: nodegroup \- webserver .ft P .fi .SS Compound matchers .INDENT 0.0 .TP .B Compound matcher A combination of many target definitions that can be combined with boolean operators. .UNINDENT .sp Compound matchers allow very granular minion targeting using any of the previously discussed matchers. The default matcher is a \fI\%glob\fP, as usual. For matching via anything other than glob, preface it with the letter denoting the match type. The currently implemented "letters" are: .TS center; |l|l|l|. _ T{ Letter T} T{ Meaning T} T{ Example T} _ T{ G T} T{ Grains glob match T} T{ \fBG@os:Ubuntu\fP T} _ T{ E T} T{ PCRE Minion id match T} T{ \fBE@web\ed+\e.(dev|qa|prod)\e.loc\fP T} _ T{ P T} T{ Grains PCRE match T} T{ \fBP@os:(RedHat|Fedora|CentOS)\fP T} _ T{ L T} T{ List of minions T} T{ \fBL@minion1.example.com,minion3.domain.com or bl*.domain.com\fP T} _ T{ I T} T{ Pillar glob match T} T{ \fBI@pdata:foobar\fP T} _ T{ S T} T{ Subnet/IP addr match 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. .sp For example, the following command matches all minions that have a hostname that begins with "webserv" and that are running Debian or it matches any minions that have a hostname that matches the \fI\%regular expression\fP \fBweb\-dc1\-srv.*\fP: .sp .nf .ft C salt \-C \(aqwebserv* and G@os:Debian or E@web\-dc1\-srv.*\(aq test.ping .ft P .fi .sp That same example expressed in a \fItop file\fP looks like the following: .sp .nf .ft C base: \(aqwebserv* and G@os:Debian or E@web\-dc1\-srv.*\(aq: \- match: compound \- webserver .ft P .fi .SS Batch Size .sp The batch size option allows commands to be executed while maintaining that only so many hosts are executing the command at one time. This option can take a percentage or a finite number: .sp .nf .ft C salt \e* \-b 10 test.ping salt \-G \(aqos:RedHat\(aq \-\-batch\-size 25% apache.signal restart .ft P .fi .sp This will only run test.ping on 10 of the targeted minions at a time and then restart apache on 25% of the minions matching \fBos:RedHat\fP at a time and work through them all until the task is complete. This makes jobs like rolling web server restarts behind a load balancer or doing maintenance on BSD firewalls using carp much easier with salt. .sp The batch system maintains a window of running minions, so, if there are a total of 150 minions targeted and the batch size is 10, then the command is sent to 10 minions, when one minion returns then the command is sent to one additional minion, so that the job is constantly running on 10 minions. .SH 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. .IP "Stuck?" .sp There are many ways to \fBget help from the Salt community\fP including our \fI\%mailing list\fP and our \fI\%IRC channel\fP #salt. .RE .SS Order your minions around .sp Now that you have a \fImaster\fP and at least one \fIminion\fP communicating with each other you can perform commands on the minion via the \fBsalt\fP command. Salt calls are comprised of three main components: .sp .nf .ft C salt \(aq\(aq [arguments] .ft P .fi .IP "See also" .sp \fBsalt manpage\fP .RE .SS target .sp The target component allows you to filter which minions should run the following function. The default filter is a glob on the minion id. For example: .sp .nf .ft C salt \(aq*\(aq test.ping salt \(aq*.example.org\(aq test.ping .ft P .fi .sp Targets can be based on minion system information using the Grains system: .sp .nf .ft C salt \-G \(aqos:Ubuntu\(aq test.ping .ft P .fi .IP "See also" .sp \fBGrains system\fP .RE .sp Targets can be filtered by regular expression: .sp .nf .ft C salt \-E \(aqvirtmach[0\-9]\(aq test.ping .ft P .fi .sp 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 \-C \(aqG@os:Ubuntu and webser* or E@database.*\(aq test.ping .ft P .fi .SS function .sp A function is some functionality provided by a module. Salt ships with a large collection of available functions. List all available functions on your minions: .sp .nf .ft C salt \(aq*\(aq sys.doc .ft P .fi .sp Here are some examples: .sp Show all currently available minions: .sp .nf .ft C salt \(aq*\(aq test.ping .ft P .fi .sp Run an arbitrary shell command: .sp .nf .ft C salt \(aq*\(aq cmd.run \(aquname \-a\(aq .ft P .fi .IP "See also" .sp \fBthe full list of modules\fP .RE .SS arguments .sp Space\-delimited arguments to the function: .sp .nf .ft C salt \(aq*\(aq cmd.exec_code python \(aqimport sys; print sys.version\(aq .ft P .fi .sp Optional, keyword arguments are also supported: .sp .nf .ft C salt \(aq*\(aq pip.install salt timeout=5 upgrade=True .ft P .fi .sp They are always in the form of \fBkwarg=argument\fP. .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 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 to contain this data simply. This is often called configuration management. .SS It is All Just Data .sp Before delving into the particulars, it will help to understand that the SLS is just a data structure under the hood. While understanding that the SLS is just a data structure is not at all critical to understand to make use Salt States, it should help bolster the understanding of where the real power is. .sp SLS files are therefore, in reality, just \fI\%dictionaries\fP, \fI\%lists\fP, \fI\%strings\fP, and \fI\%numbers\fP. By using this approach Salt can be much more flexible. As someone writes more state files, it becomes clear exactly what is being written. The result is a system that is easy to understand, yet grows with the needs of the admin or developer. .sp In the section titled "State Data Structures" a reference exists, explaining in depth how the data is laid out. .SS Default Data \- YAML .sp By default Salt represents the SLS data in what is one of the simplest serialization formats available \- \fI\%YAML\fP. .sp A typical SLS file will often look like this in YAML: .sp .nf .ft C apache: pkg: \- installed service: \- running \- require: \- pkg: apache .ft P .fi .sp This SLS data will ensure that the package named apache is installed, and that the apache service is running. The components can be explained in a simple way. .sp The first line is the ID for a set of data, and it is called the ID Declaration. This ID sets the name of the thing that needs to be manipulated. .sp The second and fourth lines are the start of the State Declarations, so they are using the pkg and service states respectively. The pkg state manages a software package to get installed via the system\(aqs native package manager, and the service state manages a system daemon. Below the pkg and service lines are the function to run. This function defines what state the named package and service should be in. Here the package is to be installed, and the service should be running. .sp Finally, on line 6, is the word \fBrequire\fP. This is called a Requisite Statement, and it makes sure that the Apache service is only started after the successful installation of the apache package. .SS Adding Configs and Users .sp When setting up a service like an Apache web server, many more components may need to be added. The Apache configuration file will most likely be managed, and a user and group may need to be set up. .sp .nf .ft C apache: pkg: \- installed service: \- running \- watch: \- pkg: apache \- file: /etc/httpd/conf/httpd.conf \- user: apache user.present: \- uid: 87 \- gid: 87 \- home: /var/www/html \- shell: /bin/nologin \- require: \- group: apache group.present: \- gid: 87 \- require: \- pkg: apache /etc/httpd/conf/httpd.conf: file.managed: \- source: salt://apache/httpd.conf \- user: root \- group: root \- mode: 644 .ft P .fi .sp This SLS data greatly extends the first example, and includes a config file, a user, a group and new requisite statement: \fBwatch\fP. .sp Adding more states is easy, since the new user and group states are under the Apache ID, the user and group will be the Apache user and group. The \fBrequire\fP statements will make sure that the user will only be made after the group, and that the group will be made only after the Apache package is installed. .sp Next,the \fBrequire\fP statement under service was changed to watch, and is now watching 3 states instead of just one. The watch statement does the same thing as require, making sure that the other states run before running the state with a watch, but it adds an extra component. The \fBwatch\fP statement will run the state\(aqs watcher function if any of the watched states changed anything. So if the package was updated, the config file changed, or the user uid modified, then the service state\(aqs watcher will be run. The service state\(aqs watcher just restarts the service, so in this case, a change in the config file will also trigger a restart of the respective service. .SS Moving Beyond a Single SLS .sp When setting up Salt States, more than one SLS will need to be used. The above examples were just in a single SLS file, but more than one SLS file can be combined to build out a State Tree. The above example also references a file with a strange source \- \fBsalt://apache/httpd.conf\fP. That file will need to be available as well. .sp The SLS files are laid out in a directory on the Salt master. Files are laid out as just files. A SLS is just a file and files to download are just files. .sp The Apache example would be laid out in the root of the Salt file server like this: .sp .nf .ft C apache/init.sls apache/httpd.conf .ft P .fi .sp So the httpd.conf is just a file in the apache directory, and is referenced directly. .sp But with more than a single SLS file, more components can be added to the toolkit, consider this SSH example: .sp \fBssh/init.sls:\fP .sp .nf .ft C openssh\-client: pkg.installed /etc/ssh/ssh_config: file.managed: \- user: root \- group: root \- mode: 644 \- source: salt://ssh/ssh_config \- require: \- pkg: openssh\-client .ft P .fi .sp \fBssh/server.sls:\fP .sp .nf .ft C include: \- ssh openssh\-server: pkg.installed sshd: service.running: \- require: \- pkg: openssh\-client \- pkg: openssh\-server \- file: /etc/ssh/banner \- file: /etc/ssh/sshd_config /etc/ssh/sshd_config: file.managed: \- user: root \- group: root \- mode: 644 \- source: salt://ssh/sshd_config \- require: \- pkg: openssh\-server /etc/ssh/banner: file: \- managed \- user: root \- group: root \- mode: 644 \- source: salt://ssh/banner \- require: \- pkg: openssh\-server .ft P .fi .IP Note You may notice that we use two similar ways of denoting that a file is managed by Salt. In the \fI/etc/ssh/sshd_config\fP state section above, we use the \fIfile.managed\fP state declaration whereas with the \fI/etc/ssh/banner\fP state section, we use the \fIfile\fP state declaration and add a \fImanaged\fP attribute to that state declaration. Both ways produce an identical result; the first way \-\- using \fIfile.managed\fP \-\- is merely a shortcut. .RE .sp Now our State Tree looks like this: .sp .nf .ft C apache/init.sls apache/httpd.conf ssh/init.sls ssh/server.sls ssh/banner ssh/ssh_config ssh/sshd_config .ft P .fi .sp This example now introduces the \fBinclude\fP statement. The include statement includes another SLS file so that components found in it can be required, watched or as will soon be demonstrated \- extended. .sp The include statement allows for states to be cross linked. When an SLS has an include statement it is literally extended to include the contents of the included SLS files. .SS Extending Included SLS Data .sp Sometimes SLS data needs to be extended. Perhaps the apache service needs to watch additional resources, or under certain circumstances a different file needs to be placed. .sp These examples will add more watchers to apache and change the ssh banner. .sp \fBssh/custom\-server.sls:\fP .sp .nf .ft C include: \- ssh.server extend: /etc/ssh/banner: file: \- source: salt://ssh/custom\-banner .ft P .fi .sp \fBpython/mod_python.sls:\fP .sp .nf .ft C include: \- apache extend: apache: service: \- watch: \- pkg: mod_python mod_python: pkg.installed .ft P .fi .sp The \fBcustom\-server.sls\fP file uses the extend statement to overwrite where the banner is being downloaded from, and therefore changing what file is being used to configure the banner. .sp In the new mod_python SLS the mod_python package is added, but more importantly the apache service was extended to also watch the mod_python package. .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 Understanding the Render System .sp Since the SLS data is just plain old data, it does not need to be represented with YAML. Salt defaults to YAML because it is very straightforward and easy to learn and use. But the SLS files can be rendered from almost any imaginable medium, so long as a renderer module is provided. .sp The default rendering system is the \fByaml_jinja\fP renderer. The \fByaml_jinja\fP renderer will first pass the template through the \fI\%Jinja2\fP templating system, and then through the YAML parser. The benefit here is that full programming constructs are available when creating SLS files. .sp Other renderers available are \fByaml_mako\fP and \fByaml_wempy\fP which each use the \fI\%Mako\fP or \fI\%Wempy\fP templating system respectively rather than the jinja templating system, and more notably, the pure Python or \fBpy\fP renderer. The \fBpy\fP renderer allows for SLS files to be written in pure Python, allowing for the utmost level of flexibility and power when preparing SLS data. .SS Getting to Know the Default \- yaml_jinja .sp The default renderer \- \fByaml_jinja\fP, allows for the use of the jinja templating system. A guide to the Jinja templating system can be found here: \fI\%http://jinja.pocoo.org/docs\fP .sp When working with renderers a few very useful bits of data are passed in. In the case of templating engine based renderers, three critical components are available, \fBsalt\fP, \fBgrains\fP, and \fBpillar\fP. The \fBsalt\fP object allows for any Salt function to be called from within the template, and \fBgrains\fP allows for the Grains to be accessed from within the template. A few examples: .sp \fBapache/init.sls:\fP .sp .nf .ft C apache: pkg.installed: {% if grains[\(aqos\(aq] == \(aqRedHat\(aq%} \- name: httpd {% endif %} service.running: {% if grains[\(aqos\(aq] == \(aqRedHat\(aq%} \- name: httpd {% endif %} \- watch: \- pkg: apache \- file: /etc/httpd/conf/httpd.conf \- user: apache user.present: \- uid: 87 \- gid: 87 \- home: /var/www/html \- shell: /bin/nologin \- require: \- group: apache group.present: \- gid: 87 \- require: \- pkg: apache /etc/httpd/conf/httpd.conf: file.managed: \- source: salt://apache/httpd.conf \- user: root \- group: root \- mode: 644 .ft P .fi .sp This example is simple. If the \fBos\fP grain states that the operating system is Red Hat, then the name of the Apache package and service needs to be httpd. .sp A more aggressive way to use Jinja can be found here, in a module to set up a MooseFS distributed filesystem chunkserver: .sp \fBmoosefs/chunk.sls:\fP .sp .nf .ft C include: \- moosefs {% for mnt in salt[\(aqcmd.run\(aq](\(aqls /dev/data/moose*\(aq).split() %} /mnt/moose{{ mnt[\-1] }}: mount.mounted: \- device: {{ mnt }} \- fstype: xfs \- mkmnt: True file.directory: \- user: mfs \- group: mfs \- require: \- user: mfs \- group: mfs {% endfor %} \(aq/etc/mfshdd.cfg\(aq: file.managed: \- source: salt://moosefs/mfshdd.cfg \- user: root \- group: root \- mode: 644 \- template: jinja \- require: \- pkg: mfs\-chunkserver \(aq/etc/mfschunkserver.cfg\(aq: file.managed: \- source: salt://moosefs/mfschunkserver.cfg \- user: root \- group: root \- mode: 644 \- template: jinja \- require: \- pkg: mfs\-chunkserver mfs\-chunkserver: pkg: \- installed mfschunkserver: service: \- running \- require: {% for mnt in salt[\(aqcmd.run\(aq](\(aqls /dev/data/moose*\(aq) %} \- mount: /mnt/moose{{ mnt[\-1] }} \- file: /mnt/moose{{ mnt[\-1] }} {% endfor %} \- file: /etc/mfschunkserver.cfg \- file: /etc/mfshdd.cfg \- file: /var/lib/mfs .ft P .fi .sp This example shows much more of the available power provided by Jinja. Multiple for loops are used to dynamically detect available hard drives and set them up to be mounted, and the \fBsalt\fP object is used multiple times to call shell commands to gather data. .SS Introducing the Python Renderer .sp Sometimes the chosen default renderer might not have enough logical power to accomplish the needed task. When this happens, the Python renderer can be used. Normally a YAML renderer should be used for the majority of SLS files, but a SLS file set to use another renderer can be easily added to the tree. .sp This example shows a very basic Python SLS file: .sp \fBpython/django.sls:\fP .sp .nf .ft C #!py def run(): \(aq\(aq\(aq Install the django package \(aq\(aq\(aq return {\(aqinclude\(aq: [\(aqpython\(aq], \(aqdjango\(aq: {\(aqpkg\(aq: [\(aqinstalled\(aq]}} .ft P .fi .sp This is a very simple example, the first line has a SLS shebang line that tells Salt to not use the default renderer, but to use the \fBpy\fP renderer. Then the run function is defined, the return value from the run function must be a Salt friendly data structure, or better known as a Salt \fBHighState data structure\fP. .sp This Python example would look like this if it were written in YAML: .sp .nf .ft C include: \- python django: pkg.installed .ft P .fi .sp This clearly illustrates, that not only is using the YAML renderer a wise decision as the default, but that unbridled power can be obtained where needed by using a pure Python SLS. .SS Running and debugging salt states. .sp Once the rules in an SLS are ready, they need to be tested to ensure they work properly. To invoke the rules, simply execute \fBsalt \(aq*\(aq state.highstate\fP on the command line. If you get back just the hostnames with a \fI:\fP after, but no return, chances are there is a problem with the one or more of the sls files. Use the \fBsalt\-call\fP command: \fBsalt\-call state.highstate \-l debug\fP and examine the output for errors. This should help troubleshoot the issue. 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. .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 system please refer to the full \fBstates reference\fP. .sp This tutorial will walk you through using Salt to configure a minion to run the Apache HTTP server and to ensure the server is running. .sp \fBBefore continuing\fP make sure you have a working Salt installation by following the \fBinstallation\fP and the \fBconfiguration\fP instructions. .IP "Stuck?" .sp There are many ways to \fBget help from the Salt community\fP including our \fI\%mailing list\fP and our \fI\%IRC channel\fP #salt. .RE .SS Setting up the Salt State Tree .sp States are stored in text files on the master and transfered to the minions on demand via the master\(aqs File Server. The collection of state files make up the \fIState Tree\fP. .sp To start using a central state system in Salt you must first set up the Salt File Server. Edit your master config file (\fBfile_roots\fP) and uncomment the following lines: .sp .nf .ft C file_roots: base: \- /srv/salt .ft P .fi .IP Note If you are deploying on FreeBSD via ports, the \fBfile_roots\fP path defaults to \fB/usr/local/etc/salt/states\fP. .RE .sp Restart the Salt master in order to pick up this change: .sp .nf .ft C % pkill salt\-master % salt\-master \-d .ft P .fi .SS Preparing the Top File .sp On the master in the directory you uncommented in the previous step (\fB/srv/salt\fP by default), create a new file called \fBtop.sls\fP and add the following: .sp .nf .ft C base: \(aq*\(aq: \- webserver .ft P .fi .sp The \fItop file\fP is separated into environments (discussed later). The default environment is \fBbase\fP. Under the \fBbase\fP environment a collection of minion matches is defined; for now simply specify all hosts (\fB*\fP). .IP "Targeting minions" .sp The expressions can use any of the targeting mechanisms used by Salt — minions can be matched by glob, pcre regular expression, or by \fBgrains\fP. For example: .sp .nf .ft C base: \(aqos:Fedora\(aq: \- match: grain \- webserver .ft P .fi .RE .SS Create an \fBsls\fP module .sp In the same directory as your \fItop file\fP, create an empty file, called an \fISLS module\fP, named \fBwebserver.sls\fP. Type the following and save the file: .sp .nf .ft C apache: # ID declaration pkg: # state declaration \- installed # function declaration .ft P .fi .sp The first line, called the \fIID declaration\fP, is an arbitrary identifier. In this case it defines the name of the package to be installed. \fBNOTE:\fP the package name for the Apache httpd web server may differ on your OS or distro — for example, on Fedora it is \fBhttpd\fP but on Debian/Ubuntu it is \fBapache2\fP. .sp The second line, called the \fIstate declaration\fP, defines which of the Salt States we are using. In this example, we are using the \fBpkg state\fP to ensure that a given package is installed. .sp The third line, called the \fIfunction declaration\fP, defines which function in the \fBpkg state\fP module to call. .IP "Renderers" .sp States \fIsls\fP files can be written in many formats. Salt requires only a simple data structure and is not concerned with how that data structure is built. Templating languages and \fI\%DSLs\fP are a dime\-a\-dozen and everyone has a favorite. .sp Building the expected data structure is the job of Salt \fBrenderers\fP and they are dead\-simple to write. .sp In this tutorial we will be using YAML in Jinja2 templates, which is the default format. You can change the default by changing \fBrenderer\fP in the master configuration file. .RE .SS Install the package .sp Next, let\(aqs run the state we created. Open a terminal on the master and run: .sp .nf .ft C % salt \(aq*\(aq state.highstate .ft P .fi .sp Our master is instructing all targeted minions to run \fBstate.highstate\fP. When a minion executes a highstate call it will download the \fItop file\fP and attempt to match the expressions. When it does match an expression the modules listed for it will be downloaded, compiled, and executed. .sp Once completed, the minion will report back with a summary of all actions taken and all changes made. .IP "Troubleshooting Salt" .sp In case you don\(aqt see the expected output, the following tips can help you narrow down the problem. .INDENT 0.0 .TP .B Turn up logging Salt can be quite chatty when you change the logging setting to \fBdebug\fP: .sp .nf .ft C salt\-minion \-l debug .ft P .fi .TP .B Run the minion in the foreground By not starting the minion in daemon mode (\fI\-d\fP) you can view any output from the minion as it works: .sp .nf .ft C salt\-minion & .ft P .fi .UNINDENT .sp Increase the default timeout value when running \fBsalt\fP. For example, to change the default timeout to 60 seconds: .sp .nf .ft C salt \-t 60 .ft P .fi .sp For best results, combine all three: .sp .nf .ft C salt\-minion \-l debug & # On the minion salt \(aq*\(aq state.highstate \-t 60 # On the master .ft P .fi .RE .SS Next steps .sp This tutorial focused on getting a simple Salt States configuration working. \fBPart 2\fP will build on this example to cover more advanced \fIsls\fP syntax and will explore more of the states that ship with Salt. .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. .RE .sp In the \fBlast part\fP of the Salt States tutorial we covered the basics of installing a package. We will now modify our \fBwebserver.sls\fP file to have requirements, and use even more Salt States. .SS Call multiple States .sp You can specify multiple \fIstate declarations\fP under an \fIID declaration\fP. For example, a quick modification to our \fBwebserver.sls\fP to also start Apache if it is not running: .sp .nf .ft C apache: pkg: \- installed service: \- running .ft P .fi .sp Try stopping Apache before running \fBstate.highstate\fP once again and observe the output. .SS Expand the SLS module .sp As you have seen, SLS modules are appended with the file extension \fB.sls\fP and are referenced by name starting at the root of the state tree. An SLS module can be also defined as a directory. Demonstrate that now by creating a directory named \fBwebserver\fP and moving and renaming \fBwebserver.sls\fP to \fBwebserver/init.sls\fP. Your state directory should now resemble: .sp .nf .ft C |\- top.sls \(ga\- webserver/ \(ga\- init.sls .ft P .fi .IP "Organizing SLS modules" .sp You can place additional \fB.sls\fP files in a state file directory. This affords much cleaner organization of your state tree on the filesystem. For example, if we created a \fBwebserver/django.sls\fP file that module would be referenced as \fBwebserver.django\fP. .sp In addition, States provide powerful includes and extending functionality which we will cover in \fBPart 3\fP. .RE .SS Require other states .sp We now have a working installation of Apache so let\(aqs add an HTML file to customize our website. It isn\(aqt exactly useful to have a website without a webserver so we don\(aqt want Salt to install our HTML file until Apache is installed and running. Include the following at the bottom of your \fBwebserver/init.sls\fP file: .sp .nf .ft C apache: pkg: \- installed service: \- running /var/www/index.html: # ID declaration file: # state declaration \- managed # function \- source: salt://webserver/index.html # function arg \- require: # requisite declaration \- pkg: apache # requisite reference .ft P .fi .sp \fBline 7\fP is the \fIID declaration\fP. In this example it is the location we want to install our custom HTML file. (\fBNote:\fP the default location that Apache serves may differ from the above on your OS or distro. \fB/srv/www\fP could also be a likely place to look.) .sp \fBLine 8\fP the \fIstate declaration\fP. This example uses the Salt \fBfile state\fP. .sp \fBLine 9\fP is the \fIfunction declaration\fP. The \fBmanaged function\fP will download a file from the master and install it in the location specified. .sp \fBLine 10\fP is a \fIfunction arg declaration\fP which, in this example, passes the \fBsource\fP argument to the \fBmanaged function\fP. .sp \fBLine 11\fP is a \fIrequisite declaration\fP. .sp \fBLine 12\fP is a \fIrequisite reference\fP which refers to a state and an ID. In this example, it is referring to the \fBID declaration\fP from our example in \fBpart 1\fP. This declaration tells Salt not to install the HTML file until Apache is installed. .sp Next, create the \fBindex.html\fP file and save it in the \fBwebserver\fP directory: .sp .nf .ft C Salt rocks

This file brought to you by Salt

.ft P .fi .sp Last, call \fBstate.highstate\fP again and the minion will fetch and execute the highstate as well as our HTML file from the master using Salt\(aqs File Server: .sp .nf .ft C salt \(aq*\(aq state.highstate .ft P .fi .sp Verify that Apache is now serving your custom HTML. .IP "\fBrequire\fP vs. \fBwatch\fP" .sp There are two \fIrequisite declarations\fP, “require” and “watch”. Not every state supports “watch”. The \fBservice state\fP does support “watch” and will restart a service based on the watch condition. .sp For example, if you use Salt to install an Apache virtual host configuration file and want to restart Apache whenever that file is changed you could modify our Apache example from earlier as follows: .sp .nf .ft C /etc/httpd/extra/httpd\-vhosts.conf: file: \- managed \- source: salt://webserver/httpd\-vhosts.conf apache: pkg: \- installed service: \- running \- watch: \- file: /etc/httpd/extra/httpd\-vhosts.conf .ft P .fi .sp If the pkg and service names differ on your OS or distro of choice you can specify each one separately using a \fIname declaration\fP which explained in \fBPart 3\fP. .RE .SS Next steps .sp In \fBpart 3\fP we will discuss how to use includes, extends and templating to make a more complete State Tree configuration. .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. .RE .sp This part of the tutorial will cover more advanced templating and configuration techniques for \fBsls\fP files. .SS Templating SLS modules .sp SLS modules may require programming logic or inline execution. This is accomplished with module templating. The default module templating system used is \fI\%Jinja2\fP and may be configured by changing the \fBrenderer\fP value in the master config. .sp All states are passed through a templating system when they are initially read. To make use of the templating system, simply add some templating markup. An example of an sls module with templating markup may look like this: .sp .nf .ft C {% for usr in \(aqmoe\(aq,\(aqlarry\(aq,\(aqcurly\(aq %} {{ usr }}: user.present {% endfor %} .ft P .fi .sp This templated sls file once generated will look like this: .sp .nf .ft C moe: user.present larry: user.present curly: user.present .ft P .fi .SS Using Grains in SLS modules .sp Often times a state will need to behave differently on different systems. \fBSalt grains\fP objects are made available in the template context. The \fIgrains\fP can be used from within sls modules: .sp .nf .ft C apache: pkg.installed: {% if grains[\(aqos\(aq] == \(aqRedHat\(aq %} \- name: httpd {% elif grains[\(aqos\(aq] == \(aqUbuntu\(aq %} \- name: apache2 {% endif %} .ft P .fi .SS Calling Salt modules from templates .sp All of the Salt modules loaded by the minion are available within the templating system. This allows data to be gathered in real time on the target system. It also allows for shell commands to be run easily from within the sls modules. .sp The Salt module functions are also made available in the template context as \fBsalt\fP: .sp .nf .ft C {% for usr in \(aqmoe\(aq,\(aqlarry\(aq,\(aqcurly\(aq %} {{ usr }}: group: \- present user: \- present \- gid: {{ salt[\(aqfile.group_to_gid\(aq](usr) }} \- require: \- group: {{ usr }} {% endfor %} .ft P .fi .sp Below is an example that uses the \fBnetwork.hwaddr\fP function to retrieve the MAC address for eth0: .sp .nf .ft C salt[\(aqnetwork.hwaddr\(aq](\(aqeth0\(aq) .ft P .fi .SS Advanced SLS module syntax .sp Lastly, we will cover some incredibly useful techniques for more complex State trees. .SS \fIInclude declaration\fP .sp A previous example showed how to spread a Salt tree across several files. Similarly, \fIrequisite references\fP span multiple files by using an \fIinclude declaration\fP. For example: .sp \fBpython/python\-libs.sls\fP: .sp .nf .ft C python\-dateutil: pkg.installed .ft P .fi .sp \fBpython/django.sls\fP: .sp .nf .ft C include: \- python\-libs django: pkg.installed: \- require: \- pkg: python\-dateutil .ft P .fi .SS \fIExtend declaration\fP .sp You can modify previous declarations by using an \fIextend declaration\fP. For example the following modifies the Apache tree to also restart Apache when the vhosts file is changed: .sp \fBapache/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 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 .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 structure of the file_roots used in the Salt file server. Like the Salt file server the \fBpillar_roots\fP option in the master config is based on environments mapping to directories. The pillar data is then mapped to minions based on matchers in a top file which is laid out in the same way as the state top file. Salt pillars can use the same matcher types as the standard top file. .sp The configuration for the \fBpillar_roots\fP in the master config is identical in behavior and function as the \fBfile_roots\fP configuration: .sp .nf .ft C pillar_roots: base: \- /srv/pillar .ft P .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: .sp \fB/srv/pillar/top.sls\fP .sp .nf .ft C base: \(aq*\(aq: \- packages .ft P .fi .sp 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 .nf .ft C {% if grains[\(aqos\(aq] == \(aqRedHat\(aq %} apache: httpd git: git {% elif grains[\(aqos\(aq] == \(aqDebian\(aq %} apache: apache2 git: git\-core {% endif %} .ft P .fi .sp Now this data can be used from within modules, renderers, State SLS files, and more via the shared pillar \fI\%dict\fP: .sp .nf .ft C apache: pkg: \- installed \- name: {{ pillar[\(aqapache\(aq] }} .ft P .fi .sp .nf .ft C git: pkg: \- installed \- name: {{ pillar[\(aqgit\(aq] }} .ft P .fi .SS Viewing Minion Pillar .sp Once the pillar is set up the data can be viewed on the minion via the \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 # salt \(aq*\(aq pillar.data .ft P .fi .SS Footnotes .IP [1] 5 Note that you cannot just list key/value\-information in \fBtop.sls\fP. .SS Refreshing Pillar Data .sp When pillar data is changed on the master the minions need to refresh the data locally. This is done with the \fBsaltutil.refresh_pillar\fP function. .sp .nf .ft C 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 control and flexibility when targeting minions. .sp .nf .ft C salt \-I \(aqsomekey:specialvalue\(aq test.ping .ft P .fi .SH MASTER TOPS SYSTEM .sp In 0.10.4 the \fIexternal_nodes\fP system was upgraded to allow for modular subsystems to be used to generate the top file data for a highstate run on the master. .sp The old \fIexternal_nodes\fP option still works, but will be removed in the future in favor of the new \fImaster_tops\fP option which uses the modular system instead. The master tops system contains a number of subsystems that are loaded via the Salt loader interfaces like modules, states, returners, runners, etc. .sp Using the new \fImaster_tops\fP option is simple: .sp .nf .ft C master_tops: ext_nodes: cobbler\-external\-nodes .ft P .fi .SH JOB MANAGEMENT .sp New in version 0.9.7. .sp Since Salt executes jobs running on many systems, Salt needs to be able to manage jobs running on many systems. As of Salt 0.9.7, the capability was added for more advanced job management. .SS The Minion proc System .sp The Salt Minions now maintain a \fIproc\fP directory in the Salt cachedir, the \fIproc\fP directory maintains files named after the executed job ID. These files contain the information about the current running jobs on the minion and allow for jobs to be looked up. This is located in the \fIproc\fP directory under the cachedir, with a default configuration it is under \fI/var/cache/salt/proc\fP. .SS Functions in the saltutil Module .sp Salt 0.9.7 introduced a few new functions to the \fBsaltutil\fP module for managing jobs. These functions are: .INDENT 0.0 .IP 1. 3 \fBrunning\fP Returns the data of all running jobs that are found in the \fIproc\fP directory. .IP 2. 3 \fBfind_job\fP Returns specific data about a certain job based on job id. .IP 3. 3 \fBsignal_job\fP Allows for a given jid to be sent a signal. .IP 4. 3 \fBterm_job\fP Sends a termination signal (SIGTERM, 15) to the process controlling the specified job. .IP 5. 3 \fBkill_job\fP Sends a kill signal (SIGKILL, 9) to the process controlling the specified job. .UNINDENT .sp These functions make up the core of the back end used to manage jobs at the minion level. .SS The jobs Runner .sp A convenience runner front end and reporting system has been added as well. The jobs runner contains functions to make viewing data easier and cleaner. .sp The jobs runner contains a number of functions... .SS active .sp The active function runs saltutil.running on all minions and formats the return data about all running jobs in a much more usable and compact format. The active function will also compare jobs that have returned and jobs that are still running, making it easier to see what systems have completed a job and what systems are still being waited on. .sp .nf .ft C # salt\-run jobs.active .ft P .fi .SS lookup_jid .sp When jobs are executed the return data is sent back to the master and cached. By default is is cached for 24 hours, but this can be configured via the \fBkeep_jobs\fP option in the master configuration. Using the lookup_jid runner will display the same return data that the initial job invocation with the salt command would display. .sp .nf .ft C # salt\-run jobs.lookup_jid .ft P .fi .SS list_jobs .sp Before finding a historic job, it may be required to find the job id. list_jobs will parse the cached execution data and display all of the job data for jobs that have already, or partially returned. .sp .nf .ft C # salt\-run jobs.list_jobs .ft P .fi .SH SALT SCHEDULING .sp 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. .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. To set up a highstate to run on a minion every 60 minutes set this in the minion config or pillar: .sp .nf .ft C schedule: highstate: function: state.highstate minutes: 60 .ft P .fi .sp Time intervals can be specified as seconds, minutes, hours, or days. Runner executions can also be specified on the master within the master configuration file: .sp .nf .ft C schedule: overstate: function: state.over seconds: 35 minutes: 30 hours: 3 .ft P .fi .sp The above configuration will execute the state.over runner every 3 hours, 30 minutes and 35 seconds, or every 12,635 seconds. .sp The scheduler is also useful for tasks like gathering monitoring data about a minion, this schedule option will gather status data and send it to a mysql returner database: .sp .nf .ft C schedule: uptime: function: status.uptime seconds: 60 returner: mysql meminfo: function: status.meminfo minutes: 5 returner: mysql .ft P .fi .sp Since specifying the returner repeatedly can be tiresome, the \fIschedule_returner\fP option is available to specify one or a list of global returners to be used by the minions when scheduling. .SH RUNNING THE SALT MASTER AS UNPRIVILEGED USER .sp While the default setup runs the Salt Master as the root user, it is generally wise to run servers as an unprivileged user. In Salt 0.9.10 the management of the running user was greatly improved, the only change needed is to alter the option \fBuser\fP in the master configuration file and all salt system components will be updated to function under the new user when the master is started. .sp If running a version older that 0.9.10 then a number of files need to be owned by the user intended to run the master: .sp .nf .ft C # chown \-R /var/cache/salt # chown \-R /var/log/salt # chown \-R /etc/salt/pki .ft P .fi .SH TROUBLESHOOTING .sp The intent of the troubleshooting section is to introduce solutions to a number of common issues encountered by users and the tools that are available to aid in developing States and Salt code. .SS Running in the Foreground .sp A great deal of information is available via the debug logging system, if you are having issues with minions connecting or not starting run the minion and/or master in the foreground: .sp .nf .ft C # salt\-master \-l debug # salt\-minion \-l debug .ft P .fi .sp Anyone wanting to run Salt daemons via a process supervisor such as \fI\%monit\fP, \fI\%runit\fP, or \fI\%supervisord\fP, should omit the \fB\-d\fP argument to the daemons and run them in the foreground. .SS What Ports do the Master and Minion Need Open? .sp No ports need to be opened up on each minion. For the master, TCP ports 4505 and 4506 need to be open. If you\(aqve put both your Salt master and minion in debug mode and don\(aqt see an acknowledgement that your minion has connected, it could very well be a firewall. .sp You can check port connectivity from the minion with the nc command: .sp .nf .ft C # nc \-v \-z salt.master.ip 4505 # nc \-v \-z salt.master.ip 4506 .ft P .fi .sp There is also a \fBfirewall configuration\fP document that might help as well. .sp If you\(aqve enabled the right TCP ports on your operating system or Linux distribution\(aqs firewall and still aren\(aqt seeing connections, check that no additional access control system such as \fI\%SELinux\fP or \fI\%AppArmor\fP is blocking Salt. .SS Using salt\-call .sp The \fBsalt\-call\fP command was originally developed for aiding in the development of new Salt modules. Since then, many applications have been developed for running any Salt module locally on a minion. These range from the original intent of salt\-call, development assistance, to gathering more verbose output from calls like \fBstate.highstate\fP. .sp When developing the State Tree it is generally recommended to invoke state.highstate with salt\-call. This displays far more information about the highstate execution than calling it remotely. For even more verbosity, increase the loglevel with the same argument as \fBsalt\-minion\fP: .sp .nf .ft C salt\-call \-l debug state.highstate .ft P .fi .SS Too many open files .sp The salt\-master needs at least 2 sockets per host that connects to it, one for the Publisher and one for response port. Thus, large installations may, upon scaling up the number of minions accessing a given master, encounter: .sp .nf .ft C 12:45:29,289 [salt.master ][INFO ] Starting Salt worker process 38 Too many open files sock != \-1 (tcp_listener.cpp:335) .ft P .fi .sp The solution to this would be to check the number of files allowed to be opened by the user running salt\-master (root by default): .sp .nf .ft C [root@salt\-master ~]# ulimit \-n 1024 .ft P .fi .sp And modify that value to be at least equal to the number of minions x 2. This setting can be changed in limits.conf as the nofile value(s), and activated upon new a login of the specified user. .sp So, an environment with 1800 minions, would need 1800 x 2 = 3600 as a minimum. .SS Salt Master Stops Responding .sp There are known bugs with ZeroMQ versions less than 2.1.11 which can cause the Salt master to not respond properly. If you\(aqre running a ZeroMQ version greater than or equal to 2.1.9, you can work around the bug by setting the sysctls \fBnet.core.rmem_max\fP and \fBnet.core.wmem_max\fP to 16777216. Next, set the third field in \fBnet.ipv4.tcp_rmem\fP and \fBnet.ipv4.tcp_wmem\fP to at least 16777216. .sp You can do it manually with something like: .sp .nf .ft C # echo 16777216 > /proc/sys/net/core/rmem_max # echo 16777216 > /proc/sys/net/core/wmem_max # echo "4096 87380 16777216" > /proc/sys/net/ipv4/tcp_rmem # echo "4096 87380 16777216" > /proc/sys/net/ipv4/tcp_wmem .ft P .fi .sp Or with the following Salt state: .sp .nf .ft C net.core.rmem_max: sysctl: \- present \- value: 16777216 net.core.wmem_max: sysctl: \- present \- value: 16777216 net.ipv4.tcp_rmem: sysctl: \- present \- value: 4096 87380 16777216 net.ipv4.tcp_wmem: sysctl: \- present \- value: 4096 87380 16777216 .ft P .fi .SS Salt and SELinux .sp Currently there are no SELinux policies for Salt. For the most part Salt runs without issue when SELinux is running in Enforcing mode. This is because when the minion executes as a daemon the type context is changed to \fBinitrc_t\fP. The problem with SELinux arises when using salt\-call or running the minion in the foreground, since the type context stays \fBunconfined_t\fP. .sp This problem is generally manifest in the rpm install scripts when using the pkg module. Until a full SELinux Policy is available for Salt the solution to this issue is to set the execution context of \fBsalt\-call\fP and \fBsalt\-minion\fP to rpm_exec_t: .sp .nf .ft C # chcon \-t system_u:system_r:rpm_exec_t:s0 /usr/bin/salt\-minion # chcon \-t system_u:system_r:rpm_exec_t:s0 /usr/bin/salt\-call .ft P .fi .sp This works well, because the \fBrpm_exec_t\fP context has very broad control over other types. .SS Red Hat Enterprise Linux 5 .sp Salt requires Python 2.6 or 2.7. Red Hat Enterprise Linux 5 and its variants come with Python 2.4 installed by default. When installing on RHEL 5 from the \fI\%EPEL repository\fP this is handled for you. But, if you run Salt from git, be advised that its dependencies need to be installed from EPEL and that Salt needs to be run with the \fBpython26\fP executable. .SS Common YAML Gotchas .sp An extensive list of \fBYAML idiosyncrasies\fP has been compiled. .SS Live Python Debug Output .sp If the minion or master seems to be unresponsive, a SIGUSR1 can be passed to the processes to display where in the code they are running. If encountering a situation like this, this debug information can be invaluable. First make sure the master of minion are running in the foreground: .sp .nf .ft C # salt\-master \-l debug # salt\-minion \-l debug .ft P .fi .sp The pass the signal to the master or minion when it seems to be unresponsive: .sp .nf .ft C killall \-SIGUSR1 salt\-master killall \-SIGUSR1 salt\-minion .ft P .fi .sp When filing an issue or sending questions to the mailing list for a problem with an unresponsive daemon this information can be invaluable. .SH YAML IDIOSYNCRASIES .sp One of Salt\(aqs strengths, the use of existing serialization systems for representing SLS data, can also backfire. \fI\%YAML\fP is a general purpose system and there are a number of things that would seem to make sense in an sls file that cause YAML issues. It is wise to be aware of these issues. While reports or running into them are generally rare they can still crop up at unexpected times. .SS Spaces vs Tabs .sp \fI\%YAML uses spaces\fP, period. Do not use tabs in your SLS files! If strange errors are coming up in rendering SLS files, make sure to check that no tabs have crept in! In Vim, after enabling search highlighting with: \fB:set hlsearch\fP, you can check with the following key sequence in normal mode(you can hit \fIESC\fP twice to be sure): \fB/\fP, \fICtrl\-v\fP, \fITab\fP, then hit \fIEnter\fP. Also, you can convert tabs to 2 spaces by these commands in Vim: \fB:set tabstop=2 expandtab\fP and then \fB:retab\fP. .SS Indentation .sp The suggested syntax for YAML files is to use 2 spaces for indentation, but YAML will follow whatever indentation system that the individual file uses. Indentation of two spaces works very well for SLS files given the fact that the data is uniform and not deeply nested. .SS Nested Dicts (key=value) .sp When \fI\%dicts\fP: are more deeply nested, they no longer follow the same indentation logic. This is rarely something that comes up in Salt, since deeply nested options like these are discouraged when making State modules, but some do exist. A good example is the context and default options in the \fBfile.managed\fP state: .sp .nf .ft C /etc/http/conf/http.conf: file: \- managed \- source: salt://apache/http.conf \- user: root \- group: root \- mode: 644 \- template: jinja \- context: custom_var: "override" \- defaults: custom_var: "default value" other_var: 123 .ft P .fi .sp Notice that the spacing used is 2 spaces, and that when defining the context and defaults options there is a 4 space indent. If only a 2 space indent is used then the information will not be loaded correctly. If using double spacing is not desirable, then a deeply nested dict can be declared with curly braces: .sp .nf .ft C /etc/http/conf/http.conf: file: \- managed \- source: salt://apache/http.conf \- user: root \- group: root \- mode: 644 \- template: jinja \- context: { custom_var: "override" } \- defaults: { custom_var: "default value", other_var: 123 } .ft P .fi .SS Integers are Parsed as Integers .sp NOTE: This has been fixed in salt 0.10.0, as of this release passing an integer that is preceded by a 0 will be correctly parsed .sp When passing \fI\%integers\fP into an SLS file, they are passed as integers. This means that if a state accepts a string value and an integer is passed, that an integer will be sent. The solution here is to send the integer as a string. .sp This is best explained when setting the mode for a file: .sp .nf .ft C /etc/vimrc: file: \- managed \- source: salt://edit/vimrc \- user: root \- group: root \- mode: 644 .ft P .fi .sp Salt manages this well, since the mode is passed as 644, but if the mode is zero padded as 0644, then it is read by YAML as an integer and evaluated as an octal value, 0644 becomes 420. Therefore, if the file mode is preceded by a 0 then it needs to be passed as a string: .sp .nf .ft C /etc/vimrc: file: \- managed \- source: salt://edit/vimrc \- user: root \- group: root \- mode: \(aq0644\(aq .ft P .fi .SS YAML does not like "Double Short Decs" .sp If I can find a way to make YAML accept "Double Short Decs" then I will, since I think that double short decs would be awesome. So what is a "Double Short Dec"? It is when you declare a multiple short decs in one ID. Here is a standard short dec, it works great: .sp .nf .ft C vim: pkg.installed .ft P .fi .sp The short dec means that there are no arguments to pass, so it is not required to add any arguments, and it can save space. .sp YAML though, gets upset when declaring multiple short decs, for the record... .sp THIS DOES NOT WORK: .sp .nf .ft C vim: pkg.installed user.present .ft P .fi .sp Similarly declaring a short dec in the same ID dec as a standard dec does not work either... .sp ALSO DOES NOT WORK: .sp .nf .ft C fred: user.present ssh_auth.present: \- name: AAAAB3NzaC... \- user: fred \- enc: ssh\-dss \- require: \- user: fred .ft P .fi .sp The correct way is to define them like this: .sp .nf .ft C vim: pkg.installed: [] user.present: [] fred: user.present: [] ssh_auth.present: \- name: AAAAB3NzaC... \- user: fred \- enc: ssh\-dss \- require: \- user: fred .ft P .fi .sp Alternatively, they can be defined the "old way", or with multiple "full decs": .sp .nf .ft C vim: pkg: \- installed user: \- present fred: user: \- present ssh_auth: \- present \- name: AAAAB3NzaC... \- user: fred \- enc: ssh\-dss \- require: \- user: fred .ft P .fi .SS YAML support only plain ASCII .sp According to YAML specification, only ASCII characters can be used. .sp Within double\-quotes, special characters may be represented with C\-style escape sequences starting with a backslash ( \e ). .sp Examples: .sp .nf .ft C \- micro: "\eu00b5" \- copyright: "\eu00A9" \- A: "\ex41" \- alpha: "\eu0251" \- Alef: "\eu05d0" .ft P .fi .sp List of useable \fI\%Unicode characters\fP will help you to identify correct numbers. .sp Python can also be used to discover the Unicode number for a character: .sp .nf .ft C repr(u"Text with wrong characters i need to figure out") .ft P .fi .sp This shell command can find wrong characters in your SLS files: .sp .nf .ft C find . \-name \(aq*.sls\(aq \-exec grep \-\-color=\(aqauto\(aq \-P \-n \(aq[^\ex00\-\ex7F]\(aq \e{} \e; .ft P .fi .SH COMMUNITY .sp Join the Salt! .sp There are many ways to participate in and communicate with the Salt community. .sp Salt has an active IRC channel and a mailing list. .SS Mailing List .sp Join the \fI\%salt-users mailing list\fP. It is the best place to ask questions about Salt and see whats going on with Salt development! The Salt mailing list is hosted by Google Groups. It is open to new members. .sp \fI\%https://groups.google.com/forum/#!forum/salt-users\fP .SS IRC .sp The \fB#salt\fP IRC channel is hosted on the popular \fI\%Freenode\fP network. You can use the \fI\%Freenode webchat client\fP right from your browser. .sp \fI\%Logs of the IRC channel activity\fP are being collected courtesy of Moritz Lenz. .SS Salt development .sp If you wish to discuss the development of Salt itself join us in \fB#salt\-devel\fP. .SS Follow on Github .sp The Salt code is developed via Github. Follow Salt for constant updates on what is happening in Salt development: .sp \fI\%https://github.com/saltstack/salt\fP .SS The Red45 Blog .sp News and thoughts on Salt and related projects is often posted on Thomas\(aq blog \fI\%The Red45\fP: .sp \fI\%http://red45.wordpress.com/\fP .SS Example Salt States .sp The official \fBsalt\-states\fP repository is: \fI\%https://github.com/saltstack/salt-states\fP .sp A few examples of salt states from the community: .INDENT 0.0 .IP \(bu 2 \fI\%https://github.com/blast-hardcheese/blast-salt-states\fP .IP \(bu 2 \fI\%https://github.com/kevingranade/kevingranade-salt-state\fP .IP \(bu 2 \fI\%https://github.com/uggedal/states\fP .IP \(bu 2 \fI\%https://github.com/mattmcclean/salt-openstack/tree/master/salt\fP .IP \(bu 2 \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 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 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 changes to the fork, and then open up a pull request. .sp 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 First, make a local clone of your github fork of the salt github repo and make edits and changes locally. .sp Then, create a new branch on your clone by entering the following commands: .sp .nf .ft C git checkout \-b fixed\-broken\-thing Switched to a new branch \(aqfixed\-broken\-thing\(aq .ft P .fi .sp Choose a name for your branch that describes its purpose. .sp Now commit your changes to this new branch with the following command: .sp .nf .ft C #add and commit all changes at once git commit \-a \-m \(aqdescription of my fixes for the broken thing\(aq .ft P .fi .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 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 .nf .ft C virtualenv /path/to/your/virtualenv .ft P .fi .sp On Arch Linux, where Python 3 is the default installation of Python, use the \fBvirtualenv2\fP command instead of \fBvirtualenv\fP. .IP Note 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: .sp .nf .ft C source /path/to/your/virtualenv/bin/activate .ft P .fi .sp Install Salt (and dependencies) into the virtualenv: .sp .nf .ft C pip install M2Crypto # Don\(aqt install on Debian/Ubuntu (see below) pip install pyzmq PyYAML pycrypto msgpack\-python jinja2 psutil pip install \-e ./salt # the path to the salt git clone from above .ft P .fi .IP Note Installing M2Crypto .sp \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 env SWIG_FEATURES="\-cpperraswarn \-includeall \-D__\(gauname \-m\(ga__ \-I/usr/include/openssl" pip install M2Crypto .ft P .fi .sp 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: .sp .nf .ft C apt\-get install python\-m2crypto .ft P .fi .sp 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 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: .INDENT 0.0 .IP \(bu 2 \fI\%RHEL\fP and \fI\%CentOS\fP releases 6 and later .IP \(bu 2 \fI\%Fedora Linux\fP releases 11 and later .IP \(bu 2 \fI\%Amazon Linux\fP .UNINDENT .sp 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 During development it is easiest to be able to run the Salt master and minion that are installed in the virtualenv you created above, and also to have all the configuration, log, and cache files contained in the virtualenv as well. .sp Copy the master and minion config files into your virtualenv: .sp .nf .ft C mkdir \-p /path/to/your/virtualenv/etc/salt cp ./salt/conf/master /path/to/your/virtualenv/etc/salt/master cp ./salt/conf/minion /path/to/your/virtualenv/etc/salt/minion .ft P .fi .sp Edit the master config file: .INDENT 0.0 .IP 1. 3 Uncomment and change the \fBuser: root\fP value to your own user. .IP 2. 3 Uncomment and change the \fBroot_dir: /\fP value to point to \fB/path/to/your/virtualenv\fP. .IP 3. 3 If you are running version 0.11.1 or older, uncomment and change the \fBpidfile: /var/run/salt\-master.pid\fP value to point to \fB/path/to/your/virtualenv/salt\-master.pid\fP. .IP 4. 3 If you are also running a non\-development version of Salt you will have to change the \fBpublish_port\fP and \fBret_port\fP values as well. .UNINDENT .sp Edit the minion config file: .INDENT 0.0 .IP 1. 3 Repeat the edits you made in the master config for the \fBuser\fP and \fBroot_dir\fP values as well as any port changes. .IP 2. 3 If you are running version 0.11.1 or older, uncomment and change the \fBpidfile: /var/run/salt\-minion.pid\fP value to point to \fB/path/to/your/virtualenv/salt\-minion.pid\fP. .IP 3. 3 Uncomment and change the \fBmaster: salt\fP value to point at \fBlocalhost\fP. .IP 4. 3 Uncomment and change the \fBid:\fP value to something descriptive like "saltdev". This isn\(aqt strictly necessary but it will serve as a reminder of which Salt installation you are working with. .UNINDENT .IP Note Using \fIsalt\-call\fP with a \fBStandalone Minion\fP .sp If you plan to run \fIsalt\-call\fP with this self\-contained development environment in a masterless setup, you should invoke \fIsalt\-call\fP with \fB\-c /path/to/your/virtualenv/etc/salt\fP so that salt can find the minion config file. Without the \fB\-c\fP option, Salt finds its config files in \fI/etc/salt\fP. .RE .sp Start the master and minion, accept the minon\(aqs key, and verify your local Salt installation is working: .sp .nf .ft C cd /path/to/your/virtualenv salt\-master \-c ./etc/salt \-d salt\-minion \-c ./etc/salt \-d salt\-key \-c ./etc/salt \-L salt\-key \-c ./etc/salt \-A salt \-c ./etc/salt \(aq*\(aq test.ping .ft P .fi .sp Running the master and minion in debug mode can be helpful when developing. To do this, add \fB\-l debug\fP to the calls to \fBsalt\-master\fP and \fBsalt\-minion\fP. If you would like to log to the console instead of to the log file, remove the \fB\-d\fP. .sp Once the minion starts, you may see an error like the following: .sp .nf .ft C zmq.core.error.ZMQError: ipc path "/path/to/your/virtualenv/var/run/salt/minion/minion_event_7824dcbcfd7a8f6755939af70b96249f_pub.ipc" is longer than 107 characters (sizeof(sockaddr_un.sun_path)). .ft P .fi .sp This means the the path to the socket the minion is using is too long. This is a system limitation, so the only workaround is to reduce the length of this path. This can be done in a couple different ways: .INDENT 0.0 .IP 1. 3 Create your virtualenv in a path that is short enough. .IP 2. 3 Edit the \fBsock_dir\fP minion config variable and reduce its length. Remember that this path is relative to the value you set in \fBroot_dir\fP. .UNINDENT .sp \fBNOTE:\fP The socket path is limited to 107 characters on Solaris and Linux, and 103 characters on BSD\-based systems. .IP Note File descriptor limits .sp Ensure that the system open file limit is raised to at least 2047: .sp .nf .ft C # check your current limit ulimit \-n # raise the limit. persists only until reboot # use \(aqlimit descriptors 2047\(aq for c\-shell ulimit \-n 2047 .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: .sp .nf .ft C pip install mock .ft P .fi .sp If you are on Python < 2.7 then you will also need unittest2: .sp .nf .ft C pip install unittest2 .ft P .fi .sp Finally you use setup.py to run the tests with the following command: .sp .nf .ft C \&./setup.py test .ft P .fi .sp For greater control while running the tests, please try: .sp .nf .ft C \&./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 enhance Salt have been created. .SS Salt Sandbox .sp Created by Aaron Bull Schaefer, aka "elasticdog". .sp \fI\%https://github.com/elasticdog/salt-sandbox\fP .sp Salt Sandbox is a multi\-VM Vagrant\-based Salt development environment used for creating and testing new Salt state modules outside of your production environment. It\(aqs also a great way to learn firsthand about Salt and its remote execution capabilities. .sp Salt Sandbox will set up three separate virtual machines: .INDENT 0.0 .IP \(bu 2 salt.example.com \- the Salt master server .IP \(bu 2 minion1.example.com \- the first Salt minion machine .IP \(bu 2 minion2.example.com \- the second Salt minion machine .UNINDENT .sp These VMs can be used in conjunction to segregate and test your modules based on node groups, top file environments, grain values, etc. You can even test modules on different Linux distributions or release versions to better match your production infrastructure. .SH SALT EVENT SYSTEM .sp Salt 0.9.10 introduced the Salt Event System. This system is used to fire off events enabling third party applications or external processes to react to behavior within Salt. .sp The event system is comprised of a few components, the event sockets which publish events, and the event library which can listen to events and send events into the salt system. .SS Listening for Events .sp The event system is accessed via the event library and can only be accessed by the same system user that Salt is running as. To listen to events a SaltEvent object needs to be created and then the get_event function needs to be run. The SaltEvent object needs to know the location that the Salt unix sockets are kept. In the configuration this is the \fBsock_dir\fP option. The \fBsock_dir\fP option defaults to "/var/run/salt/master" on most systems. .sp The following code will check for a single event: .sp .nf .ft C import salt.utils.event event = salt.utils.event.MasterEvent(\(aq/var/run/salt/master\(aq) data = event.get_event() .ft P .fi .sp Events will also use a "tag". A "tag" allows for events to be filtered. By default all events will be returned, but if only authentication events are desired, then pass the tag "auth". Also, the get_event method has a default poll time assigned of 5 seconds, to change this time set the "wait" option. This example will only listen for auth events and will wait for 10 seconds instead of the default 5. .sp .nf .ft C import salt.utils.event event = salt.utils.event.MasterEvent(\(aq/var/run/salt/master\(aq) data = event.get_event(wait=10, tag=\(aqauth\(aq) .ft P .fi .sp Instead of looking for a single event, the iter_events method can be used to make a generator which will continually yield salt events. The iter_events method also accepts a tag, but not a wait time: .sp .nf .ft C import salt.utils.event event = salt.utils.event.MasterEvent(\(aq/var/run/salt/master\(aq) for data in event.iter_events(tag=\(aqauth\(aq): print(data) .ft P .fi .SH WRITING TESTS .sp Salt uses a test platform to verify functionality of components in a simple way. Two testing systems exist to enable testing salt functions in somewhat real environments. The two subsystems available are integration tests and unit tests. .sp Salt uses the python standard library unittest2 system for testing. .SS Integration Tests .sp The integration tests start up a number of salt daemons to test functionality in a live environment. These daemons include 2 salt masters, 1 syndic and 2 minions. This allows for the syndic interface to be tested and master/minion communication to be verified. All of the integration tests are executed as live salt commands sent through the started daemons. .INDENT 0.0 .IP \(bu 2 \fBWriting integration tests\fP .UNINDENT .sp Integration tests are particularly good at testing modules, states and shell commands. .SS Unit Tests .sp Direct unit tests are also available, these tests are good for internal functions. .SH INTEGRATION TESTS .sp The Salt integration tests come with a number of classes and methods which allow for components to be easily tested. These classes are generally inherited from and provide specific methods for hooking into the running integration test environment created by the integration tests. .sp It is noteworthy that since integration tests validate against a running environment that they are generally the preferred means to write tests. .sp The integration system is all located under tests/integration in the Salt source tree. .SS Integration Classes .sp The integration classes are located in tests/integration/__init__.py and can be extended therein. There are three classes available to extend: .SS ModuleCase .sp Used to define executions run via the master to minions and to call single modules and states. .sp The available methods are as follows: .INDENT 0.0 .TP .B run_function: Run a single salt function and condition the return down to match the behavior of the raw function call. This will run the command and only return the results from a single minion to verify. .TP .B state_result: Return the result data from a single state return .TP .B run_state: Run the state.single command and return the state return structure .UNINDENT .SS SyndicCase .sp Used to execute remote commands via a syndic, only used to verify the capabilities of the Syndic. .sp The available methods are as follows: .INDENT 0.0 .TP .B run_function: Run a single salt function and condition the return down to match the behavior of the raw function call. This will run the command and only return the results from a single minion to verify. .UNINDENT .SS ShellCase .sp Shell out to the scripts which ship with Salt. .sp The available methods are as follows: .INDENT 0.0 .TP .B run_script: Execute a salt script with the given argument string .TP .B run_salt: Execute the salt command, pass in the argument string as it would be passed on the command line. .TP .B run_run: Execute the salt\-run command, pass in the argument string as it would be passed on the command line. .TP .B run_run_plus: Execute Salt run and the salt run function and return the data from each in a dict .TP .B run_key: Execute the salt\-key command, pass in the argument string as it would be passed on the command line. .TP .B run_cp: Execute salt\-cp, pass in the argument string as it would be passed on the command line. .TP .B run_call: Execute salt\-call, pass in the argument string as it would be passed on the command line. .UNINDENT .SS Examples .SS Module Example via ModuleCase Class .sp Import the integration module, this module is already added to the python path by the test execution. Inherit from the \fBintegration.ModuleCase\fP class. The tests that execute against salt modules should be placed in the \fItests/integration/modules\fP directory so that they will be detected by the test system. .sp Now the workhorse method \fBrun_function\fP can be used to test a module: .sp .nf .ft C import os import integration class TestModuleTest(integration.ModuleCase): \(aq\(aq\(aq Validate the test module \(aq\(aq\(aq def test_ping(self): \(aq\(aq\(aq test.ping \(aq\(aq\(aq self.assertTrue(self.run_function(\(aqtest.ping\(aq)) def test_echo(self): \(aq\(aq\(aq test.echo \(aq\(aq\(aq self.assertEqual(self.run_function(\(aqtest.echo\(aq, [\(aqtext\(aq]), \(aqtext\(aq) .ft P .fi .sp ModuleCase can also be used to test states, when testing states place the test module in the \fItests/integration/states\fP directory. The \fBstate_result\fP and the \fBrun_state\fP methods are the workhorse here: .sp .nf .ft C import os import shutil import integration HFILE = os.path.join(integration.TMP, \(aqhosts\(aq) class HostTest(integration.ModuleCase): \(aq\(aq\(aq Validate the host state \(aq\(aq\(aq def setUp(self): shutil.copyfile(os.path.join(integration.FILES, \(aqhosts\(aq), HFILE) super(HostTest, self).setUp() def tearDown(self): if os.path.exists(HFILE): os.remove(HFILE) super(HostTest, self).tearDown() def test_present(self): \(aq\(aq\(aq host.present \(aq\(aq\(aq name = \(aqspam.bacon\(aq ip = \(aq10.10.10.10\(aq ret = self.run_state(\(aqhost.present\(aq, name=name, ip=ip) result = self.state_result(ret) self.assertTrue(result) with open(HFILE) as fp_: output = fp_.read() self.assertIn(\(aq{0}\et\et{1}\(aq.format(ip, name), output) .ft P .fi .sp The above example also demonstrates using the integration files and the integration state tree. The variable \fIintegration.FILES\fP will point to the directory used to store files that can be used or added to to help enable tests that require files. The location \fIintegration.TMP\fP can also be used to store temporary files that the test system will clean up when the execution finishes. .sp The integration state tree can be found at \fItests/integration/files/file/base\fP. This is where the referenced \fIhost.present\fP sls file resides. .SS Shell Example via ShellCase .sp Validating the shell commands can be done via shell tests. Here are some examples: .sp .nf .ft C import sys import shutil import tempfile import integration class KeyTest(integration.ShellCase): \(aq\(aq\(aq Test salt\-key script \(aq\(aq\(aq _call_binary_ = \(aqsalt\-key\(aq def test_list(self): \(aq\(aq\(aq test salt\-key \-L \(aq\(aq\(aq data = self.run_key(\(aq\-L\(aq) expect = [ \(aqUnaccepted Keys:\(aq, \(aqAccepted Keys:\(aq, \(aqminion\(aq, \(aqsub_minion\(aq, \(aqRejected:\(aq, \(aq\(aq] self.assertEqual(data, expect) .ft P .fi .sp This example verifies that the \fBsalt\-key\fP command executes and returns as expected by making use of the \fBrun_key\fP method. .sp All shell tests should be placed in the \fItests/integraion/shell\fP directory. .SH REACTOR SYSTEM .sp Salt version 0.11.0 introduced the reactor system. The premise behind the reactor system is that with Salt\(aqs events and the ability to execute commands a logic engine could be put in place to allow events to trigger actions, or more accurately, reactions. .sp 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 (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. The event system is a local ZeroMQ PUB interface which fires salt events. This event bus is an open system used for sending information notifying Salt and other systems about operations. .sp The event system fires events with a very specific criteria. Every event has a \fItag\fP which is comprised of a maximum of 20 characters. Event tags allow for fast top level filtering of events. In addition to the tag, an event has a data structure. This data structure is a dict containing information about the event. .SS Mapping Events to Reactor SLS Files .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 formulas (globs can be used for matching): .sp .nf .ft C reactor: \- \(aqauth\(aq: \- /srv/reactor/authreact1.sls \- /srv/reactor/authreact2.sls \- \(aqminion_start\(aq: \- /srv/reactor/start.sls .ft P .fi .sp When an event with a tag of auth is fired the reactor will catch the event and render the two listed files. The rendered files are standard sls files, so by default they are yaml + jinja. The jinja is packed with a few data structures similar to state and pillar sls files. The data available is found in the \fItag\fP and \fIdata\fP variables. The \fItag\fP variable is just the tag in the fired event and the \fIdata\fP variable is the event\(aqs data dict. Here is a simple reactor sls: .sp .nf .ft C {% if data[\(aqid\(aq] == \(aqmysql1\(aq %} highstate_run: cmd.state.highstate: \- tgt: mysql1 {% endif %} .ft P .fi .sp This simple reactor file uses jinja to further refine the reaction to be made. If the \fIid\fP in the event data is mysql1 (if the name of the minion is mysql1) then the following reaction is defined. The same data structure and compiler used for the state system is used for the reactor system. The only difference is that the data is matched up to the salt command api and the runner system. In this example a command is published to the mysql1 minion with a function of state.highstate. Similarly, a runner can be called: .sp .nf .ft C {% if data[\(aqdata\(aq][\(aqoverstate\(aq] == \(aqrefresh\(aq %} overstate_run: 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 PEP\-08 it is not completely PEP\-08. It is also noteworthy that a few development techniques are also employed which should be adhered to. In the end, the code is made to be "Salty". .sp Most importantly though, we will accept code that violates the coding style and KINDLY ask the contributor to fix it, or go ahead and fix the code on behalf of the contributor. Coding style is NEVER grounds to reject code contributions, and is never grounds to talk down to another member of the community (There are no grounds to treat others without respect, especially people working to improve Salt)!! .SS Strings .sp Salt follows a few rules when formatting strings: .SS Single Quotes .sp In Salt, all strings use single quotes unless there is a good reason not to. This means that docstrings use single quotes, standard strings use single quotes etc.: .sp .nf .ft C def foo(): \(aq\(aq\(aq A function that does things \(aq\(aq\(aq name = \(aqA name\(aq return name .ft P .fi .SS Formatting Strings .sp All strings which require formatting should use the \fI.format\fP string method: .sp .nf .ft C data = \(aqsome text\(aq more = \(aq{0} and then some\(aq.format(data) .ft P .fi .sp Make sure to use indices or identifiers in the format brackets, since empty brackets are not supported by python 2.6. .sp Please do NOT use printf formatting. .SS Docstring Conventions .sp Docstrings should always add a newline, docutils takes care of the new line and it makes the code cleaner and more vertical: .sp \fIGOOD\fP: .sp .nf .ft C def bar(): \(aq\(aq\(aq Here lies a docstring with a newline after the quotes and is the salty way to handle it! Vertical code is the way to go! \(aq\(aq\(aq return .ft P .fi .sp \fIBAD\fP: .sp .nf .ft C def baz(): \(aq\(aq\(aqThis is not ok!\(aq\(aq\(aq return .ft P .fi .SS Imports .sp Salt code prefers importing modules and not explicit functions. This is both a style and functional preference. The functional preference originates around the fact that the module import system used by pluggable modules will include callable objects (functions) that exist in the direct module namespace. This is not only messy, but may unintentionally expose code python libs to the Salt interface and pose a security problem. .sp To say this more directly with an example, this is \fIGOOD\fP: .sp .nf .ft C import os def minion_path(): path = os.path.join(self.opts[\(aqcachedir\(aq], \(aqminions\(aq) return path .ft P .fi .sp This on the other hand is \fIDISCOURAGED\fP: .sp .nf .ft C from os.path import join def minion_path(): path = join(self.opts[\(aqcachedir\(aq], \(aqminions\(aq) return path .ft P .fi .sp The time when this is changed is for importing exceptions, generally directly importing exceptions is preferred: .sp This is a good way to import exceptions: .sp .nf .ft C from salt.exceptions import CommandExecutionError .ft P .fi .SS Vertical is Better .sp When writing Salt code, vertical code is generally preferred. This is not a hard rule but more of a guideline. As PEP\-08 specifies Salt code should not exceed 79 characters on a line, but it is preferred to separate code out into more newlines in some cases for better readability: .sp .nf .ft C import os os.chmod( os.path.join(self.opts[\(aqsock_dir\(aq], \(aqminion_event_pub.ipc\(aq), 448 ) .ft P .fi .sp Where there are more line breaks, this is also apparent when constructing a function with many arguments, something very common in state functions for instance: .sp .nf .ft C def managed(name, source=None, source_hash=\(aq\(aq, user=None, group=None, mode=None, template=None, makedirs=False, context=None, replace=True, defaults=None, env=None, backup=\(aq\(aq, **kwargs): .ft P .fi .SS Code Churn .sp Many pull requests have been submitted that only churn code in the name of PEP\-08. Code churn is a leading source of bugs and is strongly discouraged. While style fixes are encouraged they should be isolated to a single file per commit, and the changes should be legitimate, if there are any questions about whether a style change is legitimate please reference this document and the official PEP\-08 (\fI\%http://www.python.org/dev/peps/pep-0008/\fP) document before changing code. Many claims that a change is PEP\-08 have been invalid, please double check before committing fixes. .SH SALT STACK GIT POLICY .sp The Salt Stack team follows a git policy to maintain stability and consistency with the repository. The git policy has been developed to encourage contributions and make contributing to Salt as easy as possible. Code contributors to Salt Stack projects DO NOT NEED TO READ THIS DOCUMENT, because all contributions come into Salt Stack via a single gateway to make it as easy as possible for contributors to give us code. .sp The primary rule of git management in Salt Stack is to make life easy on contributors and developers to send in code. Simplicity is always a goal! .SS New Code Entry .sp All new Salt Stack code is posted to the \fIdevelop\fP branch, this is the single point of entry. The only exception here is when a bugfix to develop cannot be cleanly merged into a release branch and the bugfix needs to be rewritten for the release branch. .SS Release Branching .sp Salt Stack maintains two types of releases, \fIFeature Releases\fP and \fIPoint Releases\fP. A feature release is managed by incrementing the first or second release point number, so 0.10.5 \-> 0.11.0 signifies a feature release and 0.11.0 \-> 0.11.1 signifies a point release, also a hypothetical 0.42.7 \-> 1.0.0 would also signify a feature release. .SS Feature Release Branching .sp Each feature release is maintained in a dedicated git branch derived from the last applicable release commit on develop. All file changes relevant to the feature release will be completed in the develop branch prior to the creation of the feature release branch. The feature release branch will be named after the relevant numbers to the feature release, which constitute the first two numbers. This means that the release branch for the 0.11.0 series is named 0.11. .sp A feature release branch is created with the following command: .sp .nf .ft C # git checkout \-b 0.11 # From the develop branch # git push origin 0.11 .ft P .fi .SS Point Releases .sp Each point release is derived from its parent release branch. Constructing point releases is a critical aspect of Salt development and is managed by members of the core development team. Point releases comprise bug and security fixes which are cherry picked from develop onto the aforementioned release branch. At the time when a core developer accepts a pull request a determination needs to be made if the commits in the pull request need to be backported to the release branch. Some simple criteria are used to make this determination: .INDENT 0.0 .IP \(bu 2 Is this commit fixing a bug? Backport .IP \(bu 2 Does this commit change or add new features in any way? Don\(aqt backport .IP \(bu 2 Is this a PEP8 or code cleanup commit? Don\(aqt backport .IP \(bu 2 Does this commit fix a security issue? Backport .UNINDENT .sp Determining when a point release is going to be made is up to the project leader (Thomas Hatch). Generally point releases are made every 1\-2 weeks or if there is a security fix they can be made sooner. .sp 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 to provide a foundation which can be used to solve problems. And the goal of Salt is to not assume what those problems might be. .sp One of the greatest benefit of developing Salt has been the vast array of ways in which people have wanted to use it, while the original intention was as a communication layer for a cloud controller Salt has been extended to facilitate so much more. .SS Client API .sp The primary interface used to extend Salt, is to simply use it. Salt executions can be called via the Salt client api, making programming master side solutions with Salt is easy. .SS Adding Loadable Plugins .sp Salt is comprised of a core platform that loads many types of easy to write plugins. The idea is to enable all of the breaking points in the Salt processes to have a point of pluggable interaction. This means that all of the main features of Salt can be extended, modified or used. .sp The breaking points and helping interfaces span from convenience master side executions to manipulating the flow of how data is handled by Salt. .SS Minion Execution Modules .sp The minion execution modules or just \fBmodules\fP are the core to what Salt is and does. These modules are found in: .sp \fI\%https://github.com/saltstack/salt/blob/develop/salt/modules\fP .sp These modules are what is called by the Salt command line and the salt client API. Adding modules is done by simply adding additional Python modules to the \fImodules\fP directory and restarting the minion. .SS Grains .sp Salt grains, or "grains of truth" are bits of static information that are generated when the minion starts. This information is useful when determining what package manager to default to, or where certain configuration files are stored on the minion. .sp The Salt grains are the interface used for auto detection and dynamic assignment of execution modules and types to specific Salt minions. .sp The code used to generate the Salt grains can be found here: .sp \fI\%https://github.com/saltstack/salt/blob/develop/salt/grains\fP .SS States .sp Salt supports state enforcement, this makes Salt a high speed and very efficient solution for system configuration management. .sp States can be easily added to Salt by dropping a new state module in: .sp \fI\%https://github.com/saltstack/salt/blob/develop/salt/states\fP .SS Renderers .sp Salt states are controlled by simple data structures, these structures can be abstracted in a number of ways. While the default is to be in a yaml file wrapped in a jinja template, any abstraction can be used. This means that any format that can be dreamed is possible, so long as a renderer is written for it. .sp The existing renderers can be found here: .sp \fI\%https://github.com/saltstack/salt/blob/develop/salt/renderers\fP .SS Returners .sp The Salt commands all produce a return value, that return value is sent to the Salt master by default, but it can be sent anywhere. The returner interface makes it programmatically possible for the information to be sent to anything from an SQL or NoSQL database, to a custom application made to use Salt. .sp The existing returners can be found here: .sp \fI\%https://github.com/saltstack/salt/blob/develop/salt/returners\fP .SS Runners .sp Sometimes a certain application can be made to execute and run from the existing Salt command line. This is where the Salt runners come into play. The Salt Runners what is called by the Salt\-run command and are meant to act as a generic interface for encapsulating master side executions. .sp Existing Salt runners are located here: .sp \fI\%https://github.com/saltstack/salt/blob/develop/salt/runners\fP .SH MODULES .sp Salt modules are the functions called by the \fBsalt\fP command. .IP "See also" .sp \fIFull list of builtin modules\fP .sp Salt ships with many modules that cover a wide variety of tasks. .RE .SS 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 \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 cannot be imported, the Salt minion will continue to load without issue and the module with errors will simply be omitted. .sp If adding a Cython module the file must be named \fB.pyx\fP so that the loader knows that the module needs to be imported as a Cython module. The compilation of the Cython module is automatic and happens when the minion starts, so only the \fB*.pyx\fP file is required. .SS Cross Calling Modules .sp All of the Salt modules are available to each other, and can be "cross called". This means that, when creating a module, functions in modules that already exist can be called. .sp The variable \fB__salt__\fP is packed into the modules after they are loaded into the Salt minion. This variable is a \fI\%Python dictionary\fP of all of the Salt functions, laid out in the same way that they are made available to the Salt command. .sp Salt modules can be cross called by accessing the value in the \fB__salt__\fP dict: .sp .nf .ft C def foo(bar): return __salt__[\(aqcmd.run\(aq](bar) .ft P .fi .sp This code will call the Salt cmd module\(aqs \fBrun\fP function and pass the argument \fBbar\fP. .SS Preloaded Modules Data .sp When interacting with modules often it is nice to be able to read information dynamically about the minion, or load in configuration parameters for a module. Salt allows for different types of data to be loaded into the modules by the minion, as of this writing Salt loads information gathered from the Salt Grains system and from the minion configuration file. .SS Grains Data .sp The Salt minion detects information about the system when started. This allows for modules to be written dynamically with respect to the underlying hardware and operating system. This information is referred to as Salt Grains, or "grains of salt". The Grains system was introduced to replace Facter, since relying on a Ruby application from a Python application was both slow and inefficient. Grains support replaces Facter in all Salt releases after 0.8 .sp The values detected by the Salt Grains on the minion are available in a \fI\%dict\fP named \fB__grains__\fP and can be accessed from within callable objects in the Python modules. .sp To see the contents of the grains dict for a given system in your deployment run the \fBgrains.items()\fP function: .sp .nf .ft C salt \(aqhostname\(aq grains.items .ft P .fi .sp To use the \fB__grains__\fP dict simply call it as a Python dict from within your code, an excellent example is available in the Grains module: \fBsalt.modules.grains\fP. .SS Module Configuration .sp Since parameters for configuring a module may be desired, Salt allows for configuration information stored in the main minion config file to be passed to the modules. .sp Since the minion configuration file is a YAML document, arbitrary configuration data can be passed in the minion config that is read by the modules. It is \fBstrongly\fP recommended that the values passed in the configuration file match the module. This means that a value intended for the \fBtest\fP module should be named \fBtest.\fP. .sp Configuration also requires that default configuration parameters need to be loaded as well. This can be done simply by adding the \fB__opts__\fP dict to the top level of the module. .sp The test module contains usage of the module configuration, and the default configuration file for the minion contains the information and format used to pass data to the modules. \fBsalt.modules.test\fP, \fBconf/minion\fP. .SS Printout Configuration .sp Since module functions can return different data, and the way the data is printed can greatly change the presentation, Salt has a printout configuration. .sp When writing a module the \fB__outputter__\fP dict can be declared in the module. The \fB__outputter__\fP dict contains a mapping of function name to Salt Outputter. .sp .nf .ft C __outputter__ = { \(aqrun\(aq: \(aqtxt\(aq } .ft P .fi .sp This will ensure that the text outputter is used. .SS Virtual Modules .sp Sometimes a module should be presented in a generic way. A good example of this can be found in the package manager modules. The package manager changes from one operating system to another, but the Salt module that interfaces with the package manager can be presented in a generic way. .sp The Salt modules for package managers all contain a \fB__virtual__\fP function which is called to define what systems the module should be loaded on. .sp The \fB__virtual__\fP function is used to return either a \fI\%string\fP or \fI\%False\fP. If False is returned then the module is not loaded, if a string is returned then the module is loaded with the name of the string. .sp This means that the package manager modules can be presented as the \fBpkg\fP module regardless of what the actual module is named. .sp The package manager modules are the best example of using the \fB__virtual__\fP function: \fI\%https://github.com/saltstack/salt/blob/develop/salt/modules/pacman.py\fP \fI\%https://github.com/saltstack/salt/blob/develop/salt/modules/yumpkg.py\fP \fI\%https://github.com/saltstack/salt/blob/develop/salt/modules/apt.py\fP .SS Documentation .sp Salt modules are self documenting, the \fBsys.doc()\fP function will return the documentation for all available modules: .sp .nf .ft C salt \(aq*\(aq sys.doc .ft P .fi .sp This function simple prints out the docstrings found in the modules, when writing Salt modules, please follow the formating conventions for docstrings as they appear in the other modules. .SS Adding Documentation to Salt Modules .sp Since life is much better with documentation, it is strongly suggested that all Salt modules have documentation added. Any Salt modules submitted for inclusion in the main distribution of Salt will be required to have documentation. .sp Documenting Salt modules is easy! Just add a \fI\%Python docstring\fP to the function. .sp .nf .ft C def spam(eggs): \(aq\(aq\(aq A function to make some spam with eggs! CLI Example:: salt \(aq*\(aq test.spam eggs \(aq\(aq\(aq return eggs .ft P .fi .sp Now when the sys.doc call is executed the docstring will be cleanly returned to the calling terminal. .SS Add Module metadata .sp Add information about the module using the following field lists: .sp .nf .ft C :maintainer: Thomas Hatch :maturity: new :depends: python\-mysqldb :platform: all .ft P .fi .sp The maintaner field is a comma\-delimited list of developers who help maintain this module. .sp The maturity field indicates the level of quality and testing for this module. Standard labels will be determined. .sp The depends field is a comma\-delimited list of modules that this module depends on. .sp The platform field is a comma\-delimited list of platforms that this modules is known to run on. .SS How Functions are Read .sp In Salt, Python callable objects contained within a module are made available to the Salt minion for use. The only exception to this rule is a callable object with a name starting with an underscore \fB_\fP. .SS Objects Loaded Into the Salt Minion .sp .nf .ft C def foo(bar): return bar class baz: def __init__(self, quo): pass .ft P .fi .SS Objects NOT Loaded into the Salt Minion .sp .nf .ft C def _foobar(baz): # Preceded with an _ return baz cheese = {} # Not a callable Python object .ft P .fi .SS Examples of Salt Modules .sp The existing Salt modules should be fairly easy to read and understand, the goal of the main distribution\(aqs Salt modules is not only to build a set of functions for Salt, but to stand as examples for building out more Salt modules. .sp The existing modules can be found here: \fI\%https://github.com/saltstack/salt/blob/develop/salt/modules\fP .sp The most simple module is the test module, it contains the simplest Salt function, \fBtest.ping\fP: .sp .nf .ft C def ping(): \(aq\(aq\(aq Just used to make sure the minion is up and responding Return True CLI Example:: salt \(aq*\(aq test.ping \(aq\(aq\(aq return True .ft P .fi .SH FULL LIST OF BUILTIN EXECUTION MODULES .IP "Virtual modules" .SS salt.modules.pkg .sp \fBpkg\fP is a virtual module that is fulfilled by one of the following modules: .INDENT 0.0 .IP \(bu 2 \fBsalt.modules.apt\fP .IP \(bu 2 \fBsalt.modules.ebuild\fP .IP \(bu 2 \fBsalt.modules.freebsdpkg\fP .IP \(bu 2 \fBsalt.modules.pacman\fP .IP \(bu 2 \fBsalt.modules.yumpkg\fP .IP \(bu 2 \fBsalt.modules.yumpkg5\fP .IP \(bu 2 \fBsalt.modules.zypper\fP .IP \(bu 2 \fBsalt.modules.brew\fP .IP \(bu 2 \fBsalt.modules.win_pkg\fP .UNINDENT .SS salt.modules.sys .sp The regular salt modules execute in a separate context from the salt minion and manipulating the actual salt modules needs to happen in a higher level context within the minion process. This is where the sys pseudo module is used. .sp The sys pseudo module comes with a few functions that return data about the available functions on the minion or allows for the minion modules to be refreshed. These functions are as follows: .INDENT 0.0 .TP .B salt.modules.sys.doc([module[, module.function]]) Display the inline documentation for all available modules, or for the specified module or function. .UNINDENT .INDENT 0.0 .TP .B salt.modules.sys.reload_modules() Instruct the minion to reload all available modules in memory. This function can be called if the modules need to be re\-evaluated for availability or new modules have been made available to the minion. .UNINDENT .INDENT 0.0 .TP .B salt.modules.sys.list_modules() List all available (loaded) modules. .UNINDENT .INDENT 0.0 .TP .B salt.modules.sys.list_functions() List all known functions that are in available (loaded) modules. .UNINDENT .RE .TS center; |l|l|. _ T{ \fBaliases\fP T} T{ Manage the information in the aliases file T} _ T{ \fBalternatives\fP T} T{ salt.modules.alternatives T} _ T{ \fBapache\fP T} T{ Support for Apache T} _ T{ \fBapt\fP T} T{ Support for APT (Advanced Packaging Tool) T} _ T{ \fBarchive\fP T} T{ A module to wrap archive calls T} _ T{ \fBat\fP T} T{ Wrapper module for at(1) T} _ T{ \fBaugeas_cfg\fP T} T{ Manages configuration files via augeas T} _ T{ \fBbluez\fP T} T{ Support for Bluetooth (using Bluez in Linux) T} _ T{ \fBbrew\fP T} T{ Homebrew for Mac OS X T} _ T{ \fBbutterkvm\fP T} T{ Specialized routines used by the butter cloud component T} _ T{ \fBcassandra\fP T} T{ Cassandra NoSQL Database Module T} _ T{ \fBcmdmod\fP T} T{ A module for shelling out T} _ T{ \fBconfig\fP T} T{ Return config information T} _ T{ \fBcp\fP T} T{ Minion side functions for salt\-cp T} _ T{ \fBcron\fP T} T{ Work with cron T} _ T{ \fBdaemontools\fP T} T{ daemontools service module. This module will create daemontools type T} _ T{ \fBdata\fP T} T{ Manage a local persistent data structure that can hold any arbitrary data T} _ T{ \fBdebconfmod\fP T} T{ Support for Debconf T} _ T{ \fBdebian_service\fP T} T{ Service support for Debian systems \- uses update\-rc.d and service to modify the system T} _ T{ \fBdisk\fP T} T{ Module for gathering disk information T} _ T{ \fBdjangomod\fP T} T{ Manage Django sites T} _ T{ \fBebuild\fP T} T{ Support for Portage T} _ T{ \fBeix\fP T} T{ Support for Eix T} _ T{ \fBevent\fP T} T{ Fire events on the minion, events can be fired up to the master T} _ T{ \fBextfs\fP T} T{ Module for managing ext2/3/4 file systems T} _ T{ \fBfile\fP T} T{ Manage information about files on the minion, set/read user, group, and mode T} _ T{ \fBfreebsdjail\fP T} T{ The jail module for FreeBSD T} _ T{ \fBfreebsdkmod\fP T} T{ Module to manage FreeBSD kernel modules T} _ T{ \fBfreebsdpkg\fP T} T{ Package support for FreeBSD T} _ T{ \fBfreebsdservice\fP T} T{ The service module for FreeBSD T} _ T{ \fBfreebsd_sysctl\fP T} T{ Module for viewing and modifying sysctl parameters T} _ T{ \fBgem\fP T} T{ Manage ruby gems. T} _ T{ \fBgentoolkitmod\fP T} T{ Support for Gentoolkit T} _ T{ \fBgentoo_service\fP T} T{ Top level package command wrapper, used to translate the os detected by the T} _ T{ \fBgit\fP T} T{ Support for the Git SCM T} _ T{ \fBglance\fP T} T{ Module for handling openstack glance calls. T} _ T{ \fBgrains\fP T} T{ Control aspects of the grains data T} _ T{ \fBgroupadd\fP T} T{ Manage groups on Linux and OpenBSD T} _ T{ \fBgrub_legacy\fP T} T{ Support for GRUB Legacy T} _ T{ \fBhg\fP T} T{ Support for the Mercurial SCM T} _ T{ \fBhosts\fP T} T{ Manage the information in the hosts file T} _ T{ \fBiptables\fP T} T{ Support for iptables T} _ T{ \fBkeyboard\fP T} T{ Module for managing keyboards on posix\-like systems. T} _ T{ \fBkeystone\fP T} T{ Module for handling openstack keystone calls. T} _ T{ \fBkmod\fP T} T{ Module to manage Linux kernel modules T} _ T{ \fBkvm_hyper\fP T} T{ Provide the hyper module for kvm hypervisors. T} _ T{ \fBlaunchctl\fP T} T{ Module for the management of MacOS systems that use launchd/launchctl T} _ T{ \fBlayman\fP T} T{ Support for Layman T} _ T{ \fBldapmod\fP T} T{ Module to provide LDAP commands via salt. T} _ T{ \fBlinux_acl\fP T} T{ Support for Linux File Access Control Lists T} _ T{ \fBlinux_lvm\fP T} T{ Support for Linux LVM2 T} _ T{ \fBlinux_sysctl\fP T} T{ Module for viewing and modifying sysctl parameters T} _ T{ \fBlocale\fP T} T{ Module for managing locales on posix\-like systems. T} _ T{ \fBmakeconf\fP T} T{ Support for modifying make.conf under Gentoo T} _ T{ \fBmdadm\fP T} T{ Salt module to manage RAID arrays with mdadm T} _ T{ \fBmongodb\fP T} T{ Module to provide MongoDB functionality to Salt T} _ T{ \fBmonit\fP T} T{ Monit service module. T} _ T{ \fBmoosefs\fP T} T{ Module for gathering and managing information about MooseFS T} _ T{ \fBmount\fP T} T{ Salt module to manage unix mounts and the fstab file T} _ T{ \fBmysql\fP T} T{ Module to provide MySQL compatibility to salt. T} _ T{ \fBnetwork\fP T} T{ Module for gathering and managing network information T} _ T{ \fBnginx\fP T} T{ Support for nginx T} _ T{ \fBnova\fP T} T{ Module for handling openstack nova calls. T} _ T{ \fBnzbget\fP T} T{ Support for nzbget T} _ T{ \fBopenbsdpkg\fP T} T{ Package support for OpenBSD T} _ T{ \fBopenbsdservice\fP T} T{ The service module for OpenBSD T} _ T{ \fBosxdesktop\fP T} T{ Mac OS X implementations of various commands in the "desktop" interface T} _ T{ \fBpacman\fP T} T{ A module to wrap pacman calls, since Arch is the best T} _ T{ \fBpam\fP T} T{ Support for pam T} _ T{ \fBparted\fP T} T{ Module for managing partitions on posix\-like systems. T} _ T{ \fBpecl\fP T} T{ Manage PHP pecl extensions. T} _ T{ \fBpillar\fP T} T{ Extract the pillar data for this minion T} _ T{ \fBpip\fP T} T{ Install Python packages with pip to either the system or a virtualenv T} _ T{ \fBpkgng\fP T} T{ Support for pkgng T} _ T{ \fBpkg_resource\fP T} T{ Resources needed by pkg providers T} _ T{ \fBpkgutil\fP T} T{ Pkgutil support for Solaris T} _ T{ \fBpostgres\fP T} T{ Module to provide Postgres compatibility to salt. T} _ T{ \fBpoudriere\fP T} T{ Support for poudriere T} _ T{ \fBps\fP T} T{ A salt interface to psutil, a system and process library. T} _ T{ \fBpublish\fP T} T{ Publish a command from a minion to a target T} _ T{ \fBpuppet\fP T} T{ Execute puppet routines T} _ T{ \fBpw_group\fP T} T{ Manage groups on FreeBSD T} _ T{ \fBpw_user\fP T} T{ Manage users with the useradd command T} _ T{ \fBrabbitmq\fP T} T{ Module to provide RabbitMQ compatibility to Salt. T} _ T{ \fBreg\fP T} T{ Manage the registry on Windows T} _ T{ \fBret\fP T} T{ Module to integrate with the returner system and retrieve data sent to a salt T} _ T{ \fBrh_ip\fP T} T{ The networking module for RHEL/Fedora based distros T} _ T{ \fBrh_service\fP T} T{ Service support for classic Red Hat type systems. This interface uses the T} _ T{ \fBrvm\fP T} T{ Manage ruby installations and gemsets with RVM, the Ruby Version Manager. T} _ T{ \fBsaltutil\fP T} T{ The Saltutil module is used to manage the state of the salt minion itself. It T} _ T{ \fBselinux\fP T} T{ Execute calls on selinux T} _ T{ \fBservice\fP T} T{ The default service module, if not otherwise specified salt will fall back T} _ T{ \fBshadow\fP T} T{ Manage the shadow file T} _ T{ \fBsmf\fP T} T{ Service support for Solaris 10 and 11, should work with other systems T} _ T{ \fBsolaris_group\fP T} T{ Manage groups on Solaris T} _ T{ \fBsolarispkg\fP T} T{ Package support for Solaris T} _ T{ \fBsolaris_shadow\fP T} T{ Manage the shadow file T} _ T{ \fBsolaris_user\fP T} T{ Manage users with the useradd command T} _ T{ \fBsolr\fP T} T{ Apache Solr Salt Module T} _ T{ \fBsqlite3\fP T} T{ Support for SQLite3 T} _ T{ \fBssh\fP T} T{ Manage client ssh components T} _ T{ \fBstate\fP T} T{ Control the state system on the minion T} _ T{ \fBstatus\fP T} T{ Module for returning various status data about a minion. T} _ T{ \fBsupervisord\fP T} T{ Provide the service module for supervisord T} _ T{ \fBsvn\fP T} T{ Subversion SCM T} _ T{ \fBsysbench\fP T} T{ The \(aqsysbench\(aq module is used to analyse the T} _ T{ \fBsysmod\fP T} T{ The sys module provides information about the available functions on the T} _ T{ \fBsystemd\fP T} T{ Provide the service module for systemd T} _ T{ \fBtest\fP T} T{ Module for running arbitrary tests T} _ T{ \fBtimezone\fP T} T{ Module for managing timezone on posix\-like systems. T} _ T{ \fBtls\fP T} T{ A salt module for SSL/TLS. T} _ T{ \fBtomcat\fP T} T{ Support for Tomcat T} _ T{ \fBupstart\fP T} T{ Module for the management of upstart systems. T} _ T{ \fBuseradd\fP T} T{ Manage users with the useradd command T} _ T{ \fBvirt\fP T} T{ Work with virtual machines managed by libvirt T} _ T{ \fBvirtualenv\fP T} T{ Create virtualenv environments T} _ T{ \fBwin_disk\fP T} T{ Module for gathering disk information on Windows T} _ T{ \fBwin_file\fP T} T{ Manage information about files on the minion, set/read user, group T} _ T{ \fBwin_groupadd\fP T} T{ Manage groups on Windows T} _ T{ \fBwin_network\fP T} T{ Module for gathering and managing network information T} _ T{ \fBwin_pkg\fP T} T{ A module to manage software on Windows T} _ T{ \fBwin_service\fP T} T{ Windows Service module. T} _ T{ \fBwin_shadow\fP T} T{ Manage the shadow file T} _ T{ \fBwin_status\fP T} T{ Module for returning various status data about a minion. T} _ T{ \fBwin_useradd\fP T} T{ Manage Windows users with the net user command T} _ T{ \fByumpkg5\fP T} T{ Support for YUM T} _ T{ \fByumpkg\fP T} T{ Support for YUM T} _ T{ \fBzpool\fP T} T{ zfs support. T} _ T{ \fBzypper\fP T} T{ Package support for openSUSE via the zypper package manager T} _ .TE .SS salt.modules.aliases .sp Manage the information in the aliases file .INDENT 0.0 .TP .B salt.modules.aliases.get_target(alias) Return the target associated with an alias .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq aliases.get_target .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.aliases.has_target(alias, target) Return true if the alias/target is set .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq aliases.has_target .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.aliases.list_aliases() Return the aliases found in the aliases file in this format: .sp .nf .ft C {\(aq\(aq: \(aq\(aq} .ft P .fi .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq aliases.list_aliases .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.aliases.rm_alias(alias) Remove an entry from the aliases file .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq aliases.rm_alias .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.aliases.set_target(alias, target) Set the entry in the aliases file for the given alias, this will overwrite any previous entry for the given alias or create a new one if it does not exist. .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq aliases.set_target .ft P .fi .UNINDENT .SS salt.modules.alternatives .SS salt.modules.alternatives .sp Support for Alternatives system .INDENT 0.0 .TP .B codeauthor Radek Rada <\fI\%radek.rada@gmail.com\fP> .TP .B copyright © 2012 by the SaltStack Team, see AUTHORS for more details. .TP .B license Apache 2.0, see LICENSE for more details. .UNINDENT .INDENT 0.0 .TP .B salt.modules.alternatives.check_installed(name, path) Check if the alternatives link is set to desired path. .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq alternatives.check_installed name path .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.alternatives.display(name) Display alternatives settings for defined command name. .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq alternatives.display .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.alternatives.install(name, link, path, priority) Install symbolic links determining default commands. .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq alternatives.install name link path priority .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.alternatives.remove(name, path) Remove symbolic links determining the default commands. .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq alternatives.remove name path .ft P .fi .UNINDENT .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 Support for Apache .INDENT 0.0 .TP .B salt.modules.apache.directives() Return list of directives together with expected arguments and places where the directive is valid (\fBapachectl \-L\fP) .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq apache.directives .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.apache.fullversion() Return server version from apachectl \-V .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq apache.fullversion .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.apache.modules() Return list of static and shared modules from apachectl \-M .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq apache.modules .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.apache.servermods() Return list of modules compiled into the server (apachectl \-l) .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq apache.servermods .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.apache.signal(signal=None) Signals httpd to start, restart, or stop. .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq apache.signal restart .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.apache.version() Return server version from apachectl \-v .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq apache.version .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.apache.vhosts() Show the settings as parsed from the config file (currently only shows the virtualhost settings). (\fBapachectl \-S\fP) Because each additional virtual host adds to the execution time, this command may require a long timeout be specified. .sp CLI Example: .sp .nf .ft C salt \-t 10 \(aq*\(aq apache.vhosts .ft P .fi .UNINDENT .SS salt.modules.apt .sp Support for APT (Advanced Packaging Tool) .INDENT 0.0 .TP .B salt.modules.apt.available_version(*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.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\-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 .INDENT 0.0 .TP .B salt.modules.apt.install(name=None, refresh=False, fromrepo=None, skip_verify=False, debconf=None, pkgs=None, sources=None, **kwargs) Install the passed package, add refresh=True to update the dpkg database. .INDENT 7.0 .TP .B name The name of the package to be installed. Note that this parameter is ignored if either "pkgs" or "sources" is passed. Additionally, please note that this option can only be used to install packages from a software repository. To install a package file manually, use the "sources" option. .INDENT 7.0 .TP .B CLI Example:: salt \(aq*\(aq pkg.install .UNINDENT .TP .B refresh Whether or not to refresh the package database before installing. .TP .B fromrepo Specify a package repository to install from (e.g., \fBapt\-get \-t unstable install somepackage\fP) .TP .B skip_verify Skip the GPG verification check (e.g., \fB\-\-allow\-unauthenticated\fP, or \fB\-\-force\-bad\-verify\fP for install from package file). .TP .B debconf Provide the path to a debconf answers file, processed before installation. .TP .B version Install a specific version of the package, e.g. 1.2.3~0ubuntu0. Ignored if "pkgs" or "sources" is passed. .UNINDENT .sp Multiple Package Installation Options: .INDENT 7.0 .TP .B pkgs A list of packages to install from a software repository. Must be 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": "1.2.3\-0ubuntu0"}]\(aq .UNINDENT .TP .B sources A list of DEB packages to install. Must be passed as a list of dicts, with the keys being package names, and the values being the source URI or local path to the package. .INDENT 7.0 .TP .B CLI Example:: salt \(aq*\(aq pkg.install sources=\(aq[{"foo": "salt://foo.deb"},{"bar": "salt://bar.deb"}]\(aq .UNINDENT .UNINDENT .sp Returns a dict containing the new package names and versions: .sp .nf .ft C {\(aq\(aq: {\(aqold\(aq: \(aq\(aq, \(aqnew\(aq: \(aq\(aq}} .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.apt.list_pkgs(regex_string=\(aq\(aq) List the packages currently installed in a dict: .sp .nf .ft C {\(aq\(aq: \(aq\(aq} .ft P .fi .sp External dependencies: .sp .nf .ft C Virtual package resolution requires aptitude. Without aptitude virtual packages will be reported as not installed. .ft P .fi .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq pkg.list_pkgs salt \(aq*\(aq pkg.list_pkgs httpd .ft P .fi .UNINDENT .INDENT 0.0 .TP .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: .sp .nf .ft C salt \(aq*\(aq pkg.list_upgrades .ft P .fi .UNINDENT .INDENT 0.0 .TP .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 Returns a list containing the names of the removed packages .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq pkg.purge .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.apt.refresh_db() Updates the APT database to latest packages based upon repositories .sp Returns a dict, 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 .nf .ft C salt \(aq*\(aq pkg.refresh_db .ft P .fi .UNINDENT .INDENT 0.0 .TP .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. .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq pkg.remove .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.apt.upgrade(refresh=True, **kwargs) Upgrades all packages via \fBapt\-get dist\-upgrade\fP .sp Returns a list of dicts containing the package names, and the new and old versions: .sp .nf .ft C [ {\(aq\(aq: {\(aqold\(aq: \(aq\(aq, \(aqnew\(aq: \(aq\(aq} }\(aq, ... ] .ft P .fi .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq pkg.upgrade .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.apt.upgrade_available(name) Check whether or not an upgrade is available for a given package .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq pkg.upgrade_available .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.apt.version(*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 .SS salt.modules.archive .sp A module to wrap archive calls .INDENT 0.0 .TP .B salt.modules.archive.gunzip(gzipfile, template=None) Uses the gunzip command to unpack gzip files .sp CLI Example to create \fB/tmp/sourcefile.txt\fP: .sp .nf .ft C salt \(aq*\(aq archive.gunzip /tmp/sourcefile.txt.gz .ft P .fi .sp The template arg can be set to \(aqjinja\(aq or another supported template engine to render the command arguments before execution. CLI Example: .sp .nf .ft C salt \(aq*\(aq archive.gunzip template=jinja /tmp/{{grains.id}}.txt.gz .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.archive.gzip(sourcefile, template=None) Uses the gzip command to create gzip files .sp CLI Example to create \fB/tmp/sourcefile.txt.gz\fP: .sp .nf .ft C salt \(aq*\(aq archive.gzip /tmp/sourcefile.txt .ft P .fi .sp The template arg can be set to \(aqjinja\(aq or another supported template engine to render the command arguments before execution. CLI Example: .sp .nf .ft C salt \(aq*\(aq archive.gzip template=jinja /tmp/{{grains.id}}.txt .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.archive.rar(rarfile, template=None, *sources) Uses the rar command to create rar files Uses rar for Linux from \fI\%http://www.rarlab.com/\fP .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq archive.rar /tmp/rarfile.rar /tmp/sourcefile1 /tmp/sourcefile2 .ft P .fi .sp The template arg can be set to \(aqjinja\(aq or another supported template engine to render the command arguments before execution. For example: .sp .nf .ft C salt \(aq*\(aq archive.rar template=jinja /tmp/rarfile.rar /tmp/sourcefile1 /tmp/{{grains.id}}.txt .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.archive.tar(options, tarfile, cwd=None, template=None, *sources) Uses the tar command to pack, unpack, etc tar files .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq archive.tar cjvf /tmp/tarfile.tar.bz2 /tmp/file_1 /tmp/file_2 .ft P .fi .sp The template arg can be set to \(aqjinja\(aq or another supported template engine to render the command arguments before execution. For example: .sp .nf .ft C salt \(aq*\(aq archive.tar template=jinja cjvf /tmp/salt.tar.bz2 {{grains.saltpath}} .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.archive.unrar(rarfile, dest, template=None, *xfiles) Uses the unrar command to unpack rar files Uses rar for Linux from \fI\%http://www.rarlab.com/\fP .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq archive.unrar /tmp/rarfile.rar /home/strongbad/ file_1 file_2 .ft P .fi .sp The template arg can be set to \(aqjinja\(aq or another supported template engine to render the command arguments before execution. For example: .sp .nf .ft C salt \(aq*\(aq archive.unrar template=jinja /tmp/rarfile.rar /tmp/{{grains.id}}/ file_1 file_2 .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.archive.unzip(zipfile, dest, template=None, *xfiles) Uses the unzip command to unpack zip files .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq archive.unzip /tmp/zipfile.zip /home/strongbad/ file_1 file_2 .ft P .fi .sp The template arg can be set to \(aqjinja\(aq or another supported template engine to render the command arguments before execution. For example: .sp .nf .ft C salt \(aq*\(aq archive.unzip template=jinja /tmp/zipfile.zip /tmp/{{grains.id}}/ file_1 file_2 .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.archive.zip(zipfile, template=None, *sources) Uses the zip command to create zip files .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq archive.zip /tmp/zipfile.zip /tmp/sourcefile1 /tmp/sourcefile2 .ft P .fi .sp The template arg can be set to \(aqjinja\(aq or another supported template engine to render the command arguments before execution. For example: .sp .nf .ft C salt \(aq*\(aq archive.zip template=jinja /tmp/zipfile.zip /tmp/sourcefile1 /tmp/{{grains.id}}.txt .ft P .fi .UNINDENT .SS salt.modules.at .sp Wrapper module for at(1) .sp Also, a \(aqtag\(aq feature has been added to more easily tag jobs. .INDENT 0.0 .TP .B salt.modules.at.at(*args, **kwargs) Add a job to the queue. .sp The \(aqtimespec\(aq follows the format documented in the at(1) manpage. .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq at.at [tag=] [runas=] salt \(aq*\(aq at.at 12:05am \(aq/sbin/reboot\(aq tag=reboot salt \(aq*\(aq at.at \(aq3:05am +3 days\(aq \(aqbin/myscript\(aq tag=nightly runas=jim .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.at.atc(jobid) Print the at(1) script that will run for the passed job id. This is mostly for debugging so the output will just be text. .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq at.atc .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.at.atq(tag=None) List all queued and running jobs or only those with an optional \(aqtag\(aq. .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq at.atq salt \(aq*\(aq at.atq [tag] salt \(aq*\(aq at.atq [job number] .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.at.atrm(*args) Remove jobs from the queue. .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq at.atrm .. salt \(aq*\(aq at.atrm all salt \(aq*\(aq at.atrm all [tag] .ft P .fi .UNINDENT .SS salt.modules.augeas_cfg .sp Manages configuration files via augeas .INDENT 0.0 .TP .B depends .INDENT 7.0 .IP \(bu 2 Augeas Python adapter .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.augeas_cfg.get(path, value=\(aq\(aq) Get a value for a specific augeas path .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq augeas.get /files/etc/hosts/1/ ipaddr .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.augeas_cfg.ls(path) List the direct children of a node .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq augeas.ls /files/etc/passwd .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.augeas_cfg.match(path, value=\(aq\(aq) Get matches for path expression .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq augeas.match /files/etc/services/service\-name ssh .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.augeas_cfg.remove(path) Get matches for path expression .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq augeas.remove /files/etc/sysctl.conf/net.ipv4.conf.all.log_martians .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.augeas_cfg.setvalue(*args) Set a value for a specific augeas path .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq augeas.setvalue /files/etc/hosts/1/canonical localhost .ft P .fi .sp This will set the first entry in /etc/hosts to localhost .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq augeas.setvalue /files/etc/hosts/01/ipaddr 192.168.1.1 \e /files/etc/hosts/01/canonical test .ft P .fi .sp Adds a new host to /etc/hosts the ip address 192.168.1.1 and hostname test .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq augeas.setvalue prefix=/files/etc/sudoers/ \e "spec[user = \(aq%wheel\(aq]/user" "%wheel" \e "spec[user = \(aq%wheel\(aq]/host_group/host" \(aqALL\(aq \e "spec[user = \(aq%wheel\(aq]/host_group/command[1]" \(aqALL\(aq \e "spec[user = \(aq%wheel\(aq]/host_group/command[1]/tag" \(aqPASSWD\(aq \e "spec[user = \(aq%wheel\(aq]/host_group/command[2]" \(aq/usr/bin/apt\-get\(aq \e "spec[user = \(aq%wheel\(aq]/host_group/command[2]/tag" NOPASSWD .ft P .fi .sp Ensures that the following line is present in /etc/sudoers: .sp .nf .ft C %wheel ALL = PASSWD : ALL , NOPASSWD : /usr/bin/apt\-get , /usr/bin/aptitude .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.augeas_cfg.tree(path) Returns recursively the complete tree of a node .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq augeas.tree /files/etc/ .ft P .fi .UNINDENT .SS salt.modules.bluez .sp Support for Bluetooth (using Bluez in Linux) .INDENT 0.0 .TP .B salt.modules.bluez.address() Get the many addresses of the Bluetooth adapter .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq bluetooth.address .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.bluez.pair(address, key) Pair the bluetooth adapter with a device .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq bluetooth.pair DE:AD:BE:EF:CA:FE 1234 .ft P .fi .sp Where DE:AD:BE:EF:CA:FE is the address of the device to pair with, and 1234 is the passphrase. .UNINDENT .INDENT 0.0 .TP .B salt.modules.bluez.scan() Scan for bluetooth devices in the area .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq bluetooth.scan .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.bluez.start() Start the bluetooth service. .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq bluetooth.start .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.bluez.stop() Stop the bluetooth service. .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq bluetooth.stop .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.bluez.unpair(address) Unpair the bluetooth adapter from a device .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq bluetooth.unpair DE:AD:BE:EF:CA:FE .ft P .fi .sp Where DE:AD:BE:EF:CA:FE is the address of the device to unpair. .UNINDENT .INDENT 0.0 .TP .B salt.modules.bluez.version() Return Bluez version from bluetoothd \-v .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq bluetoothd.version .ft P .fi .UNINDENT .SS salt.modules.brew .sp Homebrew for Mac OS X .INDENT 0.0 .TP .B salt.modules.brew.available_version(*names) Return the latest version of the named package available for upgrade or installation .sp Note that this currently not fully implemented but needs to return something to avoid a traceback when calling pkg.latest. .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.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 \(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.brew.install(name=None, pkgs=None, **kwargs) Install the passed package(s) with \fBbrew install\fP .INDENT 7.0 .TP .B name The name of the formula to be installed. Note that this parameter is ignored if "pkgs" is passed. .INDENT 7.0 .TP .B CLI Example:: salt \(aq*\(aq pkg.install .UNINDENT .UNINDENT .sp Multiple Package Installation Options: .INDENT 7.0 .TP .B pkgs A list of formulas to install. Must be passed as a python list. .INDENT 7.0 .TP .B CLI Example:: salt \(aq*\(aq pkg.install pkgs=\(aq["foo","bar"]\(aq .UNINDENT .UNINDENT .sp Returns a dict containing the new package names and versions: .sp .nf .ft C {\(aq\(aq: {\(aqold\(aq: \(aq\(aq, \(aqnew\(aq: \(aq\(aq}} .ft P .fi .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq pkg.install \(aqpackage package package\(aq .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.brew.list_pkgs(*args) List the packages currently installed in a dict: .sp .nf .ft C {\(aq\(aq: \(aq\(aq} .ft P .fi .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq pkg.list_pkgs .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.brew.list_upgrades() Check whether or not an upgrade is available for all packages .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq pkg.list_upgrades .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.brew.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: .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq pkg.remove .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.brew.upgrade_available(pkg) Check whether or not an upgrade is available for a given package .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq pkg.upgrade_available .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.brew.version(*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 .SS salt.modules.butterkvm .sp Specialized routines used by the butter cloud component .INDENT 0.0 .TP .B salt.modules.butterkvm.create(instance, vda, image, pin) Create a virtual machine, this is part of the butter vm system and assumes that the files prepared by butter are available via shared storage. AKA \- don\(aqt call this from the command line! .INDENT 7.0 .TP .B instance string The path to the instance directory for the given vm on shared storage .TP .B vda The location where the virtual machine image needs to be placed .TP .B image The image to move into place .TP .B pin A "pin" data structure defining the myriad of possible vdb\-vbz disk images to generate .UNINDENT .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq butterkvm.create \e .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.butterkvm.full_butter_data(local_path) Return the full virt info, but add butter data! .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq buttervm.full_butter_data .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.butterkvm.libvirt_creds() Returns the user and group that the disk images should be owned by .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq butterkvm.libvirt_creds .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.butterkvm.local_images(local_path) return the virtual machine names for all of the images located in the butter cloud\(aqs local_path in a list: .sp .nf .ft C [\(aqvm1.boo.com\(aq, \(aqvm2.foo.com\(aq] .ft P .fi .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq buttervm.local_images .ft P .fi .UNINDENT .SS salt.modules.cassandra .sp Cassandra NoSQL Database Module .INDENT 0.0 .TP .B depends .INDENT 7.0 .IP \(bu 2 pycassa Cassandra Python adapter .UNINDENT .TP .B configuration The location of the \(aqnodetool\(aq command, host, and thrift port needs to be specified via pillar: .sp .nf .ft C cassandra.nodetool: /usr/local/bin/nodetool cassandra.host: localhost cassandra.thrift_port: 9160 .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.cassandra.column_families(keyspace=None) Return existing column families for all keyspaces or just the provided one. .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq cassandra.column_families salt \(aq*\(aq cassandra.column_families .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.cassandra.column_family_definition(keyspace=None, column_family=None) Return a dictionary of column family definitions for the given keyspace/column_family .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq cassandra.column_family_definition .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.cassandra.compactionstats() Return compactionstats info .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq cassandra.compactionstats .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.cassandra.info() Return cassandra node info .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq cassandra.info .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.cassandra.keyspaces() Return existing keyspaces .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq cassandra.keyspaces .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.cassandra.netstats() Return netstats info .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq cassandra.netstats .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.cassandra.ring() Return cassandra ring info .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq cassandra.ring .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.cassandra.tpstats() Return tpstats info .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq cassandra.tpstats .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.cassandra.version() Return the cassandra version .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq cassandra.version .ft P .fi .UNINDENT .SS salt.modules.cmdmod .sp A module for shelling out .sp Keep in mind that this module is insecure, in that it can give whomever has access to the master root execution access to all salt minions .INDENT 0.0 .TP .B salt.modules.cmdmod.exec_code(lang, code, cwd=None) Pass in two strings, the first naming the executable language, aka \- python2, python3, ruby, perl, lua, etc. the second string containing the code you wish to execute. The stdout and stderr will be returned .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq cmd.exec_code ruby \(aqputs "cheese"\(aq .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.cmdmod.has_exec(cmd) Returns true if the executable is available on the minion, false otherwise .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq cmd.has_exec cat .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.cmdmod.retcode(cmd, cwd=None, runas=None, shell=\(aq/bin/zsh\(aq, env=(), template=None) Execute a shell command and return the command\(aqs return code. .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq cmd.retcode "file /bin/bash" .ft P .fi .sp The template arg can be set to \(aqjinja\(aq or another supported template engine to render the command arguments before execution. For example: .sp .nf .ft C salt \(aq*\(aq cmd.retcode template=jinja "file {{grains.pythonpath[0]}}/python" .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.cmdmod.run(cmd, cwd=None, runas=None, shell=\(aq/bin/zsh\(aq, env=(), template=None, rstrip=True) Execute the passed command and return the output as a string .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq cmd.run "ls \-l | awk \(aq/foo/{print $2}\(aq" .ft P .fi .sp The template arg can be set to \(aqjinja\(aq or another supported template engine to render the command arguments before execution. For example: .sp .nf .ft C salt \(aq*\(aq cmd.run template=jinja "ls \-l /tmp/{{grains.id}} | awk \(aq/foo/{print $2}\(aq" .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.cmdmod.run_all(cmd, cwd=None, runas=None, shell=\(aq/bin/zsh\(aq, env=(), template=None, rstrip=True) Execute the passed command and return a dict of return data .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq cmd.run_all "ls \-l | awk \(aq/foo/{print $2}\(aq" .ft P .fi .sp The template arg can be set to \(aqjinja\(aq or another supported template engine to render the command arguments before execution. For example: .sp .nf .ft C salt \(aq*\(aq cmd.run_all template=jinja "ls \-l /tmp/{{grains.id}} | awk \(aq/foo/{print $2}\(aq" .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.cmdmod.run_stderr(cmd, cwd=None, runas=None, shell=\(aq/bin/zsh\(aq, env=(), template=None, rstrip=True) Execute a command and only return the standard error .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq cmd.run_stderr "ls \-l | awk \(aq/foo/{print $2}\(aq" .ft P .fi .sp The template arg can be set to \(aqjinja\(aq or another supported template engine to render the command arguments before execution. For example: .sp .nf .ft C salt \(aq*\(aq cmd.run_stderr template=jinja "ls \-l /tmp/{{grains.id}} | awk \(aq/foo/{print $2}\(aq" .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.cmdmod.run_stdout(cmd, cwd=None, runas=None, shell=\(aq/bin/zsh\(aq, env=(), template=None, rstrip=True) Execute a command, and only return the standard out .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq cmd.run_stdout "ls \-l | awk \(aq/foo/{print $2}\(aq" .ft P .fi .sp The template arg can be set to \(aqjinja\(aq or another supported template engine to render the command arguments before execution. For example: .sp .nf .ft C salt \(aq*\(aq cmd.run_stdout template=jinja "ls \-l /tmp/{{grains.id}} | awk \(aq/foo/{print $2}\(aq" .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.cmdmod.script(source, args=None, cwd=None, runas=None, shell=\(aq/bin/zsh\(aq, env=\(aqbase\(aq, template=\(aqjinja\(aq, **kwargs) Download a script from a remote location and execute the script locally. The script can be located on the salt master file server or on an http/ftp server. .sp The script will be executed directly, so it can be written in any available programming language. .sp The script can also be formated as a template, the default is jinja. Arguments for the script can be specified as well. .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq cmd.script salt://scripts/runme.sh salt \(aq*\(aq cmd.script salt://scripts/runme.sh \(aqarg1 arg2 "arg 3"\(aq .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.cmdmod.script_retcode(source, cwd=None, runas=None, shell=\(aq/bin/zsh\(aq, env=\(aqbase\(aq, template=\(aqjinja\(aq, **kwargs) Download a script from a remote location and execute the script locally. The script can be located on the salt master file server or on an http/ftp server. .sp The script will be executed directly, so it can be written in any available programming language. .sp The script can also be formated as a template, the default is jinja. .sp Only evaluate the script return code and do not block for terminal output .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq cmd.script_retcode salt://scripts/runme.sh .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.cmdmod.which(cmd) Returns the path of an executable available on the minion, None otherwise .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq cmd.which cat .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.cmdmod.which_bin(cmds) Returns the first command found in a list of commands .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq cmd.which_bin \(aq[pip2, pip, pip\-python]\(aq .ft P .fi .UNINDENT .SS salt.modules.config .sp Return config information .INDENT 0.0 .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 Minion side functions for salt\-cp .INDENT 0.0 .TP .B salt.modules.cp.cache_dir(path, env=\(aqbase\(aq, include_empty=False) Download and cache everything under a directory from the master .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq cp.cache_dir salt://path/to/dir .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.cp.cache_file(path, env=\(aqbase\(aq) Used to cache a single file in the local salt\-master file cache. .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq cp.cache_file salt://path/to/file .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.cp.cache_files(paths, env=\(aqbase\(aq) Used to gather many files from the master, the gathered files will be saved in the minion cachedir reflective to the paths retrieved from the master. .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq cp.cache_files salt://pathto/file1,salt://pathto/file1 .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.cp.cache_local_file(path) Cache a local file on the minion in the localfiles cache .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq cp.cache_local_file /etc/hosts .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.cp.cache_master(env=\(aqbase\(aq) Retrieve all of the files on the master and cache them locally .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq cp.cache_master .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.cp.get_dir(path, dest, env=\(aqbase\(aq, template=None, gzip=None) Used to recursively copy a directory from the salt master .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq cp.get_dir salt://path/to/dir/ /minion/dest .ft P .fi .sp get_dir supports the same template and gzip arguments as get_file. .UNINDENT .INDENT 0.0 .TP .B salt.modules.cp.get_file(path, dest, env=\(aqbase\(aq, makedirs=False, template=None, gzip=None) Used to get a single file from the salt master .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq cp.get_file salt://path/to/file /minion/dest .ft P .fi .sp Template rendering can be enabled on both the source and destination file names like so: .sp .nf .ft C salt \(aq*\(aq cp.get_file "salt://{{grains.os}}/vimrc" /etc/vimrc template=jinja .ft P .fi .sp This example would instruct all Salt minions to download the vimrc from a directory with the same name as their os grain and copy it to /etc/vimrc .sp For larger files, the cp.get_file module also supports gzip compression. Because gzip is CPU\-intensive, this should only be used in scenarios where the compression ratio is very high (e.g. pretty\-printed JSON or YAML files). .sp Use the \fIgzip\fP named argument to enable it. Valid values are 1..9, where 1 is the lightest compression and 9 the heaviest. 1 uses the least CPU on the master (and minion), 9 uses the most. .UNINDENT .INDENT 0.0 .TP .B salt.modules.cp.get_file_str(path, env=\(aqbase\(aq) Return the contents of a file from a url .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq cp.get_file_str salt://my/file .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.cp.get_template(path, dest, template=\(aqjinja\(aq, env=\(aqbase\(aq, **kwargs) Render a file as a template before setting it down .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq cp.get_template salt://path/to/template /minion/dest .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.cp.get_url(path, dest, env=\(aqbase\(aq) Used to get a single file from a URL. .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq cp.get_url salt://my/file /tmp/mine salt \(aq*\(aq cp.get_url http://www.slashdot.org /tmp/index.html .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.cp.hash_file(path, env=\(aqbase\(aq) Return the hash of a file, to get the hash of a file on the salt master file server prepend the path with salt:// otherwise, prepend the file with / for a local file. .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq cp.hash_file salt://path/to/file .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.cp.is_cached(path, env=\(aqbase\(aq) Return a boolean if the given path on the master has been cached on the minion .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq cp.is_cached salt://path/to/file .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.cp.list_master(env=\(aqbase\(aq) List all of the files stored on the master .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq cp.list_master .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.cp.list_master_dirs(env=\(aqbase\(aq) List all of the directories stored on the master .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq cp.list_master_dirs .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.cp.list_minion(env=\(aqbase\(aq) List all of the files cached on the minion .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq cp.list_minion .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.cp.list_states(env=\(aqbase\(aq) List all of the available state modules in an environment .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq cp.list_states .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.cp.recv(files, dest) Used with salt\-cp, pass the files dict, and the destination. .sp This function receives small fast copy files from the master via salt\-cp .sp CLI Example: .sp .nf .ft C This function does not work via the CLI .ft P .fi .UNINDENT .SS salt.modules.cron .sp Work with cron .INDENT 0.0 .TP .B salt.modules.cron.list_tab(user) Return the contents of the specified user\(aqs crontab .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq cron.list_tab root .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.cron.ls(user) Return the contents of the specified user\(aqs crontab .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq cron.list_tab root .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.cron.raw_cron(user) Return the contents of the user\(aqs crontab .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq cron.raw_cron root .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.cron.rm(user, minute, hour, dom, month, dow, cmd) Remove a cron job for a specified user. .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq cron.rm_job root \e* \e* \e* \e* 1 /usr/local/weekly .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.cron.rm_env(user, name) Remove cron environment variable for a specified user. .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq cron.rm_env root MAILTO .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.cron.rm_job(user, minute, hour, dom, month, dow, cmd) Remove a cron job for a specified user. .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq cron.rm_job root \e* \e* \e* \e* 1 /usr/local/weekly .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.cron.set_env(user, name, value=None) Set up an environment variable in the crontab. .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq cron.set_env root MAILTO user@example.com .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.cron.set_job(user, minute, hour, dom, month, dow, cmd) Sets a cron job up for a specified user. .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq cron.set_job root \e* \e* \e* \e* 1 /usr/local/weekly .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.cron.set_special(user, special, cmd) Set up a special command in the crontab. .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq cron.set_special @hourly \(aqecho foobar\(aq .ft P .fi .UNINDENT .INDENT 0.0 .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 daemontools service module. This module will create daemontools type service watcher. This module is states.service compatible so it can be used to maintain service state via provider interface: .INDENT 0.0 .INDENT 3.5 .INDENT 0.0 .IP \(bu 2 provider: daemontools .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .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 .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq daemontools.get_all .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.daemontools.reload(name) 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 .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq daemontools.restart .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.daemontools.start(name, enable=None, sig=None) Starts service via daemontools .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq daemontools.start .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.daemontools.status(name, sig=None) Return the status for a service via daemontools, return pid if running .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq daemontools.status .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.daemontools.stop(name, enable=None, sig=None) Stops service via daemontools .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq daemontools.stop .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.daemontools.term(name) Send a TERM to service via daemontools .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq daemontools.term .ft P .fi .UNINDENT .SS salt.modules.data .sp Manage a local persistent data structure that can hold any arbitrary data specific to the minion .INDENT 0.0 .TP .B salt.modules.data.clear() Clear out all of the data in the minion datastore, this function is destructive! .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq data.clear .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.data.dump(new_data) Replace the entire datastore with a passed data structure .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq data.dump \(aq{\(aqeggs\(aq: \(aqspam\(aq}\(aq .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.data.getval(key) Get a value from the minion datastore .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq data.getval .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.data.getvals(*keys) Get values from the minion datastore .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq data.getvals [ ...] .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.data.load() Return all of the data in the minion datastore .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq data.load .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.data.update(key, value) Update a key with a value in the minion datastore .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq data.update .ft P .fi .UNINDENT .SS salt.modules.debconfmod .sp Support for Debconf .INDENT 0.0 .TP .B salt.modules.debconfmod.get_selections(fetchempty=True) Answers to debconf questions for all packages in the following format: .sp .nf .ft C {\(aqpackage\(aq: [[\(aqquestion\(aq, \(aqtype\(aq, \(aqvalue\(aq], ...]} .ft P .fi .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq debconf.get_selections .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.debconfmod.set(package, question, type, value, *extra) Set answers to debconf questions for a package. .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq debconf.set [ ...] .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.debconfmod.set_file(path) Set answers to debconf questions from a file. .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq debconf.set_file salt://pathto/pkg.selections .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.debconfmod.show(name) Answers to debconf questions for a package in the following format: .sp .nf .ft C [[\(aqquestion\(aq, \(aqtype\(aq, \(aqvalue\(aq], ...] .ft P .fi .sp If debconf doesn\(aqt know about a package, we return None. .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq debconf.show .ft P .fi .UNINDENT .SS salt.modules.debian_service .sp Service support for Debian systems \- uses update\-rc.d and service to modify the system .INDENT 0.0 .TP .B salt.modules.debian_service.disable(name, **kwargs) Disable the named service to start at boot .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq service.disable .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.debian_service.disabled(name) Return True if the named servioce is enabled, false otherwise .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq service.disabled .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.debian_service.enable(name, **kwargs) Enable the named service to start at boot .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq service.enable .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.debian_service.enabled(name) Return True if the named servioce is enabled, false otherwise .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq service.enabled .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.debian_service.force_reload(name) Force\-reload the named service .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq service.force_reload .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.debian_service.get_all() Return all available boot services .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq service.get_all .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.debian_service.get_disabled() Return a set of services that are installed but disabled .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq service.get_disabled .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.debian_service.get_enabled() Return a list of service that are enabled on boot .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq service.get_enabled .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.debian_service.reload(name) Reload the named service .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq service.reload .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.debian_service.restart(name) Restart the named service .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq service.restart .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.debian_service.start(name) Start the specified service .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq service.start .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.debian_service.status(name, sig=None) Return the status for a service, pass a signature to use to find the service via ps .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq service.status .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.debian_service.stop(name) Stop the specified service .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq service.stop .ft P .fi .UNINDENT .SS salt.modules.disk .sp Module for gathering disk information .INDENT 0.0 .TP .B salt.modules.disk.inodeusage(args=None) Return inode usage information for volumes mounted on this minion .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq disk.inodeusage .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.disk.usage(args=None) Return usage information for volumes mounted on this minion .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq disk.usage .ft P .fi .UNINDENT .SS salt.modules.djangomod .sp Manage Django sites .INDENT 0.0 .TP .B salt.modules.djangomod.collectstatic(settings_module, bin_env=None, no_post_process=False, ignore=None, dry_run=False, clear=False, link=False, no_default_ignore=False, pythonpath=None) Collect static files from each of your applications into a single location that can easily be served in production. .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq django.collectstatic settings.py .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.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 .B salt.modules.djangomod.createsuperuser(settings_module, username, email, bin_env=None, database=None, pythonpath=None) Create a super user for the database. This function defaults to use the \fB\-\-noinput\fP flag which prevents the creation of a password for the superuser. .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq django.createsuperuser settings.py user user@example.com .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.djangomod.loaddata(settings_module, fixtures, bin_env=None, database=None, pythonpath=None) Load fixture data .INDENT 7.0 .TP .B Fixtures: comma separated list of fixtures to load .UNINDENT .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq django.loaddata settings.py .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.djangomod.syncdb(settings_module, bin_env=None, migrate=False, database=None, pythonpath=None, noinput=True) Run syncdb .sp Execute the Django\-Admin syncdb command, if South is available on the minion the \fBmigrate\fP option can be passed as \fBTrue\fP calling the migrations to run after the syncdb completes .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq django.syncdb settings.py .ft P .fi .UNINDENT .SS salt.modules.ebuild .sp Support for Portage .INDENT 0.0 .TP .B optdepends .INDENT 7.0 .IP \(bu 2 portage Python adapter .UNINDENT .UNINDENT .sp For now all package names \fIMUST\fP include the package category, i.e. \fB\(aqvim\(aq\fP will not work, \fB\(aqapp\-editors/vim\(aq\fP will. .INDENT 0.0 .TP .B salt.modules.ebuild.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.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 \(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, 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 CLI Example: .sp .nf .ft C salt \(aq*\(aq pkg.depclean .ft P .fi .UNINDENT .INDENT 0.0 .TP .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 .TP .B name The name of the package to be installed. Note that this parameter is ignored if either "pkgs" or "sources" is passed. Additionally, please note that this option can only be used to emerge a package from the portage tree. To install a tbz2 package manually, use the "sources" option described below. .INDENT 7.0 .TP .B CLI Example:: salt \(aq*\(aq pkg.install .UNINDENT .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: .INDENT 7.0 .TP .B pkgs A list of packages to install from the portage tree. Must be passed as a python list. .INDENT 7.0 .TP .B CLI Example:: salt \(aq*\(aq pkg.install pkgs=\(aq["foo","bar"]\(aq .UNINDENT .TP .B sources A list of tbz2 packages to install. Must be passed as a list of dicts, with the keys being package names, and the values being the source URI or local path to the package. .INDENT 7.0 .TP .B CLI Example:: salt \(aq*\(aq pkg.install sources=\(aq[{"foo": "salt://foo.tbz2"},{"bar": "salt://bar.tbz2"}]\(aq .UNINDENT .UNINDENT .sp Returns a dict containing the new package names and versions: .sp .nf .ft C {\(aq\(aq: {\(aqold\(aq: \(aq\(aq, \(aqnew\(aq: \(aq\(aq}} .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.ebuild.list_pkgs() List the packages currently installed in a dict: .sp .nf .ft C {\(aq\(aq: \(aq\(aq} .ft P .fi .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq pkg.list_pkgs .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.ebuild.list_upgrades(refresh=True) List all available package upgrades. .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq pkg.list_upgrades .ft P .fi .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 provided for packages that have several versions in the portage tree, but rather the name of the package (i.e. "dev\-python/paramiko"). .UNINDENT .INDENT 0.0 .TP .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 Return a list containing the removed packages: .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq pkg.purge .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.ebuild.refresh_db() Updates the portage tree (emerge \-\-sync). Uses eix\-sync if available. .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq pkg.refresh_db .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.ebuild.remove(pkg, 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 CLI Example: .sp .nf .ft C salt \(aq*\(aq pkg.remove .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.ebuild.update(pkg, 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 .nf .ft C {\(aq\(aq: {\(aqold\(aq: \(aq\(aq, \(aqnew\(aq: \(aq\(aq}} .ft P .fi .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq pkg.update .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.ebuild.upgrade(refresh=True) Run a full system upgrade (emerge \-\-update world) .sp Return a dict containing the new package names and versions: .sp .nf .ft C {\(aq\(aq: {\(aqold\(aq: \(aq\(aq, \(aqnew\(aq: \(aq\(aq}} .ft P .fi .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq pkg.upgrade .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.ebuild.upgrade_available(name) Check whether or not an upgrade is available for a given package .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq pkg.upgrade_available .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.ebuild.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 .SS salt.modules.eix .sp Support for Eix .INDENT 0.0 .TP .B salt.modules.eix.sync() Sync portage/overlay trees and update the eix database .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq eix.sync .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.eix.update() Update the eix database .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq eix.update .ft P .fi .UNINDENT .SS salt.modules.event .sp Fire events on the minion, events can be fired up to the master .INDENT 0.0 .TP .B salt.modules.event.fire(data, tag) Fire an event on the local minion event bus .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq event.fire \(aqstuff to be in the event\(aq \(aqtag\(aq .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.event.fire_master(data, tag) Fire an event off on the master server .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq event.fire_master \(aqstuff to be in the event\(aq \(aqtag\(aq .ft P .fi .UNINDENT .SS salt.modules.extfs .sp Module for managing ext2/3/4 file systems .INDENT 0.0 .TP .B salt.modules.extfs.attributes(device, args=None) Return attributes from dumpe2fs for a specified device .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq extfs.attributes /dev/sda1 .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.extfs.blocks(device, args=None) Return block and inode info from dumpe2fs for a specified device .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq extfs.blocks /dev/sda1 .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.extfs.dump(device, args=None) Return all contents of dumpe2fs for a specified device .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq extfs.dump /dev/sda1 .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.extfs.mkfs(device, fs_type, **kwargs) Create a file system on the specified device .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq extfs.mkfs /dev/sda1 fs_type=ext4 opts=\(aqacl,noexec\(aq .ft P .fi .sp Valid options are: .sp .nf .ft C block_size: 1024, 2048 or 4096 check: check for bad blocks direct: use direct IO ext_opts: extended file system options (comma\-separated) fragment_size: size of fragments force: setting force to True will cause mke2fs to specify the \-F option twice (it is already set once); this is truly dangerous blocks_per_group: number of blocks in a block group number_of_groups: ext4 option for a virtual block group bytes_per_inode: set the bytes/inode ratio inode_size: size of the inode journal: set to True to create a journal (default on ext3/4) journal_opts: options for the fs journal (comma separated) blocks_file: read bad blocks from file label: label to apply to the file system reserved: percentage of blocks reserved for super\-user last_dir: last mounted directory test: set to True to not actually create the file system (mke2fs \-n) number_of_inodes: override default number of inodes creator_os: override "creator operating system" field opts: mount options (comma separated) revision: set the filesystem revision (default 1) super: write superblock and group descriptors only fs_type: set the filesystem type (REQUIRED) usage_type: how the filesystem is going to be used uuid: set the UUID for the file system see man 8 mke2fs for a more complete description of these options .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.extfs.tune(device, **kwargs) Set attributes for the specified device (using tune2fs) .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq extfs.tune /dev/sda1 force=True label=wildstallyns opts=\(aqacl,noexec\(aq .ft P .fi .sp Valid options are: .sp .nf .ft C max: max mount count count: mount count error: error behavior extended_opts: extended options (comma separated) force: force, even if there are errors (set to True) group: group name or gid that can use the reserved blocks interval: interval between checks journal: set to True to create a journal (default on ext3/4) journal_opts: options for the fs journal (comma separated) label: label to apply to the file system reserved: percentage of blocks reserved for super\-user last_dir: last mounted directory opts: mount options (comma separated) feature: set or clear a feature (comma separated) mmp_check: mmp check interval reserved: reserved blocks count quota_opts: quota options (comma separated) time: time last checked user: user or uid who can use the reserved blocks uuid: set the UUID for the file system see man 8 tune2fs for a more complete description of these options .ft P .fi .UNINDENT .SS salt.modules.file .sp Manage information about files on the minion, set/read user, group, and mode data .INDENT 0.0 .TP .B salt.modules.file.append(path, *args) Append text to the end of a file .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq file.append /etc/motd \e "With all thine offerings thou shalt offer salt."\e "Salt is what makes things taste bad when it isn\(aqt in them." .ft P .fi .sp New in version 0.9.5. .UNINDENT .INDENT 0.0 .TP .B salt.modules.file.check_file_meta(name, sfn, source, source_sum, user, group, mode, env) 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 .B salt.modules.file.check_hash(path, hash) Check if a file matches the given hash string .sp Returns true if the hash matched, otherwise false. Raises ValueError if the hash was not formatted correctly. .INDENT 7.0 .TP .B path A file path .TP .B hash 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 .B salt.modules.file.check_perms(name, ret, user, group, mode) Check the permissions on files and chown if needed .INDENT 7.0 .TP .B Note: \(aqmode\(aq here is expected to be either a string or an integer, in which case it will be converted into a base\-10 string. .sp What this means is that in your YAML salt file, you can specify mode as an integer(eg, 644) or as a string(eg, \(aq644\(aq). But, to 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 .B salt.modules.file.chgrp(path, group) Change the group of a file .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq file.chgrp /etc/passwd root .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.file.chown(path, user, group) Chown a file, pass the file the desired user and group .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq file.chown /etc/passwd root root .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.file.comment(path, regex, char=\(aq#\(aq, backup=\(aq.bak\(aq) Comment out specified lines in a file .INDENT 7.0 .TP .B path The full path to the file to be edited .TP .B regex A regular expression used to find the lines that are to be commented; this pattern will be wrapped in parenthesis and will move any preceding/trailing \fB^\fP or \fB$\fP characters outside the parenthesis (e.g., the pattern \fB^foo$\fP will be rewritten as \fB^(foo)$\fP) .TP .B char \fB#\fP The character to be inserted at the beginning of a line in order to comment it out .TP .B backup \fB.bak\fP The file will be backed up before edit with this file extension .IP Warning This backup will be overwritten each time \fBsed\fP / \fBcomment\fP / \fBuncomment\fP is called. Meaning the backup will only be useful after the first invocation. .RE .UNINDENT .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq file.comment /etc/modules pcspkr .ft P .fi .sp New in version 0.9.5. .UNINDENT .INDENT 0.0 .TP .B salt.modules.file.contains(path, text) Return True if the file at \fBpath\fP contains \fBtext\fP .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq file.contains /etc/crontab \(aqmymaintenance.sh\(aq .ft P .fi .sp New in version 0.9.5. .UNINDENT .INDENT 0.0 .TP .B salt.modules.file.contains_glob(path, glob) Return True if the given glob matches a string in the named file .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq file.contains_glob /etc/foobar \(aq*cheese*\(aq .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.file.contains_regex(path, regex, lchar=\(aq\(aq) Return True if the given regular expression matches anything in the text of a given file .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq file.contains_regex /etc/crontab \(aq^maint\(aq .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.file.directory_exists(path) Tests to see if path is a valid directory. Returns True/False. .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq file.directory_exists /etc .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.file.file_exists(path) Tests to see if path is a valid file. Returns True/False. .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq file.file_exists /etc/passwd .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.file.find(path, **kwargs) Approximate the Unix find(1) command and return a list of paths that meet the specified critera. .sp The options include match criteria: .sp .nf .ft C name = path\-glob # case sensitive iname = path\-glob # case insensitive regex = path\-regex # case sensitive iregex = path\-regex # case insensitive type = file\-types # match any listed type user = users # match any listed user group = groups # match any listed group size = [+\-]number[size\-unit] # default unit = byte mtime = interval # modified since date grep = regex # search file contents .ft P .fi .sp and/or actions: .sp .nf .ft C delete [= file\-types] # default type = \(aqf\(aq exec = command [arg ...] # where {} is replaced by pathname print [= print\-opts] .ft P .fi .sp The default action is \(aqprint=path\(aq. .sp file\-glob: .sp .nf .ft C * = match zero or more chars ? = match any char [abc] = match a, b, or c [!abc] or [^abc] = match anything except a, b, and c [x\-y] = match chars x through y [!x\-y] or [^x\-y] = match anything except chars x through y {a,b,c} = match a or b or c .ft P .fi .sp path\-regex: a Python re (regular expression) pattern to match pathnames .sp file\-types: a string of one or more of the following: .sp .nf .ft C a: all file types b: block device c: character device d: directory p: FIFO (named pipe) f: plain file l: symlink s: socket .ft P .fi .sp users: a space and/or comma separated list of user names and/or uids .sp groups: a space and/or comma separated list of group names and/or gids .sp size\-unit: .sp .nf .ft C b: bytes k: kilobytes m: megabytes g: gigabytes t: terabytes .ft P .fi .sp interval: .sp .nf .ft C [w] [[d]] [h] [m] [s] where: w: week d: day h: hour m: minute s: second .ft P .fi .sp print\-opts: a comma and/or space separated list of one or more of the following: .sp .nf .ft C group: group name md5: MD5 digest of file contents mode: file permissions (as integer) mtime: last modification time (as time_t) name: file basename path: file absolute path size: file size in bytes type: file type user: user name .ft P .fi .sp CLI Examples: .sp .nf .ft C salt \(aq*\(aq file.find / type=f name=\e*.bak size=+10m salt \(aq*\(aq file.find /var mtime=+30d size=+10m print=path,size,mtime salt \(aq*\(aq file.find /var/log name=\e*.[0\-9] mtime=+30d size=+10m delete .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.file.get_diff(minionfile, masterfile, env=\(aqbase\(aq) Return unified diff of file compared to file on master .sp 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 .B salt.modules.file.get_gid(path) Return the id of the group that owns a given file .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq file.get_gid /etc/passwd .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.file.get_group(path) Return the group that owns a given file .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq file.get_group /etc/passwd .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.file.get_hash(path, form=\(aqmd5\(aq, chunk_size=4096) Get the hash sum of a file .INDENT 7.0 .TP .B This is better than \fBget_sum\fP for the following reasons: .INDENT 7.0 .IP \(bu 2 It does not read the entire file into memory. .IP \(bu 2 .INDENT 2.0 .TP .B It does not return a string on error. The returned value of \fBget_sum\fP cannot really be trusted since it is vulnerable to 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 .B salt.modules.file.get_mode(path) Return the mode of a file .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq file.get_mode /etc/passwd .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.file.get_selinux_context(path) Get an SELinux context from a given path .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq file.get_selinux_context /etc/hosts .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.file.get_sum(path, form=\(aqmd5\(aq) Return the sum for the given file, default is md5, sha1, sha224, sha256, sha384, sha512 are supported .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq file.get_sum /etc/passwd sha512 .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.file.get_uid(path) Return the id of the user that owns a given file .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq file.get_uid /etc/passwd .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.file.get_user(path) Return the user that owns a given file .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq file.get_user /etc/passwd .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.file.gid_to_group(gid) Convert the group id to the group name on this system .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq file.gid_to_group 0 .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.file.group_to_gid(group) Convert the group to the gid on this system .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq file.group_to_gid root .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.file.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=\(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 .B salt.modules.file.patch(originalfile, patchfile, options=\(aq\(aq, dry_run=False) Apply a patch to a file .sp Equivalent to: .sp .nf .ft C patch .ft P .fi .INDENT 7.0 .TP .B originalfile The full path to the file or directory to be patched .TP .B patchfile A patch file to apply to \fBoriginalfile\fP .TP .B options Options to pass to patch. .UNINDENT .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq file.patch /opt/file.txt /tmp/file.txt.patch .ft P .fi .sp New in version 0.10.4. .UNINDENT .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 .B salt.modules.file.restorecon(path, recursive=False) Reset the SELinux context on a given path .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq file.restorecon /home/user/.ssh/authorized_keys .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.file.sed(path, before, after, limit=\(aq\(aq, backup=\(aq.bak\(aq, options=\(aq\-r \-e\(aq, flags=\(aqg\(aq, escape_all=False) Make a simple edit to a file .sp Equivalent to: .sp .nf .ft C sed "// s/// " .ft P .fi .INDENT 7.0 .TP .B path The full path to the file to be edited .TP .B before A pattern to find in order to replace with \fBafter\fP .TP .B after Text that will replace \fBbefore\fP .TP .B limit \fB\(aq\(aq\fP An initial pattern to search for before searching for \fBbefore\fP .TP .B backup \fB.bak\fP The file will be backed up before edit with this file extension; \fBWARNING:\fP each time \fBsed\fP/\fBcomment\fP/\fBuncomment\fP is called will overwrite this backup .TP .B options \fB\-r \-e\fP Options to pass to sed .TP .B flags \fBg\fP Flags to modify the sed search; e.g., \fBi\fP for case\-insensitve pattern matching .UNINDENT .sp Forward slashes and single quotes will be escaped automatically in the \fBbefore\fP and \fBafter\fP patterns. .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq file.sed /etc/httpd/httpd.conf \(aqLogLevel warn\(aq \(aqLogLevel info\(aq .ft P .fi .sp New in version 0.9.5. .UNINDENT .INDENT 0.0 .TP .B salt.modules.file.set_mode(path, mode) Set the mode of a file .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq file.set_mode /etc/passwd 0644 .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.file.set_selinux_context(path, user=None, role=None, type=None, range=None) Set a specific SELinux label on a given path .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq file.set_selinux_context path .ft P .fi .UNINDENT .INDENT 0.0 .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 .B salt.modules.file.stats(path, hash_type=\(aqmd5\(aq, follow_symlink=False) Return a dict containing the stats for a given file .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq file.stats /etc/passwd .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.file.touch(name, atime=None, mtime=None) Just like \(aqnix\(aqs "touch" command, create a file if it doesn\(aqt exist or simply update the atime and mtime if it already does. .INDENT 7.0 .TP .B atime: Access time in Unix epoch time .TP .B mtime: Last modification in Unix epoch time .UNINDENT .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq file.touch /var/log/emptyfile .ft P .fi .sp New in version 0.9.5. .UNINDENT .INDENT 0.0 .TP .B salt.modules.file.uid_to_user(uid) Convert a uid to a user name .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq file.uid_to_user 0 .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.file.uncomment(path, regex, char=\(aq#\(aq, backup=\(aq.bak\(aq) Uncomment specified commented lines in a file .INDENT 7.0 .TP .B path The full path to the file to be edited .TP .B regex A regular expression used to find the lines that are to be uncommented. This regex should not include the comment character. A leading \fB^\fP character will be stripped for convenience (for easily switching between comment() and uncomment()). .TP .B char \fB#\fP The character to remove in order to uncomment a line; if a single whitespace character follows the comment it will also be removed .TP .B backup \fB.bak\fP The file will be backed up before edit with this file extension; \fBWARNING:\fP each time \fBsed\fP/\fBcomment\fP/\fBuncomment\fP is called will overwrite this backup .UNINDENT .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq file.uncomment /etc/hosts.deny \(aqALL: PARANOID\(aq .ft P .fi .sp New in version 0.9.5. .UNINDENT .INDENT 0.0 .TP .B salt.modules.file.user_to_uid(user) Convert user name to a uid .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq file.user_to_uid root .ft P .fi .UNINDENT .SS salt.modules.freebsdjail .sp The jail module for FreeBSD .INDENT 0.0 .TP .B salt.modules.freebsdjail.fstab(jail) Display contents of a fstab(5) file defined in specified jail\(aqs configuration. If no file is defined, return False. .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq jail.fstab .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.freebsdjail.get_enabled() Return which jails are set to be run .UNINDENT .INDENT 0.0 .TP .B salt.modules.freebsdjail.is_enabled() See if jail service is actually enabled on boot .UNINDENT .INDENT 0.0 .TP .B salt.modules.freebsdjail.restart(jail=\(aq\(aq) Restart the specified jail or all, if none specified .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq jail.restart [] .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.freebsdjail.show_config(jail) Display specified jail\(aqs configuration .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq jail.show_config .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.freebsdjail.start(jail=\(aq\(aq) Start the specified jail or all, if none specified .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq jail.start [] .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.freebsdjail.status(jail) See if specified jail is currently running .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq jail.status .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.freebsdjail.stop(jail=\(aq\(aq) Stop the specified jail or all, if none specified .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq jail.stop [] .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.freebsdjail.sysctl() Dump all jail related kernel states (sysctl) .UNINDENT .SS salt.modules.freebsdkmod .sp Module to manage FreeBSD kernel modules .INDENT 0.0 .TP .B salt.modules.freebsdkmod.available() Return a list of all available kernel modules .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq kmod.available .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.freebsdkmod.check_available(mod) Check to see if the specified kernel module is available .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq kmod.check_available kvm .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.freebsdkmod.load(mod) Load the specified kernel module .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq kmod.load kvm .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.freebsdkmod.lsmod() Return a dict containing information about currently loaded modules .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq kmod.lsmod .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.freebsdkmod.remove(mod) Remove the specified kernel module .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq kmod.remove kvm .ft P .fi .UNINDENT .SS salt.modules.freebsdpkg .sp Package support for FreeBSD .INDENT 0.0 .TP .B salt.modules.freebsdpkg.available_version(*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(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.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 .INDENT 0.0 .TP .B salt.modules.freebsdpkg.install(name=None, refresh=False, fromrepo=None, pkgs=None, sources=None, **kwargs) Install the passed package .INDENT 7.0 .TP .B name The name of the package to be installed. .TP .B refresh Whether or not to refresh the package database before installing. .TP .B fromrepo Specify a package repository to install from. .UNINDENT .sp Multiple Package Installation Options: .INDENT 7.0 .TP .B pkgs A list of packages to install from a software repository. Must be passed as a python list. .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq pkg.install pkgs=\(aq["foo","bar"]\(aq .ft P .fi .TP .B sources A list of packages to install. Must be passed as a list of dicts, with the keys being package names, and the values being the source URI or local path to the package. .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq pkg.install sources=\(aq[{"foo": "salt://foo.deb"},{"bar": "salt://bar.deb"}]\(aq .ft P .fi .UNINDENT .sp Return a dict containing the new package names and versions: .sp .nf .ft C {\(aq\(aq: {\(aqold\(aq: \(aq\(aq, \(aqnew\(aq: \(aq\(aq}} .ft P .fi .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq pkg.install .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.freebsdpkg.list_pkgs() List the packages currently installed as a dict: .sp .nf .ft C {\(aq\(aq: \(aq\(aq} .ft P .fi .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq pkg.list_pkgs .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.freebsdpkg.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. .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq pkg.purge .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.freebsdpkg.refresh_db() Use pkg update to get latest repo.txz when using pkgng, else update the ports tree with portsnap otherwise. If the ports tree does not exist it will be downloaded and set up. .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq pkg.refresh_db .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.freebsdpkg.rehash() Recomputes internal hash table for the PATH variable. Use whenever a new command is created during the current session. .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq pkg.rehash .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.freebsdpkg.remove(name=None, pkgs=None, **kwargs) Remove a single package. .INDENT 7.0 .TP .B name None The name of the package to be deleted. .TP .B pkgs None A list of packages to delete. Must be passed as a python list. .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq pkg.remove pkgs=\(aq["foo","bar"]\(aq .ft P .fi .UNINDENT .sp Returns a list containing the removed packages. .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq pkg.remove .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.freebsdpkg.search(pkg_name) Use \fIpkg search\fP if pkg is being used. .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq pkg.search \(aqmysql\-server\(aq .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.freebsdpkg.upgrade() Run pkg upgrade, if pkgng used. Otherwise do nothing .sp Return a dict containing the new package names and versions: .sp .nf .ft C {\(aq\(aq: {\(aqold\(aq: \(aq\(aq, \(aqnew\(aq: \(aq\(aq}} .ft P .fi .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq pkg.upgrade .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.freebsdpkg.version(*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 .SS salt.modules.freebsdservice .sp The service module for FreeBSD .INDENT 0.0 .TP .B salt.modules.freebsdservice.disable(name, config=\(aq/etc/rc.conf\(aq, **kwargs) Disable the named service to start at boot .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq service.disable .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.freebsdservice.disabled(name) Return True if the named servioce is enabled, false otherwise .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq service.disabled .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.freebsdservice.enable(name, config=\(aq/etc/rc.conf\(aq, **kwargs) Enable the named service to start at boot .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq service.enable .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.freebsdservice.enabled(name) Return True if the named servioce is enabled, false otherwise .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq service.enabled .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.freebsdservice.get_all() Return a list of all available services .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq service.get_all .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.freebsdservice.get_disabled() Return what services are available but not enabled to start at boot .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq service.get_disabled .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.freebsdservice.get_enabled() Return what services are set to run on boot .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq service.get_enabled .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.freebsdservice.reload(name) Restart the named service .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq service.reload .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.freebsdservice.restart(name) Restart the named service .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq service.restart .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.freebsdservice.start(name) Start the specified service .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq service.start .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.freebsdservice.status(name, sig=None) Return the status for a service (True or False). .INDENT 7.0 .TP .B name Name of service. .TP .B sig None Signature. If sig is passed use as service name instead of name argument. .UNINDENT .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq service.status .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.freebsdservice.stop(name) Stop the specified service .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq service.stop .ft P .fi .UNINDENT .SS salt.modules.freebsd_sysctl .sp Module for viewing and modifying sysctl parameters .INDENT 0.0 .TP .B salt.modules.freebsd_sysctl.assign(name, value) Assign a single sysctl parameter for this minion .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq sysctl.assign net.inet.icmp.icmplim 50 .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.freebsd_sysctl.get(name) Return a single sysctl parameter for this minion .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq sysctl.get hw.physmem .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.freebsd_sysctl.persist(name, value, config=\(aq/etc/sysctl.conf\(aq) Assign and persist a simple sysctl parameter for this minion .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq sysctl.persist net.inet.icmp.icmplim 50 salt \(aq*\(aq sysctl.persist coretemp_load NO config=/boot/loader.conf .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.freebsd_sysctl.show() Return a list of sysctl parameters for this minion .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq sysctl.show .ft P .fi .UNINDENT .SS salt.modules.gem .sp Manage ruby gems. .INDENT 0.0 .TP .B salt.modules.gem.install(gems, ruby=None, runas=None, version=None, rdoc=False, ri=False) Installs one or several gems. .INDENT 7.0 .TP .B gems The gems to install. .TP .B ruby None If RVM is installed, the ruby version and gemset to use. .TP .B runas None The user to run gem as. .TP .B version None Specify the version to install for the gem. Doesn\(aqt play nice with multiple gems at once .TP .B rdoc False Generate RDoc documentation for the gem(s). .TP .B ri 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 .B salt.modules.gem.list(prefix=\(aq\(aq, ruby=None, runas=None) List locally installed gems. .INDENT 7.0 .TP .B prefix : Only list gems when the name matches this prefix. .TP .B ruby None If RVM is installed, the ruby version and gemset to use. .TP .B runas None The user to run gem as. .UNINDENT .sp CLI Example: .sp .nf .ft C gem.list .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.gem.sources_add(source_uri, ruby=None, runas=None) Add a gem source. .INDENT 7.0 .TP .B source_uri The source URI to add. .TP .B ruby None If RVM is installed, the ruby version and gemset to use. .TP .B runas None The user to run gem as. .UNINDENT .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq gem.sources_add http://rubygems.org/ .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.gem.sources_list(ruby=None, runas=None) List the configured gem sources. .INDENT 7.0 .TP .B ruby None If RVM is installed, the ruby version and gemset to use. .TP .B runas None The user to run gem as. .UNINDENT .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq gem.sources_list .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.gem.sources_remove(source_uri, ruby=None, runas=None) Remove a gem source. .INDENT 7.0 .TP .B source_uri The source URI to remove. .TP .B ruby None If RVM is installed, the ruby version and gemset to use. .TP .B runas None The user to run gem as. .UNINDENT .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq gem.sources_remove http://rubygems.org/ .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.gem.uninstall(gems, ruby=None, runas=None) Uninstall one or several gems. .INDENT 7.0 .TP .B gems The gems to uninstall. .TP .B ruby None If RVM is installed, the ruby version and gemset to use. .TP .B runas None The user to run gem as. .UNINDENT .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq gem.uninstall vagrant .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.gem.update(gems, ruby=None, runas=None) Update one or several gems. .INDENT 7.0 .TP .B gems The gems to update. .TP .B ruby None If RVM is installed, the ruby version and gemset to use. .TP .B runas None The user to run gem as. .UNINDENT .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq gem.update vagrant .ft P .fi .UNINDENT .INDENT 0.0 .TP .B salt.modules.gem.update_system(version=\(aq\(aq, ruby=None, runas=None) Update rubygems. .INDENT 7.0 .TP .B version (newest) The version of rubygems to install. .TP .B ruby None If RVM is installed, the ruby version and gemset to use. .TP .B runas None The user to run gem as. .UNINDENT .sp CLI Example: .sp .nf .ft C salt \(aq*\(aq gem.update_system .ft P .fi .UNINDENT .SS salt.modules.gentoolkitmod .sp Support for Gentoolkit .INDENT 0.0 .TP .B salt.modules.gentoolkitmod.eclean_dist(destructive=False, package_names=False, size_limit=0, time_limit=0, fetch_restricted=False, exclude_file=\(aq/etc/eclean/distfiles.exclude\(aq) Clean obsolete portage sources .INDENT 7.0 .TP .B destructive Only keep minimum for reinstallation .TP .B package_names Protect all versions of installed packages. Only meaningful if used with destructive=True .TP .B size_limit Don\(aqt delete distfiles bigger than . is a size specification: "10M" is "ten megabytes", "200K" is "two hundreds kilobytes", etc. Units are: G, M, K and B. .TP .B time_limit