.\" Man page generated from reStructuredText. . .TH "SALT" "7" "February 13, 2015" "2014.1.13" "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 .. .SH FREQUENTLY ASKED QUESTIONS .SS FAQ .INDENT 0.0 .IP \(bu 2 \fI\%Frequently Asked Questions\fP .INDENT 2.0 .IP \(bu 2 \fI\%Is Salt open\-core?\fP .IP \(bu 2 \fI\%What ports should I open on my firewall?\fP .IP \(bu 2 \fI\%I\(aqm seeing weird behavior (including but not limited to packages not installing their users properly)\fP .IP \(bu 2 \fI\%My script runs every time I run a state.highstate. Why?\fP .IP \(bu 2 \fI\%When I run test.ping, why don\(aqt the Minions that aren\(aqt responding return anything? Returning False would be helpful.\fP .IP \(bu 2 \fI\%How does Salt determine the Minion\(aqs id?\fP .IP \(bu 2 \fI\%I\(aqm trying to manage packages/services but I get an error saying that the state is not available. Why?\fP .IP \(bu 2 \fI\%I\(aqm using gitfs and my custom modules/states/etc are not syncing. Why?\fP .IP \(bu 2 \fI\%Why aren\(aqt my custom modules/states/etc. available on my Minions?\fP .IP \(bu 2 \fI\%Module X isn\(aqt available, even though the shell command it uses is installed. Why?\fP .IP \(bu 2 \fI\%Can I run different versions of Salt on my Master and Minion?\fP .IP \(bu 2 \fI\%Does Salt support backing up managed files?\fP .UNINDENT .UNINDENT .SS Is Salt open\-core? .sp No. Salt is 100% committed to being open\-source, including all of our APIs and the new \fI\%\(aqHalite\(aq web interface\fP which was introduced in version 0.17.0. It is developed under the \fI\%Apache 2.0 license\fP, allowing it to be used in both open and proprietary projects. .SS What ports should I open on my firewall? .sp Minions need to be able to connect to the Master on TCP ports 4505 and 4506. Minions do not need any inbound ports open. More detailed information on firewall settings can be found \fBhere\fP\&. .SS I\(aqm seeing weird behavior (including but not limited to packages not installing their users properly) .sp This is often caused by SELinux. Try disabling SELinux or putting it in permissive mode and see if the weird behavior goes away. .SS My script runs every time I run a \fIstate.highstate\fP\&. Why? .sp You are probably using \fBcmd.run\fP rather than \fBcmd.wait\fP\&. A \fBcmd.wait\fP state will only run when there has been a change in a state that it is watching. .sp A \fBcmd.run\fP state will run the corresponding command \fIevery time\fP (unless it is prevented from running by the \fBunless\fP or \fBonlyif\fP arguments). .sp More details can be found in the docmentation for the \fBcmd\fP states. .SS When I run \fItest.ping\fP, why don\(aqt the Minions that aren\(aqt responding return anything? Returning \fBFalse\fP would be helpful. .sp When you run \fItest.ping\fP the Master tells Minions to run commands/functions, and listens for the return data, printing it to the screen when it is received. If it doesn\(aqt receive anything back, it doesn\(aqt have anything to display for that Minion. .sp There are a couple options for getting information on Minions that are not responding. One is to use the verbose (\fB\-v\fP) option when you run salt commands, as it will display "Minion did not return" for any Minions which time out. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt \-v \(aq*\(aq pkg.install zsh .ft P .fi .UNINDENT .UNINDENT .sp Another option is to use the \fBmanage.down\fP runner: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt\-run manage.down .ft P .fi .UNINDENT .UNINDENT .SS How does Salt determine the Minion\(aqs id? .sp If the Minion id is not configured explicitly (using the \fBid\fP parameter), Salt will determine the id based on the hostname. Exactly how this is determined varies a little between operating systems and is described in detail \fIhere\fP\&. .SS I\(aqm trying to manage packages/services but I get an error saying that the state is not available. Why? .sp Salt detects the Minion\(aqs operating system and assigns the correct package or service management module based on what is detected. However, for certain custom spins and OS derivatives this detection fails. In cases like this, an issue should be opened on our \fI\%tracker\fP, with the following information: .INDENT 0.0 .IP 1. 3 The output of the following command: .INDENT 3.0 .INDENT 3.5 .sp .nf .ft C salt grains.items | grep os .ft P .fi .UNINDENT .UNINDENT .IP 2. 3 The contents of \fB/etc/lsb\-release\fP, if present on the Minion. .UNINDENT .SS I\(aqm using gitfs and my custom modules/states/etc are not syncing. Why? .sp In versions of Salt 0.16.3 or older, there is a bug in \fBgitfs\fP which can affect the syncing of custom types. Upgrading to 0.16.4 or newer will fix this. .SS Why aren\(aqt my custom modules/states/etc. available on my Minions? .sp Custom modules are only synced to Minions when \fBstate.highstate\fP, \fBsaltutil.sync_modules\fP, or \fBsaltutil.sync_all\fP is run. Similarly, custom states are only synced to Minions when \fBstate.highstate\fP, \fBsaltutil.sync_states\fP, or \fBsaltutil.sync_all\fP is run. .sp Other custom types (renderers, outputters, etc.) have similar behavior, see the documentation for the \fBsaltutil\fP module for more information. .SS Module \fBX\fP isn\(aqt available, even though the shell command it uses is installed. Why? .sp This is most likely a PATH issue. Did you custom\-compile the software which the module requires? RHEL/CentOS/etc. in particular override the root user\(aqs path in \fB/etc/init.d/functions\fP, setting it to \fB/sbin:/usr/sbin:/bin:/usr/bin\fP, making software installed into \fB/usr/local/bin\fP unavailable to Salt when the Minion is started using the initscript. In version 2014.1.0, Salt will have a better solution for these sort of PATH\-related issues, but recompiling the software to install it into a location within the PATH should resolve the issue in the meantime. Alternatively, you can create a symbolic link within the PATH using a \fBfile.symlink\fP state. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C /usr/bin/foo: file.symlink: \- target: /usr/local/bin/foo .ft P .fi .UNINDENT .UNINDENT .SS Can I run different versions of Salt on my Master and Minion? .sp As of release 0.17.1 backwards compatibility was broken (specifically for 0.17.1 trying to interface with older releases) due to a protocol change for security purposes. The Salt team continues to emphasize backwards compatiblity as an important feature and plans to support it to the best of our ability to do so. .SS Does Salt support backing up managed files? .sp Yes. Salt provides an easy to use addition to your file.managed states that allow you to back up files via \fBbackup_mode\fP, backup_mode can be configured on a per state basis, or in the minion config (note that if set in the minion config this would simply be the default method to use, you still need to specify that the file should be backed up!). .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 license\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. .sp \fBSEE ALSO:\fP .INDENT 0.0 .INDENT 3.5 \fBInstalling Salt for development\fP and contributing to the project. .UNINDENT .UNINDENT .SS Quick Install .sp Many popular distributions will be able to install the salt minion by executing the bootstrap script: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C wget \-O \- http://bootstrap.saltstack.org | sudo sh .ft P .fi .UNINDENT .UNINDENT .sp Run the following script to install just the Salt Master: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C curl \-L http://bootstrap.saltstack.org | sudo sh \-s \-\- \-M \-N .ft P .fi .UNINDENT .UNINDENT .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: .INDENT 0.0 .INDENT 3.5 .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 .UNINDENT .UNINDENT .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 .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 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: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C yaourt salt .ft P .fi .UNINDENT .UNINDENT .UNINDENT .UNINDENT .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: .INDENT 0.0 .INDENT 3.5 .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 .UNINDENT .UNINDENT .sp See the note above about Salt\(aqs dependencies. .SS Post\-installation tasks .sp \fBsystemd\fP .sp Activate the Salt Master and/or Minion via \fBsystemctl\fP as follows: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C systemctl enable salt\-master.service systemctl enable salt\-minion.service .ft P .fi .UNINDENT .UNINDENT .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: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C systemctl start salt\-master .ft P .fi .UNINDENT .UNINDENT .sp Now go to the \fBConfiguring Salt\fP page. .SS Debian Installation .sp Currently the latest packages for Debian Old Stable, Stable and Unstable (Squeeze, Wheezy and Sid) are published in our (saltstack.com) debian repository. .SS Configure Apt .SS Squeeze (Old Stable) .sp For squeeze, you will need to enable the debian backports repository as well as the debian.saltstack.com repository. To do so, add the following to \fB/etc/apt/sources.list\fP or a file in \fB/etc/apt/sources.list.d\fP: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C deb http://debian.saltstack.com/debian squeeze\-saltstack main deb http://backports.debian.org/debian\-backports squeeze\-backports main contrib non\-free .ft P .fi .UNINDENT .UNINDENT .SS Wheezy (Stable) .sp For wheezy, the following line is needed in either \fB/etc/apt/sources.list\fP or a file in \fB/etc/apt/sources.list.d\fP: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C deb http://debian.saltstack.com/debian wheezy\-saltstack main .ft P .fi .UNINDENT .UNINDENT .SS Sid (Unstable) .sp For sid, the following line is needed in either \fB/etc/apt/sources.list\fP or a file in \fB/etc/apt/sources.list.d\fP: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C deb http://debian.saltstack.com/debian unstable main .ft P .fi .UNINDENT .UNINDENT .SS Import the repository key. .sp You will need to import the key used for signing. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C wget \-q \-O\- "http://debian.saltstack.com/debian\-salt\-team\-joehealy.gpg.key" | apt\-key add \- .ft P .fi .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 You can optionally verify the key integrity with \fBsha512sum\fP using the public key signature shown here. E.g: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C echo "b702969447140d5553e31e9701be13ca11cc0a7ed5fe2b30acb8491567560ee62f834772b5095d735dfcecb2384a5c1a20045f52861c417f50b68dd5ff4660e6 debian\-salt\-team\-joehealy.gpg.key" | sha512sum \-c .ft P .fi .UNINDENT .UNINDENT .UNINDENT .UNINDENT .SS Update the package database .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C apt\-get update .ft P .fi .UNINDENT .UNINDENT .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: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C apt\-get install salt\-master .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C apt\-get install salt\-minion .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C apt\-get install salt\-syndic .ft P .fi .UNINDENT .UNINDENT .SS Post\-installation tasks .sp Now, go to the \fBConfiguring Salt\fP page. .SS Notes .sp 1. These packages will be backported from the packages intended to be uploaded into debian unstable. This means that the packages will be built for unstable first and then backported over the next day or so. .sp 2. These packages will be tracking the released versions of salt rather than maintaining a stable fixed feature set. If a fixed version is what you desire, then either pinning or manual installation may be more appropriate for you. .sp 3. The version numbering and backporting process should provide clean upgrade paths between debian versions. .sp If you have any questions regarding these, please email the mailing list or look for joehh on irc. .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! .sp \fBWARNING\fP: Fedora 19 comes with systemd 204. Systemd has known bugs fixed in later revisions that prevent the salt\-master from starting reliably or opening the network connections that it needs to. It\(aqs not likely that a salt\-master will start or run reliably on any distribution that uses systemd version 204 or earlier. Running salt\-minions should be OK. .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. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C yum install salt\-master yum install salt\-minion .ft P .fi .UNINDENT .UNINDENT .SS Post\-installation tasks .sp \fBMaster\fP .sp To have the Master start automatically at boot time: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C systemctl enable salt\-master.service .ft P .fi .UNINDENT .UNINDENT .sp To start the Master: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C systemctl start salt\-master.service .ft P .fi .UNINDENT .UNINDENT .sp \fBMinion\fP .sp To have the Minion start automatically at boot time: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C systemctl enable salt\-minion.service .ft P .fi .UNINDENT .UNINDENT .sp To start the Minion: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C systemctl start salt\-minion.service .ft P .fi .UNINDENT .UNINDENT .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. .INDENT 0.0 .INDENT 3.5 .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 .UNINDENT .UNINDENT .SS Installation .sp To install Salt from the FreeBSD ports tree, use the command: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C make \-C /usr/ports/sysutils/py\-salt install clean .ft P .fi .UNINDENT .UNINDENT .SS Post\-installation tasks .sp \fBMaster\fP .sp Copy the sample configuration file: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C cp /usr/local/etc/salt/master.sample /usr/local/etc/salt/master .ft P .fi .UNINDENT .UNINDENT .sp \fBrc.conf\fP .sp Activate the Salt Master in \fB/etc/rc.conf\fP or \fB/etc/rc.conf.local\fP and add: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C + salt_master_enable="YES" .ft P .fi .UNINDENT .UNINDENT .sp \fBStart the Master\fP .sp Start the Salt Master as follows: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C service salt_master start .ft P .fi .UNINDENT .UNINDENT .sp \fBMinion\fP .sp Copy the sample configuration file: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C cp /usr/local/etc/salt/minion.sample /usr/local/etc/salt/minion .ft P .fi .UNINDENT .UNINDENT .sp \fBrc.conf\fP .sp Activate the Salt Minion in \fB/etc/rc.conf\fP or \fB/etc/rc.conf.local\fP and add: .INDENT 0.0 .INDENT 3.5 .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 .UNINDENT .UNINDENT .sp \fBStart the Minion\fP .sp Start the Salt Minion as follows: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C service salt_minion start .ft P .fi .UNINDENT .UNINDENT .sp Now go to the \fBConfiguring Salt\fP page. .SS Gentoo .sp Salt can be easily installed on Gentoo via Portage: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C emerge app\-admin/salt .ft P .fi .UNINDENT .UNINDENT .SS Post\-installation tasks .sp Now go to the \fBConfiguring Salt\fP page. .SS OS X .SS Dependency Installation .sp When installing via Homebrew, dependency resolution is handled for you. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C brew install saltstack .ft P .fi .UNINDENT .UNINDENT .sp When using macports, zmq, swig, and pip may need to be installed this way: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C sudo port install py\-zmq sudo port install py27\-m2crypto sudo port install py27\-crypto sudo port install py27\-msgpack sudo port install swig\-python sudo port install py\-pip .ft P .fi .UNINDENT .UNINDENT .sp For installs using the OS X system python, pip install needs to use \(aqsudo\(aq: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C sudo pip install salt .ft P .fi .UNINDENT .UNINDENT .SS Salt\-Master Customizations .sp To run salt\-master on OS X, the root user maxfiles limit must be increased: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C sudo launchctl limit maxfiles 4096 8192 .ft P .fi .UNINDENT .UNINDENT .sp And sudo add this configuration option to the /etc/salt/master file: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C max_open_files: 8192 .ft P .fi .UNINDENT .UNINDENT .sp Now the salt\-master should run without errors: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C sudo /usr/local/share/python/salt\-master \-\-log\-level=all .ft P .fi .UNINDENT .UNINDENT .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 repositories 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: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C yum \-\-enablerepo=epel\-testing install salt\-minion .ft P .fi .UNINDENT .UNINDENT .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 Enabling EPEL on RHEL .sp If EPEL is not enabled on your system, you can use the following commands to enable it. .sp For RHEL 5: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C rpm \-Uvh http://mirror.pnl.gov/epel/5/i386/epel\-release\-5\-4.noarch.rpm .ft P .fi .UNINDENT .UNINDENT .sp For RHEL 6: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C rpm \-Uvh http://ftp.linux.ncsu.edu/pub/epel/6/i386/epel\-release\-6\-8.noarch.rpm .ft P .fi .UNINDENT .UNINDENT .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: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C yum install salt\-master .ft P .fi .UNINDENT .UNINDENT .sp On each salt\-minion, run this: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C yum install salt\-minion .ft P .fi .UNINDENT .UNINDENT .SS Post\-installation tasks .sp \fBMaster\fP .sp To have the Master start automatically at boot time: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C chkconfig salt\-master on .ft P .fi .UNINDENT .UNINDENT .sp To start the Master: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C service salt\-master start .ft P .fi .UNINDENT .UNINDENT .sp \fBMinion\fP .sp To have the Minion start automatically at boot time: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C chkconfig salt\-minion on .ft P .fi .UNINDENT .UNINDENT .sp To start the Minion: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C service salt\-minion start .ft P .fi .UNINDENT .UNINDENT .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.: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C py_yaml py_pyzmq py_jinja2 py_msgpack_python py_m2crypto py_crypto python .ft P .fi .UNINDENT .UNINDENT .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: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C pkgadd \-d http://get.opencsw.org/now .ft P .fi .UNINDENT .UNINDENT .sp On Solaris 9: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C wget http://mirror.opencsw.org/opencsw/pkgutil.pkg pkgadd \-d pkgutil.pkg all .ft P .fi .UNINDENT .UNINDENT .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: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C \- #mirror=http://mirror.opencsw.org/opencsw/testing + mirror=http://mirror.opencsw.org/opencsw/unstable .ft P .fi .UNINDENT .UNINDENT .sp OK, time to install salt. .INDENT 0.0 .INDENT 3.5 .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 .UNINDENT .UNINDENT .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: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C \- #master: salt + master: your\-salt\-server .ft P .fi .UNINDENT .UNINDENT .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: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C svcadm enable salt\-minion .ft P .fi .UNINDENT .UNINDENT .sp On Solaris 9: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C /etc/init.d/salt\-minion start .ft P .fi .UNINDENT .UNINDENT .sp You should now be able to log onto the salt master and check to see if the salt\-minion key is awaiting acceptance: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt\-key \-l un .ft P .fi .UNINDENT .UNINDENT .sp Accept the key: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt\-key \-a .ft P .fi .UNINDENT .UNINDENT .sp Run a simple test against the minion: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt \(aq\(aq test.ping .ft P .fi .UNINDENT .UNINDENT .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: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C sudo add\-apt\-repository ppa:saltstack/salt .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .INDENT 3.5 .IP "add\-apt\-repository: command not found?" .sp The \fBadd\-apt\-repository\fP command is not always present on Ubuntu systems. This can be fixed by installing \fIpython\-software\-properties\fP: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C sudo apt\-get install python\-software\-properties .ft P .fi .UNINDENT .UNINDENT .sp Note that since Ubuntu 12.10 (Raring Ringtail), \fBadd\-apt\-repository\fP is found in the \fIsoftware\-properties\-common\fP package, and is part of the base install. Thus, \fBadd\-apt\-repository\fP should be able to be used out\-of\-the\-box to add the PPA. .UNINDENT .UNINDENT .sp Alternately, manually add the repository and import the PPA key with these commands: .INDENT 0.0 .INDENT 3.5 .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 .UNINDENT .UNINDENT .sp After adding the repository, update the package management database: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C sudo apt\-get update .ft P .fi .UNINDENT .UNINDENT .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: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C sudo apt\-get install salt\-master .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C sudo apt\-get install salt\-minion .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C sudo apt\-get install salt\-syndic .ft P .fi .UNINDENT .UNINDENT .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: .INDENT 0.0 .INDENT 3.5 .IP "Download here" .INDENT 0.0 .IP \(bu 2 0.17.4 .IP \(bu 2 \fI\%http://docs.saltstack.com/downloads/Salt\-Minion\-0.17.4\-win32\-Setup.exe\fP .IP \(bu 2 \fI\%http://docs.saltstack.com/downloads/Salt\-Minion\-0.17.4\-AMD64\-Setup.exe\fP .IP \(bu 2 0.17.2 .IP \(bu 2 \fI\%http://docs.saltstack.com/downloads/Salt\-Minion\-0.17.2\-win32\-Setup.exe\fP .IP \(bu 2 \fI\%http://docs.saltstack.com/downloads/Salt\-Minion\-0.17.2\-AMD64\-Setup.exe\fP .IP \(bu 2 0.17.1.1 \- Windows Installer bugfix release .IP \(bu 2 \fI\%http://docs.saltstack.com/downloads/Salt\-Minion\-0.17.1.1\-win32\-Setup.exe\fP .IP \(bu 2 \fI\%http://docs.saltstack.com/downloads/Salt\-Minion\-0.17.1.1\-AMD64\-Setup.exe\fP .IP \(bu 2 0.17.1 .IP \(bu 2 \fI\%http://docs.saltstack.com/downloads/Salt\-Minion\-0.17.1\-win32\-Setup.exe\fP .IP \(bu 2 \fI\%http://docs.saltstack.com/downloads/Salt\-Minion\-0.17.1\-AMD64\-Setup.exe\fP .IP \(bu 2 0.17.0 .IP \(bu 2 \fI\%http://docs.saltstack.com/downloads/Salt\-Minion\-0.17.0\-win32\-Setup.exe\fP .IP \(bu 2 \fI\%http://docs.saltstack.com/downloads/Salt\-Minion\-0.17.0\-AMD64\-Setup.exe\fP .IP \(bu 2 0.16.3 .IP \(bu 2 \fI\%http://docs.saltstack.com/downloads/Salt\-Minion\-0.16.3\-win32\-Setup.exe\fP .IP \(bu 2 \fI\%http://docs.saltstack.com/downloads/Salt\-Minion\-0.16.3\-AMD64\-Setup.exe\fP .IP \(bu 2 0.16.2 .IP \(bu 2 \fI\%http://docs.saltstack.com/downloads/Salt\-Minion\-0.16.2\-win32\-Setup.exe\fP .IP \(bu 2 \fI\%http://docs.saltstack.com/downloads/Salt\-Minion\-0.16.2\-AMD64\-Setup.exe\fP .IP \(bu 2 0.16.0 .IP \(bu 2 \fI\%http://docs.saltstack.com/downloads/Salt\-Minion\-0.16.0\-win32\-Setup.exe\fP .IP \(bu 2 \fI\%http://docs.saltstack.com/downloads/Salt\-Minion\-0.16.0\-AMD64\-Setup.exe\fP .IP \(bu 2 0.15.3 .IP \(bu 2 \fI\%http://docs.saltstack.com/downloads/Salt\-Minion\-0.15.3\-win32\-Setup.exe\fP .IP \(bu 2 \fI\%http://docs.saltstack.com/downloads/Salt\-Minion\-0.15.3\-AMD64\-Setup.exe\fP .IP \(bu 2 0.14.1 .IP \(bu 2 \fI\%http://docs.saltstack.com/downloads/Salt\-Minion\-0.14.1\-win32\-Setup.exe\fP .IP \(bu 2 \fI\%http://docs.saltstack.com/downloads/Salt\-Minion\-0.14.1\-AMD64\-Setup.exe\fP .IP \(bu 2 0.14.0 .IP \(bu 2 \fI\%http://docs.saltstack.com/downloads/Salt\-Minion\-0.14.0\-win32\-Setup.exe\fP .IP \(bu 2 \fI\%http://docs.saltstack.com/downloads/Salt\-Minion\-0.14.0\-AMD64\-Setup.exe\fP .UNINDENT .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 The executables above will install dependencies that the Salt minion requires. .UNINDENT .UNINDENT .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 SP1 redistributable. Allow all Windows updates to run salt\-minion smoothly. .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: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C Salt\-Minion\-0.17.0\-Setup\-amd64.exe /S /master=yoursaltmaster /minion\-name=yourminionname .ft P .fi .UNINDENT .UNINDENT .SS Setting up a Windows build environment .INDENT 0.0 .IP 1. 3 Install the Microsoft Visual C++ 2008 SP1 Redistributable, \fI\%vcredist_x86\fP or \fI\%vcredist_x64\fP\&. .IP 2. 3 Install \fI\%msysgit\fP .IP 3. 3 Clone the Salt git repository from GitHub .UNINDENT .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C git clone git://github.com/saltstack/salt.git .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .IP 4. 3 Install the latest point release of \fI\%Python 2.7\fP for the architecture you wish to target .IP 5. 3 Add C:\ePython27 and C:\ePython27\eScripts to your system path .IP 6. 3 Download and run the Setuptools bootstrap \- \fI\%ez_setup.py\fP .UNINDENT .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C python ez_setup.py .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .IP 7. 3 Install Pip .UNINDENT .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C easy_install pip .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .IP 8. 3 Install the latest point release of \fI\%OpenSSL for Windows\fP .INDENT 3.0 .IP 1. 3 During setup, choose first option to install in Windows system directory .UNINDENT .IP 9. 3 Install the latest point release of \fI\%M2Crypto\fP .INDENT 3.0 .IP 1. 3 In general, be sure to download installers targeted at py2.7 for your chosen architecture .UNINDENT .IP 10. 3 Install the latest point release of \fI\%pycrypto\fP .IP 11. 3 Install the latest point release of \fI\%pywin32\fP .IP 12. 3 Install the latest point release of \fI\%Cython\fP .IP 13. 3 Install the latest point release of \fI\%jinja2\fP .IP 14. 3 Install the latest point release of \fI\%msgpack\fP .IP 15. 3 Install psutil .UNINDENT .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C easy_install psutil .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .IP 16. 4 Install pyzmq .UNINDENT .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C easy_install pyzmq .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .IP 17. 4 Install PyYAML .UNINDENT .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C easy_install pyyaml .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .IP 18. 4 Install bbfreeze .UNINDENT .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C easy_install bbfreeze .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .IP 19. 4 Install wmi .UNINDENT .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C pip install wmi .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .IP 20. 4 Install esky .UNINDENT .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C pip install esky .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .IP 21. 4 Install Salt .UNINDENT .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C cd salt python setup.py install .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .IP 22. 4 Build a frozen binary distribution of Salt .UNINDENT .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C python setup.py bdist_esky .ft P .fi .UNINDENT .UNINDENT .sp A zip file has been created in the \fBdist/\fP folder, containing a frozen copy of Python and the dependency libraries, along with Windows executables for each of the Salt scripts. .SS Building the installer .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, 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 Testing the Salt minion .INDENT 0.0 .IP 1. 3 Create the directory C:\esalt (if it doesn\(aqt exist already) .IP 2. 3 Copy the example \fBconf\fP and \fBvar\fP directories from \fBpkg/windows/buildenv/\fP into C:\esalt .IP 3. 3 Edit C:\esalt\econf\eminion .UNINDENT .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C master: ipaddress or hostname of your salt\-master .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .IP 4. 3 Start the salt\-minion .UNINDENT .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C cd C:\ePython27\eScripts python salt\-minion .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .IP 5. 3 On the salt\-master accept the new minion\(aqs key .UNINDENT .INDENT 0.0 .INDENT 3.5 .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 .UNINDENT .UNINDENT .INDENT 0.0 .IP 6. 3 Test that your minion is responding .INDENT 3.0 .INDENT 3.5 .INDENT 0.0 .IP a. 3 On the salt\-master run: .UNINDENT .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C sudo salt \(aq*\(aq test.ping .ft P .fi .UNINDENT .UNINDENT .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: .INDENT 0.0 .INDENT 3.5 .IP "Not up to date." .sp This script is not up to date. Please use the installer found above .UNINDENT .UNINDENT .INDENT 0.0 .INDENT 3.5 .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 .UNINDENT .UNINDENT .sp You can execute the above command remotely from a Linux host using winexe: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C winexe \-U "administrator" //fqdn "PowerShell (New\-Object ......);" .ft P .fi .UNINDENT .UNINDENT .sp For more info check \fI\%http://csa\-net.dk/salt\fP .SS Packages management under Windows 2003 .sp On windows Server 2003, you need to install optional component "wmi windows installer provider" to have full list of installed packages. If you don\(aqt have this, salt\-minion can\(aqt report some installed softwares. .SS SUSE Installation .sp With openSUSE 13.1, Salt 0.16.4 has been available in the primary repositories. The devel:language:python repo will have more up to date versions of salt, all package development will be done there. .SS Installation .sp Salt can be installed using \fBzypper\fP and is available in the standard openSUSE 13.1 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. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C zypper install salt\-master zypper install salt\-minion .ft P .fi .UNINDENT .UNINDENT .SS Post\-installation tasks openSUSE .sp \fBMaster\fP .sp To have the Master start automatically at boot time: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C systemctl enable salt\-master.service .ft P .fi .UNINDENT .UNINDENT .sp To start the Master: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C systemctl start salt\-master.service .ft P .fi .UNINDENT .UNINDENT .sp \fBMinion\fP .sp To have the Minion start automatically at boot time: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C systemctl enable salt\-minion.service .ft P .fi .UNINDENT .UNINDENT .sp To start the Minion: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C systemctl start salt\-minion.service .ft P .fi .UNINDENT .UNINDENT .SS Post\-installation tasks SLES .sp \fBMaster\fP .sp To have the Master start automatically at boot time: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C chkconfig salt\-master on .ft P .fi .UNINDENT .UNINDENT .sp To start the Master: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C rcsalt\-master start .ft P .fi .UNINDENT .UNINDENT .sp \fBMinion\fP .sp To have the Minion start automatically at boot time: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C chkconfig salt\-minion on .ft P .fi .UNINDENT .UNINDENT .sp To start the Minion: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C rcsalt\-minion start .ft P .fi .UNINDENT .UNINDENT .SS Unstable Release .SS openSUSE .sp For openSUSE Factory run the following as root: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C zypper addrepo http://download.opensuse.org/repositories/devel:languages:python/openSUSE_Factory/devel:languages:python.repo zypper refresh zypper install salt salt\-minion salt\-master .ft P .fi .UNINDENT .UNINDENT .sp For openSUSE 13.1 run the following as root: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C zypper addrepo http://download.opensuse.org/repositories/devel:languages:python/openSUSE_13.1/devel:languages:python.repo zypper refresh zypper install salt salt\-minion salt\-master .ft P .fi .UNINDENT .UNINDENT .sp For openSUSE 12.3 run the following as root: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C zypper addrepo http://download.opensuse.org/repositories/devel:languages:python/openSUSE_12.3/devel:languages:python.repo zypper refresh zypper install salt salt\-minion salt\-master .ft P .fi .UNINDENT .UNINDENT .sp For openSUSE 12.2 run the following as root: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C zypper addrepo http://download.opensuse.org/repositories/devel:languages:python/openSUSE_12.2/devel:languages:python.repo zypper refresh zypper install salt salt\-minion salt\-master .ft P .fi .UNINDENT .UNINDENT .sp For openSUSE 12.1 run the following as root: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C zypper addrepo http://download.opensuse.org/repositories/devel:languages:python/openSUSE_12.1/devel:languages:python.repo zypper refresh zypper install salt salt\-minion salt\-master .ft P .fi .UNINDENT .UNINDENT .sp For bleeding edge python Factory run the following as root: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C zypper addrepo http://download.opensuse.org/repositories/devel:languages:python/bleeding_edge_python_Factory/devel:languages:python.repo zypper refresh zypper install salt salt\-minion salt\-master .ft P .fi .UNINDENT .UNINDENT .SS Suse Linux Enterprise .sp For SLE 11 SP3 run the following as root: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C zypper addrepo http://download.opensuse.org/repositories/devel:languages:python/SLE_11_SP3/devel:languages:python.repo zypper refresh zypper install salt salt\-minion salt\-master .ft P .fi .UNINDENT .UNINDENT .sp For SLE 11 SP2 run the following as root: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C zypper addrepo http://download.opensuse.org/repositories/devel:languages:python/SLE_11_SP2/devel:languages:python.repo zypper refresh zypper install salt salt\-minion salt\-master .ft P .fi .UNINDENT .UNINDENT .sp Now go to the \fBConfiguring Salt\fP page. .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 >= 3.2.0 .IP \(bu 2 \fI\%pyzmq\fP >= 2.2.0 \- 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 .SS Upgrading Salt .sp When upgrading Salt, the master(s) should always be upgraded first. Backwards compatibility for minions running newer versions of salt than their masters is not guaranteed. .sp Whenever possible, backwards compatibility between new masters and old minions will be preserved. Generally, the only exception to this policy is in case of a security vulnerability. .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: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C \- #interface: 0.0.0.0 + interface: 10.0.0.1 .ft P .fi .UNINDENT .UNINDENT .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: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C \- #master: salt + master: 10.0.0.1 .ft P .fi .UNINDENT .UNINDENT .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): .INDENT 3.0 .INDENT 3.5 .sp .nf .ft C salt\-master .ft P .fi .UNINDENT .UNINDENT .IP 2. 3 Start the minion in the foreground (to daemonize the process, pass the \fI\-d flag\fP): .INDENT 3.0 .INDENT 3.5 .sp .nf .ft C salt\-minion .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .INDENT 3.5 .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: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt\-master \-\-log\-level=debug .ft P .fi .UNINDENT .UNINDENT .sp For information on salt\(aqs logging system please see the \fBlogging document\fP\&. .UNINDENT .UNINDENT .INDENT 0.0 .INDENT 3.5 .IP "Run as an unprivileged (non\-root) user" .sp To run Salt as another user, set the \fBuser\fP parameter in the master config file. .sp Additionally, ownership and permissions need to be set such that the desired user can read from and write to the following directories (and their subdirectories, where applicable): .INDENT 0.0 .IP \(bu 2 /etc/salt .IP \(bu 2 /var/cache/salt .IP \(bu 2 /var/log/salt .UNINDENT .sp More information about running salt as a non\-privileged user can be found \fBhere\fP\&. .UNINDENT .UNINDENT .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: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C [root@master ~]# salt\-key \-L Unaccepted Keys: alpha bravo charlie delta Accepted Keys: .ft P .fi .UNINDENT .UNINDENT .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: .INDENT 0.0 .INDENT 3.5 .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 .UNINDENT .UNINDENT .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\&. .sp \fBSEE ALSO:\fP .INDENT 0.0 .INDENT 3.5 \fBsalt\-key manpage\fP .UNINDENT .UNINDENT .SS Sending Commands .sp Communication between the Master and a Minion may be verified by running the \fBtest.ping\fP command: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C [root@master ~]# salt alpha test.ping alpha: True .ft P .fi .UNINDENT .UNINDENT .sp Communication between the Master and all Minions may be tested in a similar way: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C [root@master ~]# salt \(aq*\(aq test.ping alpha: True bravo: True charlie: True delta: True .ft P .fi .UNINDENT .UNINDENT .sp Each of the Minions should send a \fBTrue\fP response as shown above. .SS What\(aqs Next? .sp Understanding \fBtargeting\fP is important. From there, depending on the way you wish to use Salt, you should also proceed to learn about \fBStates\fP and \fBExecution Modules\fP\&. .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: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C git checkout \-b fixed\-broken\-thing Switched to a new branch \(aqfixed\-broken\-thing\(aq .ft P .fi .UNINDENT .UNINDENT .sp Choose a name for your branch that describes its purpose. .sp Now commit your changes to this new branch with the following command: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C git commit \-am \(aqdescription of my fixes for the broken thing\(aq .ft P .fi .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 Using \fBgit commit \-am\fP, followed by a quoted string, both stages and commits all modified files in a single command. Depending on the nature of your changes, you may wish to stage and commit them separately. Also, note that if you wish to add newly\-tracked files as part of your commit, they will not be caught using \fBgit commit \-am\fP and will need to be added using \fBgit add\fP before committing. .UNINDENT .UNINDENT .sp Push your locally\-committed changes back up to GitHub: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C git push \-\-set\-upstream origin fixed\-broken\-thing .ft P .fi .UNINDENT .UNINDENT .sp Now go look at your fork of the salt repo on the GitHub website. The new branch will now be listed under the "Source" tab where it says "Switch Branches". Select the new branch from this list, and then click the "Pull request" button. .sp Put in a descriptive comment, and include links to any project issues related to the pull request. .sp The repo managers will be notified of your pull request and it will be reviewed. If a reviewer asks for changes, just make the changes locally in the same local feature branch, push them to GitHub, then add a comment to the discussion section of the pull request. .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 Travis\-CI .sp To make reviewing pull requests easier for the maintainers, please enable Travis\-CI on your fork. Salt is already configured, so simply follow the first 2 steps on the Travis\-CI \fI\%Getting Started Doc\fP\&. .UNINDENT .UNINDENT .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: .INDENT 0.0 .INDENT 3.5 .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 .UNINDENT .UNINDENT .sp To check the log to be sure that you actually want the changes, run the following before merging: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C git log upstream/develop .ft P .fi .UNINDENT .UNINDENT .sp Then to accept the changes and merge into the current branch: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C git merge upstream/develop .ft P .fi .UNINDENT .UNINDENT .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: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C git clone https://github.com/saltstack/salt .ft P .fi .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 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: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C git remote add upstream http://github.com/saltstack/salt .ft P .fi .UNINDENT .UNINDENT .sp Fetching tags is done with the git \(aqfetch\(aq utility: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C git fetch \-\-tags upstream .ft P .fi .UNINDENT .UNINDENT .UNINDENT .UNINDENT .sp Create a new \fI\%virtualenv\fP: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C virtualenv /path/to/your/virtualenv .ft P .fi .UNINDENT .UNINDENT .sp On Arch Linux, where Python 3 is the default installation of Python, use the \fBvirtualenv2\fP command instead of \fBvirtualenv\fP\&. .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 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. .UNINDENT .UNINDENT .sp Activate the virtualenv: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C source /path/to/your/virtualenv/bin/activate .ft P .fi .UNINDENT .UNINDENT .sp Install Salt (and dependencies) into the virtualenv: .INDENT 0.0 .INDENT 3.5 .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 .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 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: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C env SWIG_FEATURES="\-cpperraswarn \-includeall \-D__\(gauname \-m\(ga__ \-I/usr/include/openssl" pip install M2Crypto .ft P .fi .UNINDENT .UNINDENT .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: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C apt\-get install python\-m2crypto .ft P .fi .UNINDENT .UNINDENT .sp This also means that pulling in the M2Crypto installed using apt requires using \fB\-\-system\-site\-packages\fP when creating the virtualenv. .sp If you\(aqre using a platform other than Debian or Ubuntu, and you are installing M2Crypto via pip instead of a system package, then you will also need the \fBgcc\fP compiler. .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 Installing psutil .sp Python header files are required to build this module, otherwise the pip install will fail. If your distribution separates binaries and headers into separate packages, make sure that you have the headers installed. In most Linux distributions which split the headers into their own package, this can be done by installing the \fBpython\-dev\fP or \fBpython\-devel\fP package. For other platforms, the package will likely be similarly named. .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 Installing dependencies on OS X. .sp You can install needed dependencies on OS X using homebrew or macports. See \fBOS X Installation\fP .UNINDENT .UNINDENT .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: .INDENT 0.0 .INDENT 3.5 .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 .UNINDENT .UNINDENT .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. .IP 5. 3 If you changed the \fBret_port\fP value in the master config because you are also running a non\-development version of Salt, then you will have to change the \fBmaster_port\fP value in the minion config to match. .UNINDENT .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 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\&. .UNINDENT .UNINDENT .sp Start the master and minion, accept the minion\(aqs key, and verify your local Salt installation is working: .INDENT 0.0 .INDENT 3.5 .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 .UNINDENT .UNINDENT .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: .INDENT 0.0 .INDENT 3.5 .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 .UNINDENT .UNINDENT .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. .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 File descriptor limits .sp Ensure that the system open file limit is raised to at least 2047: .INDENT 0.0 .INDENT 3.5 .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 .UNINDENT .UNINDENT .sp To set file descriptors on OSX, refer to the \fBOS X Installation\fP instructions. .UNINDENT .UNINDENT .SS Installing Salt from the Python Package Index .sp If you are installing using \fBeasy_install\fP, you will need to define a \fBUSE_SETUPTOOLS\fP environment variable, otherwise dependencies will not be installed: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C USE_SETUPTOOLS=1 easy_install salt .ft P .fi .UNINDENT .UNINDENT .SS Editing and previewing the documentation .sp You need \fBsphinx\-build\fP command to build the docs. In Debian/Ubuntu this is provided in the \fBpython\-sphinx\fP package. Sphinx can also be installed to a virtualenv using pip: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C pip install Sphinx .ft P .fi .UNINDENT .UNINDENT .sp Change to salt documentation directory, then: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C cd doc; make html .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .IP \(bu 2 This will build the HTML docs. Run \fBmake\fP without any arguments to see the available make targets, which include \fBhtml\fP, \fBman\fP, and \fBtext\fP\&. .IP \(bu 2 The docs then are built within the \fBdocs/_build/\fP folder. To update the docs after making changes, run \fBmake\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 To build the docs on Arch Linux, the \fBpython2\-sphinx\fP package is required. Additionally, it is necessary to tell \fBmake\fP where to find the proper \fBsphinx\-build\fP binary, like so: .UNINDENT .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C make SPHINXBUILD=sphinx\-build2 html .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .IP \(bu 2 To build the docs on RHEL/CentOS 6, the \fBpython\-sphinx10\fP package must be installed from EPEL, and the following make command must be used: .UNINDENT .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C make SPHINXBUILD=sphinx\-1.0\-build html .ft P .fi .UNINDENT .UNINDENT .sp Once you\(aqve updated the documentation, you can run the following command to launch a simple Python HTTP server to see your changes: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C cd _build/html; python \-m SimpleHTTPServer .ft P .fi .UNINDENT .UNINDENT .SS Running unit and integration tests .sp Run the test suite with following command: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C \&./setup.py test .ft P .fi .UNINDENT .UNINDENT .sp See \fBhere\fP for more information regarding the test suite. .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: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C base: \(aqweb1\(aq: \- webserver .ft P .fi .UNINDENT .UNINDENT .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. .sp \fBTIP:\fP .INDENT 0.0 .INDENT 3.5 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. .UNINDENT .UNINDENT .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\&. .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 You must wrap \fBsalt\fP calls that use globbing in single\-quotes to prevent the shell from expanding the globs before Salt is invoked. .UNINDENT .UNINDENT .sp Match all minions: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq test.ping .ft P .fi .UNINDENT .UNINDENT .sp Match all minions in the example.net domain or any of the example domains: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*.example.net\(aq test.ping salt \(aq*.example.*\(aq test.ping .ft P .fi .UNINDENT .UNINDENT .sp Match all the \fBwebN\fP minions in the example.net domain (\fBweb1.example.net\fP, \fBweb2.example.net\fP … \fBwebN.example.net\fP): .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt \(aqweb?.example.net\(aq test.ping .ft P .fi .UNINDENT .UNINDENT .sp Match the \fBweb1\fP through \fBweb5\fP minions: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt \(aqweb[1\-5]\(aq test.ping .ft P .fi .UNINDENT .UNINDENT .sp Match the \fBweb1\fP and \fBweb3\fP minions: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt \(aqweb[1,3]\(aq test.ping .ft P .fi .UNINDENT .UNINDENT .sp Match the \fBweb\-x\fP, \fBweb\-y\fP, and \fBweb\-z\fP minions: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt \(aqweb\-[x\-z]\(aq test.ping .ft P .fi .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 For additional targeting methods please review the \fBcompound matchers\fP documentation. .UNINDENT .UNINDENT .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: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt \-E \(aqweb1\-(prod|devel)\(aq test.ping .ft P .fi .UNINDENT .UNINDENT .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. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C base: \(aqweb1\-(prod|devel)\(aq: \- match: pcre \- webserver .ft P .fi .UNINDENT .UNINDENT .SS Lists .sp At the most basic level, you can specify a flat list of minion IDs: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt \-L \(aqweb1,web2,web3\(aq test.ping .ft P .fi .UNINDENT .UNINDENT .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: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt \-G \(aqos:CentOS\(aq test.ping .ft P .fi .UNINDENT .UNINDENT .sp Match all minions with 64\-bit CPUs, and return number of CPU cores for each matching minion: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt \-G \(aqcpuarch:x86_64\(aq grains.item num_cpus .ft P .fi .UNINDENT .UNINDENT .sp Additionally, globs can be used in grain matches, and grains that are nested in a \fI\%dictionary\fP can be matched by adding a colon for each level that is traversed. For example, the following will match hosts that have a grain called \fBec2_tags\fP, which itself is a \fI\%dict\fP with a key named \fBenvironment\fP, which has a value that contains the word \fBproduction\fP: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt \-G \(aqec2_tags:environment:*production*\(aq .ft P .fi .UNINDENT .UNINDENT .SS Listing Grains .sp Available grains can be listed by using the \(aqgrains.ls\(aq module: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq grains.ls .ft P .fi .UNINDENT .UNINDENT .sp Grains data can be listed by using the \(aqgrains.items\(aq module: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq grains.items .ft P .fi .UNINDENT .UNINDENT .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: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C grains: roles: \- webserver \- memcache deployment: datacenter4 cabinet: 13 cab_u: 14\-15 .ft P .fi .UNINDENT .UNINDENT .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 Grains in /etc/salt/grains .sp If you do not want to place your custom static grains in the minion config file, you can also put them in \fB/etc/salt/grains\fP on the minion. They are configured in the same way as in the above example, only without a top\-level \fBgrains:\fP key: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C roles: \- webserver \- memcache deployment: datacenter4 cabinet: 13 cab_u: 14\-15 .ft P .fi .UNINDENT .UNINDENT .SS Matching Grains in the Top File .sp With correctly setup grains on the Minion, the Top file used in Pillar or during Highstate can be made really efficient. Like for example, you could do: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C \(aqnode_type:web\(aq: \- match: grain \- webserver \(aqnode_type:postgres\(aq: \- match: grain \- database \(aqnode_type:redis\(aq: \- match: grain \- redis \(aqnode_type:lb\(aq: \- match: grain \- lb .ft P .fi .UNINDENT .UNINDENT .sp For this example to work, you would need the grain \fBnode_type\fP and the correct value to match on. This simple example is nice, but too much of the code is similar. To go one step further, we can place some Jinja template code into the Top file. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C {% set self = grains[\(aqnode_type\(aq] %} \(aqnode_type:{{ self }}\(aq: \- match: grain \- {{ self }} .ft P .fi .UNINDENT .UNINDENT .sp The Jinja code simplified the Top file, and allowed SaltStack to work its magic. .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 \fI\%dict\fP 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 Precedence .sp Core grains can be overriden by custom grains. As there are several ways of defining custom grains, there is an order of precedence which should be kept in mind when defining them. The order of evaluation is as follows: .INDENT 0.0 .IP 1. 3 Core grains. .IP 2. 3 Custom grains in \fB/etc/salt/grains\fP\&. .IP 3. 3 Custom grains in \fB/etc/salt/minion\fP\&. .IP 4. 3 Custom grain modules in \fB_grains\fP directory, synced to minions. .UNINDENT .sp Each successive evaluation overrides the previous ones, so any grains defined in \fB/etc/salt/grains\fP that have the same name as a core grain will override that core grain. Similarly, \fB/etc/salt/minion\fP overrides both core grains and grains set in \fB/etc/salt/grains\fP, and custom grain modules will override \fIany\fP grains of the same name. .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 \fBstate.highstate\fP is called, or (as noted above) the grains can be manually synced and reloaded by calling the \fBsaltutil.sync_grains\fP or \fBsaltutil.sync_all\fP 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 compound target documentation can be found \fBhere\fP\&. .sp The \fBnodegroups\fP master config file parameter is used to define nodegroups. Here\(aqs an example nodegroup configuration within \fB/etc/salt/master\fP: .INDENT 0.0 .INDENT 3.5 .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 .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 The \(aqL\(aq within group1 is matching a list of minions, while the \(aqG\(aq in group2 is matching specific grains. See the \fBcompound matchers\fP documentation for more details. .UNINDENT .UNINDENT .sp To match a nodegroup on the CLI, use the \fB\-N\fP command\-line option: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt \-N group1 test.ping .ft P .fi .UNINDENT .UNINDENT .sp To match in your \fItop file\fP, make sure to put \fB\- match: nodegroup\fP on the line directly following the nodegroup name. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C base: group1: \- match: nodegroup \- webserver .ft P .fi .UNINDENT .UNINDENT .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 Salt\(aqs matchers. The default matcher is a \fI\%glob\fP match, just as with CLI and \fItop file\fP matching. To match using anything other than a glob, prefix the match string with the appropriate letter from the table below, followed by an \fB@\fP sign. .TS center; |l|l|l|. _ T{ Letter T} T{ Match Type T} T{ Example T} _ T{ G T} T{ Grains glob T} T{ \fBG@os:Ubuntu\fP T} _ T{ E T} T{ PCRE Minion ID T} T{ \fBE@web\ed+\e.(dev|qa|prod)\e.loc\fP T} _ T{ P T} T{ Grains PCRE 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 T} T{ \fBI@pdata:foobar\fP T} _ T{ S T} T{ Subnet/IP address T} T{ \fBS@192.168.1.0/24\fP or \fBS@192.168.1.100\fP T} _ T{ R T} T{ Range cluster T} T{ \fBR@%foo.bar\fP T} _ .TE .nf Matchers can be joined using boolean \fBand\fP, \fBor\fP, and \fBnot\fP operators. .fi .sp .sp For example, the following string matches all Debian minions with a hostname that begins with \fBwebserv\fP, as well as any minions that have a hostname which matches the \fI\%regular expression\fP \fBweb\-dc1\-srv.*\fP: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt \-C \(aqwebserv* and G@os:Debian or E@web\-dc1\-srv.*\(aq test.ping .ft P .fi .UNINDENT .UNINDENT .sp That same example expressed in a \fItop file\fP looks like the following: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C base: \(aqwebserv* and G@os:Debian or E@web\-dc1\-srv.*\(aq: \- match: compound \- webserver .ft P .fi .UNINDENT .UNINDENT .sp Note that a leading \fBnot\fP is not supported in compound matches. Instead, something like the following must be done: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt \-C \(aq* and not G@kernel:Darwin\(aq test.ping .ft P .fi .UNINDENT .UNINDENT .sp Excluding a minion based on its ID is also possible: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt \-C \(aq* and not web\-dc1\-srv\(aq test.ping .ft P .fi .UNINDENT .UNINDENT .SS Batch Size .sp The \fB\-b\fP (or \fB\-\-batch\-size\fP) option allows commands to be executed on only a specified number of minions at a time. Both percentages and finite numbers are supported. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq \-b 10 test.ping salt \-G \(aqos:RedHat\(aq \-\-batch\-size 25% apache.signal restart .ft P .fi .UNINDENT .UNINDENT .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 Introduction .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: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt\-call \-\-local state.highstate .ft P .fi .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 When running Salt in masterless mode, do not run the salt\-minion daemon. Otherwise, it will attempt to connect to a master and fail. The salt\-call command stands on its own and does not need the salt\-minion daemon. .UNINDENT .UNINDENT .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: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C wget \-O \- http://bootstrap.saltstack.org | sudo sh .ft P .fi .UNINDENT .UNINDENT .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\&. .INDENT 0.0 .IP 1. 3 Create the top.sls file: .UNINDENT .sp \fB/srv/salt/top.sls:\fP .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C base: \(aq*\(aq: \- webserver .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .IP 2. 3 Create our webserver state tree: .UNINDENT .sp \fB/srv/salt/webserver.sls:\fP .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C apache: # ID declaration pkg: # state declaration \- installed # function declaration .ft P .fi .UNINDENT .UNINDENT .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: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt\-call \-\-local state.highstate \-l debug .ft P .fi .UNINDENT .UNINDENT .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 Basics .SS Salt Bootstrap .sp The Salt Bootstrap script allows for a user to install the Salt Minion or Master on a variety of system distributions and versions. This shell script known as \fBbootstrap\-salt.sh\fP runs through a series of checks to determine the operating system type and version. It then installs the Salt binaries using the appropriate methods. The Salt Bootstrap script installs the minimum number of packages required to run Salt. This means that in the event you run the bootstrap to install via package, Git will not be installed. Installing the minimum number of packages helps ensure the script stays as lightweight as possible, assuming the user will install any other required packages after the Salt binaries are present on the system. The script source is available on GitHub: \fI\%https://github.com/saltstack/salt\-bootstrap\fP .SS Supported Operating Systems .INDENT 0.0 .IP \(bu 2 Amazon Linux 2012.09 .IP \(bu 2 Arch .IP \(bu 2 CentOS 5/6 .IP \(bu 2 Debian 6.x/7.x .IP \(bu 2 Fedora 17/18 .IP \(bu 2 FreeBSD 9.1 .IP \(bu 2 Gentoo .IP \(bu 2 Linaro .IP \(bu 2 Linux Mint 13/14 .IP \(bu 2 OpenSUSE 12.x .IP \(bu 2 Red Hat 5/6 .IP \(bu 2 Red Hat Enterprise 5/6 .IP \(bu 2 SmartOS .IP \(bu 2 SuSE 11 SP1/11 SP2 .IP \(bu 2 Ubuntu 10.x/11.x/12.x/13.04 .UNINDENT .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 In the event you do not see your distribution or version available please review the develop branch on Github as it main contain updates that are not present in the stable release: \fI\%https://github.com/saltstack/salt\-bootstrap/tree/develop\fP .UNINDENT .UNINDENT .SS Example Usage .sp The Salt Bootstrap script has a wide variety of options that can be passed as well as several ways of obtaining the bootstrap script itself. .sp For example, using \fBcurl\fP to install latest git: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C curl \-L http://bootstrap.saltstack.org | sudo sh \-s \-\- git develop .ft P .fi .UNINDENT .UNINDENT .sp If you have certificate issues using \fBcurl\fP, try the following: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C curl \-\-insecure \-L http://bootstrap.saltstack.org | sudo sh \-s \-\- git develop .ft P .fi .UNINDENT .UNINDENT .sp Using \fBwget\fP to install your distribution\(aqs stable packages: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C wget \-O \- http://bootstrap.saltstack.org | sudo sh .ft P .fi .UNINDENT .UNINDENT .sp If you have certificate issues using \fBwget\fP try the following: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C wget \-\-no\-check\-certificate \-O \- http://bootstrap.saltstack.org | sudo sh .ft P .fi .UNINDENT .UNINDENT .sp Install a specific version from git using \fBwget\fP: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C wget \-O \- http://bootstrap.saltstack.org | sh \-s \-\- \-P git v0.16.4 .ft P .fi .UNINDENT .UNINDENT .sp If you already have python installed, \fBpython 2.6\fP, then it\(aqs as easy as: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C python \-m urllib "http://bootstrap.saltstack.org" | sudo sh \-s \-\- git develop .ft P .fi .UNINDENT .UNINDENT .sp All python versions should support the following one liner: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C python \-c \(aqimport urllib; print urllib.urlopen("http://bootstrap.saltstack.org").read()\(aq | \e sudo sh \-s \-\- git develop .ft P .fi .UNINDENT .UNINDENT .sp On a FreeBSD base system you usually don\(aqt have either of the above binaries available. You \fBdo\fP have \fBfetch\fP available though: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C fetch \-o \- http://bootstrap.saltstack.org | sudo sh .ft P .fi .UNINDENT .UNINDENT .sp If all you want is to install a \fBsalt\-master\fP using latest git: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C curl \-L http://bootstrap.saltstack.org | sudo sh \-s \-\- \-M \-N git develop .ft P .fi .UNINDENT .UNINDENT .sp If you want to install a specific release version (based on the git tags): .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C curl \-L http://bootstrap.saltstack.org | sudo sh \-s \-\- git v0.16.4 .ft P .fi .UNINDENT .UNINDENT .sp Downloading the develop branch (from here standard command line options may be passed): .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C wget https://raw.githubusercontent.com/saltstack/salt\-bootstrap/develop/bootstrap\-salt.sh .ft P .fi .UNINDENT .UNINDENT .SS Command Line Options .sp \fB\-h\fP Display the help message and command line options. .sp \fB\-v\fP Display script version. .sp \fB\-n\fP No colours. .sp \fB\-D\fP Show debug output. .sp \fB\-c\fP Temporary configuration directory. .sp \fB\-k\fP Temporary directory holding the minion keys which will pre\-seed the master. .sp \fB\-M\fP Also install salt\-master. .sp \fB\-S\fP Also install salt\-syndic. .sp \fB\-N\fP Do not install salt\-minion. .sp \fB\-X\fP Do not start daemons after installation. .sp \fB\-C\fP Only run the configuration function. This option automatically bypasses any installation. .sp \fB\-P\fP Allow pip based installations. On some distributions the required salt packages or its dependencies are not available as a package for that distribution. Using this flag allows the script to use pip as a last resort method. .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 This works for functions which actually implement pip based installations. .UNINDENT .UNINDENT .sp \fB\-F\fP Allow copied files to overwrite existing(config, init.d, etc). .sp \fB\-U\fP If set, fully upgrade the system prior to bootstrapping salt. .sp \fB\-K\fP If set, keep the temporary files in the temporary directories specified with \-c and \-k. .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 .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 When running Salt in masterless mode, do not run the salt\-minion daemon. Otherwise, it will attempt to connect to a master and fail. The salt\-call command stands on its own and does not need the salt\-minion daemon. .UNINDENT .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. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C file_client: local .ft P .fi .UNINDENT .UNINDENT .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: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C file_roots: base: \- /srv/salt .ft P .fi .UNINDENT .UNINDENT .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: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt\-call state.highstate .ft P .fi .UNINDENT .UNINDENT .sp Or the salt\-call command can be executed with the \fB\-\-local\fP flag, this makes it unnecessary to change the configuration file: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt\-call state.highstate \-\-local .ft P .fi .UNINDENT .UNINDENT .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 TCP 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. .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 No firewall configuration needs to be done on Salt minions. These changes refer to the master only. .UNINDENT .UNINDENT .SS RHEL 6 / CentOS 6 .sp The \fBlokkit\fP 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: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C lokkit \-p 22:tcp \-p 4505:tcp \-p 4506:tcp .ft P .fi .UNINDENT .UNINDENT .sp The \fBsystem\-config\-firewall\-tui\fP command provides a text\-based interface to modifying the firewall. .sp \fBsystem\-config\-firewall\-tui\fP: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C system\-config\-firewall\-tui .ft P .fi .UNINDENT .UNINDENT .SS openSUSE .sp Salt installs firewall rules in \fI\%/etc/sysconfig/SuSEfirewall2.d/services/salt\fP\&. Enable with: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C SuSEfirewall2 open SuSEfirewall2 start .ft P .fi .UNINDENT .UNINDENT .sp If you have an older package of Salt where the above configuration file is not included, the \fBSuSEfirewall2\fP command makes opening iptables firewall ports very simple via the command line. .sp \fBSuSEfirewall example\fP: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C SuSEfirewall2 open EXT TCP 4505 SuSEfirewall2 open EXT TCP 4506 .ft P .fi .UNINDENT .UNINDENT .sp The firewall module in YaST2 provides a text\-based interface to modifying the firewall. .sp \fBYaST2\fP: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C yast2 firewall .ft P .fi .UNINDENT .UNINDENT .SS iptables .sp Different Linux distributions store their \fIiptables\fP (also known as \fI\%netfilter\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: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C /etc/sysconfig/iptables .ft P .fi .UNINDENT .UNINDENT .sp \fBArch Linux\fP: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C /etc/iptables/iptables.rules .ft P .fi .UNINDENT .UNINDENT .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: .INDENT 0.0 .INDENT 3.5 .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 .UNINDENT .UNINDENT .sp \fBUbuntu\fP .sp Salt installs firewall rules in \fI\%/etc/ufw/applications.d/salt.ufw\fP\&. Enable with: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C ufw allow salt .ft P .fi .UNINDENT .UNINDENT .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. .INDENT 0.0 .INDENT 3.5 .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 .UNINDENT .UNINDENT .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. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C pfctl \-vf /etc/pf.conf .ft P .fi .UNINDENT .UNINDENT .SS Whitelist communication to Master .sp There are situations where you want to selectively allow Minon traffic from specific hosts or networks into your Salt Master. The first scenario which comes to mind is to prevent unwanted traffic to your Master out of security concerns, but another scenario is to handle Minion upgrades when there are backwards incompatible changes between the installed Salt versions in your environment. .sp Here is an example \fILinux iptables\fP ruleset to be set on the Master: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C # Allow Minions from these networks \-I INPUT \-s 10.1.2.0/24 \-p tcp \-m multiport \-\-dports 4505,4506 \-j ACCEPT \-I INPUT \-s 10.1.3.0/24 \-p tcp \-m multiport \-\-dports 4505,4506 \-j ACCEPT # Allow Salt to communicate with Master on the loopback interface \-A INPUT \-i lo \-p tcp \-m multiport \-\-dports 4505,4506 \-j ACCEPT # Reject everything else \-A INPUT \-p tcp \-m multiport \-\-dports 4505,4506 \-j REJECT .ft P .fi .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 The important thing to note here is that the \fBsalt\fP command needs to communicate with the listening network socket of \fBsalt\-master\fP on the \fIloopback\fP interface. Without this you will see no outgoing Salt traffic from the master, even for a simple \fBsalt \(aq*\(aq test.ping\fP, because the \fBsalt\fP client never reached the \fBsalt\-master\fP to tell it to carry out the execution. .UNINDENT .UNINDENT .SS Using cron with Salt .sp The Salt Minion can initiate its own highstate using the \fBsalt\-call\fP command. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C $ salt\-call state.highstate .ft P .fi .UNINDENT .UNINDENT .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 \fBsalt\-call\fP command. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C # PATH=/bin:/sbin:/usr/bin:/usr/sbin 00 00 * * * salt\-call state.highstate .ft P .fi .UNINDENT .UNINDENT .sp The above cron entry will run a highstate every day at midnight. .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 Be aware that you may need to ensure the PATH for cron includes any scripts or commands that need to be executed. .UNINDENT .UNINDENT .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. .INDENT 0.0 .INDENT 3.5 .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. .UNINDENT .UNINDENT .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: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt \(aq\(aq [arguments] .ft P .fi .UNINDENT .UNINDENT .sp \fBSEE ALSO:\fP .INDENT 0.0 .INDENT 3.5 \fBsalt manpage\fP .UNINDENT .UNINDENT .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: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq test.ping salt \(aq*.example.org\(aq test.ping .ft P .fi .UNINDENT .UNINDENT .sp Targets can be based on minion system information using the Grains system: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt \-G \(aqos:Ubuntu\(aq test.ping .ft P .fi .UNINDENT .UNINDENT .sp \fBSEE ALSO:\fP .INDENT 0.0 .INDENT 3.5 \fBGrains system\fP .UNINDENT .UNINDENT .sp Targets can be filtered by regular expression: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt \-E \(aqvirtmach[0\-9]\(aq test.ping .ft P .fi .UNINDENT .UNINDENT .sp Targets can be explicitly specified in a list: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt \-L \(aqfoo,bar,baz,quo\(aq test.ping .ft P .fi .UNINDENT .UNINDENT .sp Or Multiple target types can be combined in one command: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt \-C \(aqG@os:Ubuntu and webser* or E@database.*\(aq test.ping .ft P .fi .UNINDENT .UNINDENT .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: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq sys.doc .ft P .fi .UNINDENT .UNINDENT .sp Here are some examples: .sp Show all currently available minions: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq test.ping .ft P .fi .UNINDENT .UNINDENT .sp Run an arbitrary shell command: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq cmd.run \(aquname \-a\(aq .ft P .fi .UNINDENT .UNINDENT .sp \fBSEE ALSO:\fP .INDENT 0.0 .INDENT 3.5 \fBthe full list of modules\fP .UNINDENT .UNINDENT .SS arguments .sp Space\-delimited arguments to the function: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq cmd.exec_code python \(aqimport sys; print sys.version\(aq .ft P .fi .UNINDENT .UNINDENT .sp Optional, keyword arguments are also supported: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pip.install salt timeout=5 upgrade=True .ft P .fi .UNINDENT .UNINDENT .sp They are always in the form of \fBkwarg=argument\fP\&. .SS Pillar Walkthrough .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 This walkthrough assumes that the reader has already completed the initial Salt \fBwalkthrough\fP\&. .UNINDENT .UNINDENT .sp The pillar interface inside of Salt is one of the most important components of a Salt deployment. Pillar is the interface used to generate arbitrary data for specific minions. The data generated in pillar is made available to almost every component of Salt and is used for a number of purposes: .INDENT 0.0 .TP .B Highly Sensitive Data: Information transferred via pillar is guaranteed to only be presented to the minions that are targeted, this makes pillar the engine to use in Salt for managing security information, such as cryptographic keys and passwords. .TP .B Minion Configuration: Minion modules such as the execution modules, states, and returners can often be configured via data stored in pillar. .TP .B Variables: Variables which need to be assigned to specific minions or groups of minions can be defined in pillar and then accessed inside sls formulas and template files. .TP .B Arbitrary Data: Pillar can contain any basic data structure, so a list of values, or a key/value store can be defined making it easy to iterate over a group of values in sls formulas .UNINDENT .sp Pillar is therefore one of the most important systems when using Salt, this walkthrough is designed to get a simple pillar up and running in a few minutes and then to dive into the capabilities of pillar and where the data is available. .SS Setting Up Pillar .sp The pillar is already running in Salt by default. The data in the minion\(aqs pillars can be seen via the following command: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pillar.items .ft P .fi .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 Prior to version 0.16.2, this function is named \fBpillar.data\fP\&. This function name is still supported for backwards compatibility. .UNINDENT .UNINDENT .sp By default the contents of the master configuration file are loaded into pillar for all minions, this is to enable the master configuration file to be used for global configuration of minions. .sp The pillar is built in a similar fashion as the state tree, it is comprised of sls files and has a top file, just like the state tree. The pillar is stored in a different location on the Salt master than the state tree. The default location for the pillar is in /srv/pillar. .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 The pillar location can be configured via the \fIpillar_roots\fP option inside the master configuration file. .UNINDENT .UNINDENT .sp To start setting up the pillar, the /srv/pillar directory needs to be present: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C mkdir /srv/pillar .ft P .fi .UNINDENT .UNINDENT .sp Now a simple top file, following the same format as the top file used for states needs to be created: .sp \fB/srv/pillar/top.sls\fP: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C base: \(aq*\(aq: \- data .ft P .fi .UNINDENT .UNINDENT .sp This top file associates the data.sls file to all minions. Now the \fB/srv/pillar/data.sls\fP file needs to be populated: .sp \fB/srv/pillar/data.sls\fP: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C info: some data .ft P .fi .UNINDENT .UNINDENT .sp Now that the file has been saved the minions\(aq pillars will be updated: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pillar.items .ft P .fi .UNINDENT .UNINDENT .sp The key \fBinfo\fP should now appear in the returned pillar data. .SS More Complex Data .sp Pillar files are sls files, just like states, but unlike states they do not need to define \fBformulas\fP, the data can be arbitrary, this example for instance sets up user data with a UID: .sp \fB/srv/pillar/users/init.sls\fP: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C users: thatch: 1000 shouse: 1001 utahdave: 1002 redbeard: 1003 .ft P .fi .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 The same directory lookups that exist in states exist in pillar, so the file \fBusers/init.sls\fP can be referenced with \fBusers\fP in the \fItop file\fP\&. .UNINDENT .UNINDENT .sp The top file will need to be updated to include this sls file: .sp \fB/srv/pillar/top.sls\fP: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C base: \(aq*\(aq: \- data \- users .ft P .fi .UNINDENT .UNINDENT .sp Now the data will be available to the minions. To use the pillar data in a state just access the pillar via Jinja: .sp \fB/srv/salt/users/init.sls\fP .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C {% for user, uid in pillar.get(\(aqusers\(aq, {}).items() %} {{user}}: user.present: \- uid: {{uid}} {% endfor %} .ft P .fi .UNINDENT .UNINDENT .sp This approach allows for users to be safely defined in a pillar and then the user data is applied in an sls file. .SS Paramaterizing States With Pillar .sp One of the most powerful abstractions in pillar is the ability to parameterize states. Instead of defining macros or functions within the state context the entire state tree can be freely parameterized relative to the minion\(aqs pillar. .sp This approach allows for Salt to be very flexible while staying very straightforward. It also means that simple sls formulas used in the state tree can be directly parameterized without needing to refactor the state tree. .sp A simple example is to set up a mapping of package names in pillar for separate Linux distributions: .sp \fB/srv/pillar/pkg/init.sls\fP: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C pkgs: {% if grains[\(aqos_family\(aq] == \(aqRedHat\(aq %} apache: httpd vim: vim\-enhanced {% elif grains[\(aqos_family\(aq] == \(aqDebian\(aq %} apache: apache2 vim: vim {% elif grains[\(aqos\(aq] == \(aqArch\(aq %} apache: apache vim: vim {% endif %} .ft P .fi .UNINDENT .UNINDENT .sp The new \fBpkg\fP sls needs to be added to the top file: .sp \fB/srv/pillar/top.sls\fP: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C base: \(aq*\(aq: \- data \- users \- pkg .ft P .fi .UNINDENT .UNINDENT .sp Now the minions will auto map values based on respective operating systems inside of the pillar, so sls files can be safely parameterized: .sp \fB/srv/salt/apache/init.sls\fP: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C apache: pkg.installed: \- name: {{ pillar[\(aqpkgs\(aq][\(aqapache\(aq] }} .ft P .fi .UNINDENT .UNINDENT .sp Or, if no pillar is available a default can be set as well: .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 The function \fBpillar.get\fP used in this example was added to Salt in version 0.14.0 .UNINDENT .UNINDENT .sp \fB/srv/salt/apache/init.sls\fP: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C apache: pkg.installed: \- name: {{ salt[\(aqpillar.get\(aq](\(aqpkgs:apache\(aq, \(aqhttpd\(aq) }} .ft P .fi .UNINDENT .UNINDENT .sp In the above example, if the pillar value \fBpillar[\(aqpkgs\(aq][\(aqapache\(aq]\fP is not set in the minion\(aqs pillar, then the default of \fBhttpd\fP will be used. .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 Under the hood, pillar is just a python dict, so python dict methods such as \fIget\fP and \fIitems\fP can be used. .UNINDENT .UNINDENT .SS Pillar Makes Simple States Grow Easily .sp One of the design goals of pillar is to make simple sls formulas easily grow into more flexible formulas without refactoring or complicating the states. .sp A simple formula: .sp \fB/srv/salt/edit/vim.sls\fP: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C vim: pkg: \- installed /etc/vimrc: file.managed: \- source: salt://edit/vimrc \- mode: 644 \- user: root \- group: root \- require: \- pkg: vim .ft P .fi .UNINDENT .UNINDENT .sp Can be easily transformed into a powerful, parameterized formula: .sp \fB/srv/salt/edit/vim.sls\fP: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C vim: pkg: \- installed \- name: {{ pillar[\(aqpkgs\(aq][\(aqvim\(aq] }} /etc/vimrc: file.managed: \- source: {{ pillar[\(aqvimrc\(aq] }} \- mode: 644 \- user: root \- group: root \- require: \- pkg: vim .ft P .fi .UNINDENT .UNINDENT .sp Where the vimrc source location can now be changed via pillar: .sp \fB/srv/pillar/edit/vim.sls\fP: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C {% if grains[\(aqid\(aq].startswith(\(aqdev\(aq) %} vimrc: salt://edit/dev_vimrc {% elif grains[\(aqid\(aq].startswith(\(aqqa\(aq) %} vimrc: salt://edit/qa_vimrc {% else %} vimrc: salt://edit/vimrc {% endif %} .ft P .fi .UNINDENT .UNINDENT .sp Ensuring that the right vimrc is sent out to the correct minions. .SS More On Pillar .sp The pillar data is generated on the Salt master and securely distributed to minions. Salt is not restricted to the pillar sls files when defining the pillar but can retrieve data from external sources. This can be useful when information about an infrastructure is stored in a separate location. .sp Reference information on pillar and the external pillar interface can be found in the Salt documentation: .sp \fBPillar\fP .SS States .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. Salt States strive to do just that: K.I.S.S. (Keep It Stupidly Simple) .sp The core of the Salt State system is the SLS, or \fBS\fPa\fBL\fPt \fBS\fPtate file. The SLS is a representation of the state in which a system should be in, and is set up to contain this data in a simple format. This is often called configuration management. .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 This is just the beginning of using states, make sure to read up on pillar \fBPillar\fP next. .UNINDENT .UNINDENT .SS It is All Just Data .sp Before delving into the particulars, it will help to understand that the SLS file is just a data structure under the hood. While understanding that the SLS is just a data structure isn\(aqt critical for understanding and making use of Salt States, it should help bolster knowledge 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 one writes more state files, it becomes clearer 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. .SS The Top File .sp The example SLS files in the below sections can be assigned to hosts using a file called \fBtop.sls\fP\&. This file is described in\-depth \fBhere\fP\&. .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 \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 These demos use some generic service and package names, different distributions often use different names for packages and services. For instance \fIapache\fP should be replaced with \fIhttpd\fP on a Red Hat system. Salt uses the name of the init script, systemd name, upstart name etc. based on what the underlying service management for the platform. To get a list of the available service names on a platform execute the service.get_all salt function. .sp Information on how to make states work with multiple distributions is later in the tutorial. .UNINDENT .UNINDENT .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C apache: pkg: \- installed service: \- running \- require: \- pkg: apache .ft P .fi .UNINDENT .UNINDENT .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 be installed via the system\(aqs native package manager, and the service state manages a system daemon. .sp The third and fifth 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 six, is the word \fBrequire\fP\&. This is called a Requisite Statement, and it makes sure that the Apache service is only started after a 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. .INDENT 0.0 .INDENT 3.5 .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 .UNINDENT .UNINDENT .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 for any changes to the watched states. 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 in a scalable manner, more than one SLS will need to be used. The above examples were in a single SLS file, but two or more SLS files 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 structure on the Salt master; an 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: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C apache/init.sls apache/httpd.conf .ft P .fi .UNINDENT .UNINDENT .sp So the httpd.conf is just a file in the apache directory, and is referenced directly. .sp But when using more than one single SLS file, more components can be added to the toolkit. Consider this SSH example: .sp \fBssh/init.sls:\fP .INDENT 0.0 .INDENT 3.5 .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 .UNINDENT .UNINDENT .sp \fBssh/server.sls:\fP .INDENT 0.0 .INDENT 3.5 .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 .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 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. .UNINDENT .UNINDENT .sp Now our State Tree looks like this: .INDENT 0.0 .INDENT 3.5 .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 .UNINDENT .UNINDENT .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. .sp Note that some of the SLS files are called init.sls, while others are not. More info on what this means can be found in the \fIStates Tutorial\fP\&. .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 In these examples, the first will add a custom banner to ssh and the second will add more watchers to apache to include mod_python. .sp \fBssh/custom\-server.sls:\fP .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C include: \- ssh.server extend: /etc/ssh/banner: file: \- source: salt://ssh/custom\-banner .ft P .fi .UNINDENT .UNINDENT .sp \fBpython/mod_python.sls:\fP .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C include: \- apache extend: apache: service: \- watch: \- pkg: mod_python mod_python: pkg.installed .ft P .fi .UNINDENT .UNINDENT .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. .INDENT 0.0 .INDENT 3.5 .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. .UNINDENT .UNINDENT .SS Understanding the Render System .sp Since SLS data is simply that (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 and \fBpydsl\fP renderers. 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; while the \fBpydsl\fP renderer provides a flexible, domain\-specific language for authoring SLS data in Python. .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 The templating engines described above aren\(aqt just available in SLS files. They can also be used in \fBfile.managed\fP states, making file management much more dynamic and flexible. Some examples for using templates in managed files can be found in the documentation for the \fBfile states\fP, as well as the \fIMooseFS example\fP below. .UNINDENT .UNINDENT .SS Getting to Know the Default \- yaml_jinja .sp The default renderer \- \fByaml_jinja\fP, allows for 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 .INDENT 0.0 .INDENT 3.5 .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 .UNINDENT .UNINDENT .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 .INDENT 0.0 .INDENT 3.5 .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 %} /etc/mfshdd.cfg: file.managed: \- source: salt://moosefs/mfshdd.cfg \- user: root \- group: root \- mode: 644 \- template: jinja \- require: \- pkg: mfs\-chunkserver /etc/mfschunkserver.cfg: 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 .UNINDENT .UNINDENT .sp This example shows much more of the available power of 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 and the PyDSL Renderers .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 an 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 .INDENT 0.0 .INDENT 3.5 .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 .UNINDENT .UNINDENT .sp This is a very simple example; the first line has an SLS shebang 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 Alternatively, using the \fBpydsl\fP renderer, the above example can be written more succinctly as: .sp \fBpython/django.sls:\fP .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C #!pydsl include(\(aqpython\(aq, delayed=True) state(\(aqdjango\(aq).pkg.installed() .ft P .fi .UNINDENT .UNINDENT .sp This Python examples would look like this if they were written in YAML: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C include: \- python django: pkg.installed .ft P .fi .UNINDENT .UNINDENT .sp This example clearly illustrates that; one, using the YAML renderer by default is a wise decision and two, 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 should be tested to ensure they work properly. To invoke these rules, simply execute \fBsalt \(aq*\(aq state.highstate\fP on the command line. If you get back only hostnames with a \fB:\fP after, but no return, chances are there is a problem with one or more of the sls files. On the minion, use the \fBsalt\-call\fP command: \fBsalt\-call state.highstate \-l debug\fP to examine the output for errors. This should help troubleshoot the issue. The minions can also be started in the foreground in debug mode: \fBsalt\-minion \-l debug\fP\&. .SS Next Reading .sp With an understanding of states, the next recommendation is to become familiar with Salt\(aqs pillar interface: .INDENT 0.0 .INDENT 3.5 \fBPillar Walkthrough\fP .UNINDENT .UNINDENT .SS States tutorial, part 1 \- Basic Usage .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. .INDENT 0.0 .INDENT 3.5 .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. .UNINDENT .UNINDENT .SS Setting up the Salt State Tree .sp States are stored in text files on the master and transferred 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, the Salt File Server must first be set up. Edit the master config file (\fBfile_roots\fP) and uncomment the following lines: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C file_roots: base: \- /srv/salt .ft P .fi .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 If you are deploying on FreeBSD via ports, the \fBfile_roots\fP path defaults to \fB/usr/local/etc/salt/states\fP\&. .UNINDENT .UNINDENT .sp Restart the Salt master in order to pick up this change: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C pkill salt\-master salt\-master \-d .ft P .fi .UNINDENT .UNINDENT .SS Preparing the Top File .sp On the master, in the directory uncommented in the previous step, (\fB/srv/salt\fP by default), create a new file called \fBtop.sls\fP and add the following: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C base: \(aq*\(aq: \- webserver .ft P .fi .UNINDENT .UNINDENT .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). .INDENT 0.0 .INDENT 3.5 .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: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C base: \(aqos:Fedora\(aq: \- match: grain \- webserver .ft P .fi .UNINDENT .UNINDENT .UNINDENT .UNINDENT .SS Create an \fBsls\fP file .sp In the same directory as the \fItop file\fP, create a file named \fBwebserver.sls\fP, containing the following: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C apache: # ID declaration pkg: # state declaration \- installed # function declaration .ft P .fi .UNINDENT .UNINDENT .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. .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 The package name for the Apache httpd web server may differ depending on OS or distro — for example, on Fedora it is \fBhttpd\fP but on Debian/Ubuntu it is \fBapache2\fP\&. .UNINDENT .UNINDENT .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. .INDENT 0.0 .INDENT 3.5 .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. The default can be changed by editing \fBrenderer\fP in the master configuration file. .UNINDENT .UNINDENT .SS Install the package .sp Next, let\(aqs run the state we created. Open a terminal on the master and run: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C % salt \(aq*\(aq state.highstate .ft P .fi .UNINDENT .UNINDENT .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. .INDENT 0.0 .INDENT 3.5 .IP "SLS File Namespace" .sp Note that in the \fIexample\fP above, the SLS file \fBwebserver.sls\fP was referred to simply as \fBwebserver\fP\&. The namespace for SLS files follows a few simple rules: .INDENT 0.0 .IP 1. 3 The \fB\&.sls\fP is discarded (i.e. \fBwebserver.sls\fP becomes \fBwebserver\fP). .IP 2. 3 .INDENT 3.0 .TP .B Subdirectories can be used for better organization. .INDENT 7.0 .IP a. 3 Each subdirectory is represented by a dot. .IP b. 3 \fBwebserver/dev.sls\fP is referred to as \fBwebserver.dev\fP\&. .UNINDENT .UNINDENT .IP 3. 3 A file called \fBinit.sls\fP in a subdirectory is referred to by the path of the directory. So, \fBwebserver/init.sls\fP is referred to as \fBwebserver\fP\&. .IP 4. 3 If both \fBwebserver.sls\fP and \fBwebserver/init.sls\fP happen to exist, \fBwebserver/init.sls\fP will be ignored and \fBwebserver.sls\fP will be the file referred to as \fBwebserver\fP\&. .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .INDENT 3.5 .IP "Troubleshooting Salt" .sp If the expected output isn\(aqt seen, the following tips can help to 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: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-minion \-l debug .ft P .fi .UNINDENT .UNINDENT .TP .B Run the minion in the foreground By not starting the minion in daemon mode (\fI\-d\fP) one can view any output from the minion as it works: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-minion & .ft P .fi .UNINDENT .UNINDENT .UNINDENT .sp Increase the default timeout value when running \fBsalt\fP\&. For example, to change the default timeout to 60 seconds: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt \-t 60 .ft P .fi .UNINDENT .UNINDENT .sp For best results, combine all three: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt\-minion \-l debug & # On the minion salt \(aq*\(aq state.highstate \-t 60 # On the master .ft P .fi .UNINDENT .UNINDENT .UNINDENT .UNINDENT .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 \- More Complex States, Requisites .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 This tutorial builds on topics covered in \fBpart 1\fP\&. It is recommended that you begin there. .UNINDENT .UNINDENT .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: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C apache: pkg: \- installed service: \- running \- require: \- pkg: apache .ft P .fi .UNINDENT .UNINDENT .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 look like this: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C |\- top.sls \(ga\- webserver/ \(ga\- init.sls .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .INDENT 3.5 .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\&. .UNINDENT .UNINDENT .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: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C apache: pkg: \- installed service: \- running \- require: \- pkg: apache /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 .UNINDENT .UNINDENT .sp \fBline 9\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 10\fP the \fIstate declaration\fP\&. This example uses the Salt \fBfile state\fP\&. .sp \fBLine 11\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 12\fP is a \fIfunction arg declaration\fP which, in this example, passes the \fBsource\fP argument to the \fBmanaged function\fP\&. .sp \fBLine 13\fP is a \fIrequisite declaration\fP\&. .sp \fBLine 14\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: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C Salt rocks

This file brought to you by Salt

.ft P .fi .UNINDENT .UNINDENT .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: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq state.highstate .ft P .fi .UNINDENT .UNINDENT .sp Verify that Apache is now serving your custom HTML. .INDENT 0.0 .INDENT 3.5 .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: .INDENT 0.0 .INDENT 3.5 .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 \- require: \- pkg: apache .ft P .fi .UNINDENT .UNINDENT .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\&. .UNINDENT .UNINDENT .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 \- Templating, Includes, Extends .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 This tutorial builds on topics covered in \fBpart 1\fP and \fBpart 2\fP\&. It is recommended that you begin there. .UNINDENT .UNINDENT .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: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C {% for usr in [\(aqmoe\(aq,\(aqlarry\(aq,\(aqcurly\(aq] %} {{ usr }}: user.present {% endfor %} .ft P .fi .UNINDENT .UNINDENT .sp This templated sls file once generated will look like this: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C moe: user.present larry: user.present curly: user.present .ft P .fi .UNINDENT .UNINDENT .sp Here\(aqs a more complex example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C {% for usr in \(aqmoe\(aq,\(aqlarry\(aq,\(aqcurly\(aq %} {{ usr }}: group: \- present user: \- present \- gid_from_name: True \- require: \- group: {{ usr }} {% endfor %} .ft P .fi .UNINDENT .UNINDENT .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: .INDENT 0.0 .INDENT 3.5 .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 .UNINDENT .UNINDENT .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 .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C moe: user: \- present \- gid: {{ salt[\(aqfile.group_to_gid\(aq](\(aqsome_group_that_exists\(aq) }} .ft P .fi .UNINDENT .UNINDENT .sp Note that for the above example to work, \fBsome_group_that_exists\fP must exist before the state file is processed by the templating engine. .sp Below is an example that uses the \fBnetwork.hw_addr\fP function to retrieve the MAC address for eth0: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt[\(aqnetwork.hw_addr\(aq](\(aqeth0\(aq) .ft P .fi .UNINDENT .UNINDENT .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, \fBrequisites\fP span multiple files by using an \fIinclude declaration\fP\&. For example: .sp \fBpython/python\-libs.sls:\fP .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C python\-dateutil: pkg.installed .ft P .fi .UNINDENT .UNINDENT .sp \fBpython/django.sls:\fP .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C include: \- python.python\-libs django: pkg.installed: \- require: \- pkg: python\-dateutil .ft P .fi .UNINDENT .UNINDENT .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 .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C apache: pkg.installed .ft P .fi .UNINDENT .UNINDENT .sp \fBapache/mywebsite.sls:\fP .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C include: \- apache.apache extend: apache: service: \- running \- 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 .UNINDENT .UNINDENT .INDENT 0.0 .INDENT 3.5 .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. .UNINDENT .UNINDENT .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 .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C include: \- apache.apache extend: apache: service: \- running \- watch: \- file: mywebsite mywebsite: file.managed: \- name: /etc/httpd/extra/httpd\-vhosts.conf \- source: salt://apache/httpd\-vhosts.conf .ft P .fi .UNINDENT .UNINDENT .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: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C stooges: user.present: \- names: \- moe \- larry \- curly .ft P .fi .UNINDENT .UNINDENT .SS Next steps .sp In \fBpart 4\fP we will discuss how to use salt\(aqs \fBfile_roots\fP to set up a workflow in which states can be "promoted" from dev, to QA, to production. .SS States tutorial, part 4 .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 This tutorial builds on topics covered in \fBpart 1\fP, \fBpart 2\fP and \fBpart 3\fP\&. It is recommended that you begin there. .UNINDENT .UNINDENT .sp This part of the tutorial will show how to use salt\(aqs \fBfile_roots\fP to set up a workflow in which states can be "promoted" from dev, to QA, to production. .SS Salt fileserver path inheritance .sp Salt\(aqs fileserver allows for more than one root directory per environment, like in the below example, which uses both a local directory and a secondary location shared to the salt master via NFS: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C # In the master config file (/etc/salt/master) file_roots: base: \- /srv/salt \- /mnt/salt\-nfs/base .ft P .fi .UNINDENT .UNINDENT .sp Salt\(aqs fileserver collapses the list of root directories into a single virtual environment containing all files from each root. If the same file exists at the same relative path in more than one root, then the top\-most match "wins". For example, if \fB/srv/salt/foo.txt\fP and \fB/mnt/salt\-nfs/base/foo.txt\fP both exist, then \fBsalt://foo.txt\fP will point to \fB/srv/salt/foo.txt\fP\&. .SS Environment configuration .sp Configure a multiple\-environment setup like so: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C file_roots: base: \- /srv/salt/prod qa: \- /srv/salt/qa \- /srv/salt/prod dev: \- /srv/salt/dev \- /srv/salt/qa \- /srv/salt/prod .ft P .fi .UNINDENT .UNINDENT .sp Given the path inheritance described above, files within \fB/srv/salt/prod\fP would be available in all environments. Files within \fB/srv/salt/qa\fP would be available in both \fBqa\fP, and \fBdev\fP\&. Finally, the files within \fB/srv/salt/dev\fP would only be available within the \fBdev\fP environment. .sp Based on the order in which the roots are defined, new files/states can be placed within \fB/srv/salt/dev\fP, and pushed out to the dev hosts for testing. .sp Those files/states can then be moved to the same relative path within \fB/srv/salt/qa\fP, and they are now available only in the \fBdev\fP and \fBqa\fP environments, allowing them to be pushed to QA hosts and tested. .sp Finally, if moved to the same relative path within \fB/srv/salt/prod\fP, the files are now available in all three environments. .SS Practical Example .sp As an example, consider a simple website, installed to \fB/var/www/foobarcom\fP\&. Below is a top.sls that can be used to deploy the website: .sp \fB/srv/salt/prod/top.sls:\fP .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C base: \(aqweb*prod*\(aq: \- webserver.foobarcom qa: \(aqweb*qa*\(aq: \- webserver.foobarcom dev: \(aqweb*dev*\(aq: \- webserver.foobarcom .ft P .fi .UNINDENT .UNINDENT .sp Using pillar, roles can be assigned to the hosts: .sp \fB/srv/pillar/top.sls:\fP .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C base: \(aqweb*prod*\(aq: \- webserver.prod \(aqweb*qa*\(aq: \- webserver.qa \(aqweb*dev*\(aq: \- webserver.dev .ft P .fi .UNINDENT .UNINDENT .sp \fB/srv/pillar/webserver/prod.sls:\fP .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C webserver_role: prod .ft P .fi .UNINDENT .UNINDENT .sp \fB/srv/pillar/webserver/qa.sls:\fP .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C webserver_role: qa .ft P .fi .UNINDENT .UNINDENT .sp \fB/srv/pillar/webserver/dev.sls:\fP .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C webserver_role: dev .ft P .fi .UNINDENT .UNINDENT .sp And finally, the SLS to deploy the website: .sp \fB/srv/salt/prod/webserver/foobarcom.sls:\fP .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C {% if pillar.get(\(aqwebserver_role\(aq, \(aq\(aq) %} /var/www/foobarcom: file.recurse: \- source: salt://webserver/src/foobarcom \- env: {{ pillar[\(aqwebserver_role\(aq] }} \- user: www \- group: www \- dir_mode: 755 \- file_mode: 644 {% endif %} .ft P .fi .UNINDENT .UNINDENT .sp Given the above SLS, the source for the website should initially be placed in \fB/srv/salt/dev/webserver/src/foobarcom\fP\&. .sp First, let\(aqs deploy to dev. Given the configuration in the top file, this can be done using \fBstate.highstate\fP: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt \-\-pillar \(aqwebserver_role:dev\(aq state.highstate .ft P .fi .UNINDENT .UNINDENT .sp However, in the event that it is not desirable to apply all states configured in the top file (which could be likely in more complex setups), it is possible to apply just the states for the \fBfoobarcom\fP website, using \fBstate.sls\fP: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt \-\-pillar \(aqwebserver_role:dev\(aq state.sls webserver.foobarcom .ft P .fi .UNINDENT .UNINDENT .sp Once the site has been tested in dev, then the files can be moved from \fB/srv/salt/dev/webserver/src/foobarcom\fP to \fB/srv/salt/qa/webserver/src/foobarcom\fP, and deployed using the following: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt \-\-pillar \(aqwebserver_role:qa\(aq state.sls webserver.foobarcom .ft P .fi .UNINDENT .UNINDENT .sp Finally, once the site has been tested in qa, then the files can be moved from \fB/srv/salt/qa/webserver/src/foobarcom\fP to \fB/srv/salt/prod/webserver/src/foobarcom\fP, and deployed using the following: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt \-\-pillar \(aqwebserver_role:prod\(aq state.sls webserver.foobarcom .ft P .fi .UNINDENT .UNINDENT .sp Thanks to Salt\(aqs fileserver inheritance, even though the files have been moved to within \fB/srv/salt/prod\fP, they are still available from the same \fBsalt://\fP URI in both the qa and dev environments. .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\&. Many pre\-configured state trees can be found on Github in the \fI\%saltstack\-formulas\fP collection of repositories. .sp If you have any questions, suggestions, or just want to chat with other people who are using Salt, we have a very \fBactive community\fP and we\(aqd love to hear from you. .sp In addition, by continuing to \fBpart 5\fP, you can learn about the powerful orchestration of which Salt is capable. .SS States Tutorial, Part 5 \- Orchestration with Salt .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 This tutorial builds on some of the topics covered in the earlier \fBStates Walkthrough\fP pages. It is recommended to start with \fBPart 1\fP if you are not familiar with how to use states. .UNINDENT .UNINDENT .sp Orchestration can be accomplished in two distinct ways: .INDENT 0.0 .IP 1. 3 The \fIOverState System\fP\&. Added in version 0.11.0, this Salt \fBRunner\fP allows for SLS files to be organized into stages, and to require that one or more stages successfully execute before another stage will run. .IP 2. 3 The \fIOrchestrate Runner\fP\&. Added in version 0.17.0, this Salt \fBRunner\fP can use the full suite of \fBrequisites\fP available in states, and can also execute states/functions using salt\-ssh. This runner was designed with the eventual goal of replacing the \fIOverState\fP\&. .UNINDENT .SS The OverState System .sp Often servers need to be set up and configured in a specific order, and systems should only be set up if systems earlier in the sequence has been set up without any issues. .sp The OverState system can be used to orchestrate deployment in a smooth and reliable way across multiple systems in small to large environments. .SS The OverState SLS .sp The OverState system is managed by an SLS file named \fBoverstate.sls\fP, located in the root of a Salt fileserver environment. .sp The overstate.sls configures an unordered list of stages, each stage defines the minions on which to execute the state, and can define what sls files to run, execute a \fBstate.highstate\fP, or execute a function. Here\(aqs a sample overstate.sls: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C mysql: match: \(aqdb*\(aq sls: \- mysql.server \- drbd webservers: match: \(aqweb*\(aq require: \- mysql all: match: \(aq*\(aq require: \- mysql \- webservers .ft P .fi .UNINDENT .UNINDENT .sp Given the above setup, the OverState will be carried out as follows: .INDENT 0.0 .IP 1. 3 The \fBmysql\fP stage will be executed first because it is required by the \fBwebservers\fP and \fBall\fP stages. It will execute \fBstate.sls\fP once for each of the two listed SLS targets (\fBmysql.server\fP and \fBdrbd\fP). These states will be executed on all minions whose minion ID starts with "db". .IP 2. 3 The \fBwebservers\fP stage will then be executed, but only if the \fBmysql\fP stage executes without any failures. The \fBwebservers\fP stage will execute a \fBstate.highstate\fP on all minions whose minion IDs start with "web". .IP 3. 3 Finally, the \fBall\fP stage will execute, running \fBstate.highstate\fP on all systems, if and only if the \fBmysql\fP and \fBwebservers\fP stages completed without any failures. .UNINDENT .sp Any failure in the above steps would cause the requires to fail, preventing the dependent stages from executing. .SS Using Functions with OverState .sp In the above example, you\(aqll notice that the stages lacking an \fBsls\fP entry run a \fBstate.highstate\fP\&. As mentioned earlier, it is also possible to execute other functions in a stage. This functionality was added in version 0.15.0. .sp Running a function is easy: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C http: function: pkg.install: \- httpd .ft P .fi .UNINDENT .UNINDENT .sp The list of function arguments are defined after the declared function. So, the above stage would run \fBpkg.install http\fP\&. Requisites only function properly if the given function supports returning a custom return code. .SS Executing an OverState .sp Since the OverState is a \fBRunner\fP, it is executed using the \fBsalt\-run\fP command. The runner function for the OverState is \fBstate.over\fP\&. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt\-run state.over .ft P .fi .UNINDENT .UNINDENT .sp The function will by default look in the root of the \fBbase\fP environment (as defined in \fBfile_roots\fP) for a file called \fBoverstate.sls\fP, and then execute the stages defined within that file. .sp Different environments and paths can be used as well, by adding them as positional arguments: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt\-run state.over dev /root/other\-overstate.sls .ft P .fi .UNINDENT .UNINDENT .sp The above would run an OverState using the \fBdev\fP fileserver environment, with the stages defined in \fB/root/other\-overstate.sls\fP\&. .sp \fBWARNING:\fP .INDENT 0.0 .INDENT 3.5 Since these are positional arguments, when defining the path to the overstate file the environment must also be specified, even if it is the \fBbase\fP environment. .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 Remember, salt\-run is always executed on the master. .UNINDENT .UNINDENT .SS The Orchestrate Runner .sp New in version 0.17.0. .sp As noted above in the introduction, the Orchestrate Runner (originally called the state.sls runner) offers all the functionality of the OverState, but with a couple advantages: .INDENT 0.0 .IP \(bu 2 All \fBrequisites\fP available in states can be used. .IP \(bu 2 The states/functions can be executed using salt\-ssh. .UNINDENT .sp The Orchestrate Runner was added with the intent to eventually deprecate the OverState system, however the OverState will still be maintained for the foreseeable future. .SS Configuration Syntax .sp The configuration differs slightly from that of the OverState, and more closely resembles the configuration schema used for states. .sp To execute a state, use \fBsalt.state\fP: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C install_nginx: salt.state: \- tgt: \(aqweb*\(aq \- sls: \- nginx .ft P .fi .UNINDENT .UNINDENT .sp To execute a function, use \fBsalt.function\fP: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C cmd.run: salt.function: \- tgt: \(aq*\(aq \- arg: \- rm \-rf /tmp/foo .ft P .fi .UNINDENT .UNINDENT .SS Triggering a Highstate .sp Wheras with the OverState, a Highstate is run by simply omitting an \fBsls\fP or \fBfunction\fP argument, with the Orchestrate Runner the Highstate must explicitly be requested by using \fBhighstate: True\fP: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C webserver_setup: salt.state: \- tgt: \(aqweb*\(aq \- highstate: True .ft P .fi .UNINDENT .UNINDENT .SS Executing the Orchestrate Runner .sp The Orchestrate Runner can be executed using the \fBstate.orchestrate\fP runner function. \fBstate.orch\fP also works, for those that would like to type less. .sp Assuming that your \fBbase\fP environment is located at \fB/srv/salt\fP, and you have placed a configuration file in \fB/srv/salt/orchestration/webserver.sls\fP, then the following could both be used: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt\-run state.orchestrate orchestration.webserver salt\-run state.orch orchestration.webserver .ft P .fi .UNINDENT .UNINDENT .sp Changed in version 2014.1.1: The runner function was renamed to \fBstate.orchestrate\fP\&. In versions 0.17.0 through 2014.1.0, \fBstate.sls\fP must be used. This was renamed to avoid confusion with the \fBstate.sls\fP execution function. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt\-run state.sls orchestration.webserver .ft P .fi .UNINDENT .UNINDENT .SS More Complex Orchestration .sp Many states/functions can be configured in a single file, which when combined with the full suite of \fBrequisites\fP, can be used to easily configure complex orchestration tasks. Additionally, the states/functions will be executed in the order in which they are defined, unless prevented from doing so by any \fBrequisites\fP, as is the default in SLS files since 0.17.0. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C cmd.run: salt.function: \- tgt: 10.0.0.0/24 \- tgt_type: ipcidr \- arg: \- bootstrap storage_setup: salt.state: \- tgt: \(aqrole:storage\(aq \- tgt_type: grain \- sls: ceph \- require: \- salt: webserver_setup webserver_setup: salt.state: \- tgt: \(aqweb*\(aq \- highstate: True .ft P .fi .UNINDENT .UNINDENT .sp Given the above setup, the orchestration will be carried out as follows: .INDENT 0.0 .IP 1. 3 The shell command \fBbootstrap\fP will be executed on all minions in the 10.0.0.0/24 subnet. .IP 2. 3 A Highstate will be run on all minions whose ID starts with "web", since the \fBstorage_setup\fP state requires it. .IP 3. 3 Finally, the \fBceph\fP SLS target will be executed on all minions which have a grain called \fBrole\fP with a value of \fBstorage\fP\&. .UNINDENT .SS Understanding State Ordering .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 This tutorial is an intermediate level tutorial. Some basic understanding of the state system and writing Salt Formulas is assumed. .UNINDENT .UNINDENT .sp Salt\(aqs state system is built to deliver all of the power of configuration management systems without sacrificing simplicity. This tutorial is made to help users understand in detail just how the order is defined for state executions in Salt. .sp This tutorial is written to represent the behavior of Salt as of version 0.17.0. .SS Compiler Basics .sp To understand ordering in depth some very basic knowledge about the state compiler is very helpful. No need to worry though, this is very high level! .SS High Data and Low Data .sp When defining Salt Formulas in YAML the data that is being represented is referred to by the compiler as High Data. When the data is initially loaded into the compiler it is a single large python dictionary, this dictionary can be viewed raw by running: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq state.show_highstate .ft P .fi .UNINDENT .UNINDENT .sp This "High Data" structure is then compiled down to "Low Data". The Low Data is what is matched up to create individual executions in Salt\(aqs configuration management system. The low data is an ordered list of single state calls to execute. Once the low data is compiled the evaluation order can be seen. .sp The low data can be viewed by running: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq state.show_lowstate .ft P .fi .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 The state execution module contains MANY functions for evaluating the state system and is well worth a read! These routines can be very useful when debugging states or to help deepen one\(aqs understanding of Salt\(aqs state system. .UNINDENT .UNINDENT .sp As an example, a state written thusly: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C apache: pkg: \- installed service: \- running \- watch: \- file: /etc/httpd/conf.d/httpd.conf \- pkg: apache /etc/httpd/conf.d/httpd.conf: file: \- managed \- source: salt://apache/httpd.conf .ft P .fi .UNINDENT .UNINDENT .sp Will have High Data which looks like this represented in json: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C { "apache": { "pkg": [ "installed", { "order": 10000 } ], "service": [ "running", { "watch": [ { "file": "/etc/httpd/conf.d/httpd.conf" }, { "pkg": "apache" } ] }, { "order": 10001 } ], "__sls__": "apache", "__env__": "base" }, "/etc/httpd/conf.d/httpd.conf": { "file": [ "managed", { "source": "salt://apache/httpd.conf" }, { "order": 10002 } ], "__sls__": "apache", "__env__": "base" } } .ft P .fi .UNINDENT .UNINDENT .sp The subsequent Low Data will look like this: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C [ { "name": "apache", "state": "pkg", "__id__": "apache", "fun": "installed", "__env__": "base", "__sls__": "apache", "order": 10000 }, { "name": "apache", "watch": [ { "file": "/etc/httpd/conf.d/httpd.conf" }, { "pkg": "apache" } ], "state": "service", "__id__": "apache", "fun": "running", "__env__": "base", "__sls__": "apache", "order": 10001 }, { "name": "/etc/httpd/conf.d/httpd.conf", "source": "salt://apache/httpd.conf", "state": "file", "__id__": "/etc/httpd/conf.d/httpd.conf", "fun": "managed", "__env__": "base", "__sls__": "apache", "order": 10002 } ] .ft P .fi .UNINDENT .UNINDENT .sp This tutorial discusses the Low Data evaluation and the state runtime. .SS Ordering Layers .sp Salt defines 2 order interfaces which are evaluated in the state runtime and defines these orders in a number of passes. .SS Definition Order .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 The Definition Order system can be disabled by turning the option \fIstate_auto_order\fP to \fIFalse\fP in the master configuration file. .UNINDENT .UNINDENT .sp The top level of ordering is the \fIDefinition Order\fP\&. The \fIDefinition Order\fP is the order in which states are defined in salt formulas. This is very straightforward on basic states which do not contain \fBinclude\fP statements or a \fBtop\fP file, as the states are just ordered from the top of the file, but the include system starts to bring in some simple rules for how the \fIDefinitiion Order\fP is defined. .sp Looking back at the "Low Data" and "High Data" shown above, the order key has been transparently added to the data to enable the \fIDefinition Order\fP\&. .SS The Include Statement .sp Basically, if there is an include statement in a formula, then the formulas which are included will be run BEFORE the contents of the formula which is including them. Also, the include statement is a list, so they will be loaded in the order in which they are included. .sp In the following case: .sp \fBfoo.sls\fP .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C include: \- bar \- baz .ft P .fi .UNINDENT .UNINDENT .sp \fBbar.sls\fP .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C include: \- quo .ft P .fi .UNINDENT .UNINDENT .sp \fBbaz.sls\fP .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C include: \- qux .ft P .fi .UNINDENT .UNINDENT .sp In the above case if \fIstate.sls foo\fP were called then the formulas will be loaded in the following order: .INDENT 0.0 .IP 1. 3 quo .IP 2. 3 bar .IP 3. 3 qux .IP 4. 3 baz .IP 5. 3 foo .UNINDENT .SS The \fIorder\fP Flag .sp The \fIDefinition Order\fP happens transparently in the background, but the ordering can be explicitly overridden using the \fIorder\fP flag in states: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C apache: pkg: \- installed \- order: 1 .ft P .fi .UNINDENT .UNINDENT .sp This order flag will over ride the definition order, this makes it very simple to create states that are always executed first, last or in specific stages, a great example is defining a number of package repositories that need to be set up before anything else, or final checks that need to be run at the end of a state run by using \fIorder: last\fP or \fIorder: \-1\fP\&. .sp When the order flag is explicitly set the \fIDefinition Order\fP system will omit setting an order for that state and directly use the order flag defined. .SS Lexicographical Fall\-back .sp Salt states were written to ALWAYS execute in the same order. Before the introduction of \fIDefinition Order\fP in version 0.17.0 everything was ordered lexicographically according to the name of the state, then function then id. .sp This is the way Salt has always ensured that states always run in the same order regardless of where they are deployed, the addition of the \fIDefinition Order\fP method mealy makes this finite ordering easier to follow. .sp The lexicographical ordering is still applied but it only has any effect when two order statements collide. This means that if multiple states are assigned the same order number that they will fall back to lexicographical ordering to ensure that every execution still happens in a finite order. .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 If running with \fIstate_auto_order: False\fP the \fIorder\fP key is not set automatically, since the Lexicographical order can be derived from other keys. .UNINDENT .UNINDENT .SS Requisite Ordering .sp Salt states are fully declarative, in that they are written to declare the state in which a system should be. This means that components can require that other components have been set up successfully. Unlike the other ordering systems, the \fIRequisite\fP system in Salt is evaluated at runtime. .sp The requisite system is also built to ensure that the ordering of execution never changes, but is always the same for a given set of states. This is accomplished by using a runtime that processes states in a completely predictable order instead of using an event loop based system like other declarative configuration management systems. .SS Runtime Requisite Evaluation .sp The requisite system is evaluated as the components are found, and the requisites are always evaluated in the same order. This explanation will be followed by an example, as the raw explanation may be a little dizzying at first as it creates a linear dependency evaluation sequence. .sp The "Low Data" is an ordered list or dictionaries, the state runtime evaluates each dictionary in the order in which they are arranged in the list. When evaluating a single dictionary it is checked for requisites, requisites are evaluated in order, \fIrequire\fP then \fIwatch\fP then \fIprereq\fP\&. .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 If using requisite in statements like require_in and watch_in these will be compiled down to require and watch statements before runtime evaluation. .UNINDENT .UNINDENT .sp Each requisite contains an ordered list of requisites, these requisites are looked up in the list of dictionaries and then executed. Once all requisites have been evaluated and executed then the requiring state can safely be run (or not run if requisites have not been met). .sp This means that the requisites are always evaluated in the same order, again ensuring one of the core design principals of Salt\(aqs State system to ensure that execution is always finite is intact. .SS Simple Runtime Evaluation Example .sp Given the above "Low Data" the states will be evaluated in the following order: .INDENT 0.0 .IP 1. 3 The pkg.installed is executed ensuring that the apache package is installed, it contains no requisites and is therefore the first defined state to execute. .IP 2. 3 The service.running state is evaluated but NOT executed, a watch requisite is found, therefore they are read in order, the runtime first checks for the file, sees that it has not been executed and calls for the file state to be evaluated. .IP 3. 3 The file state is evaluated AND executed, since it, like the pkg state does not contain any requisites. .IP 4. 3 The evaluation of the service state continues, it next checks the pkg requisite and sees that it is met, with all requisites met the service state is now executed. .UNINDENT .SS Best Practice .sp The best practice in Salt is to choose a method and stick with it, official states are written using requisites for all associations since requisites create clean, traceable dependency trails and make for the most portable formulas. To accomplish something similar to how classical imperative systems function all requisites can be omitted and the \fBfailhard\fP option then set to \fITrue\fP in the master configuration, this will stop all state runs at the first instance of a failure. .sp In the end, using requisites creates very tight and fine grained states, not using requisites makes full sequence runs and while slightly easier to write, and gives much less control over the executions. .SS Advanced Topics .SS SaltStack Walkthrough .SS Welcome! .sp Welcome to SaltStack! I am excited that you are interested in Salt and starting down the path to better infrastructure management. I developed (and am continuing to develop) Salt with the goal of making the best software available to manage computers of almost any kind. I hope you enjoy working with Salt and that the software can solve your real world needs! .INDENT 0.0 .IP \(bu 2 Thomas S Hatch .IP \(bu 2 Salt creator and chief developer .IP \(bu 2 CTO of SaltStack, Inc. .UNINDENT .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 This is the first of a series of walkthroughs and serves as the best entry point for people new to Salt, after this be sure to read up on pillar and more on states: .sp \fBStarting States\fP .sp \fBPillar Walkthrough\fP .UNINDENT .UNINDENT .SS Getting Started .SS What is Salt? .sp Salt is a different approach to infrastructure management, it is founded on the idea that high speed communication with large numbers of systems can open up new capabilities. This approach makes Salt a powerful multitasking system that can solve many specific problems in an infrastructure. The backbone of Salt is the remote execution engine, which creates a high speed, secure and bi\-directional communication net for groups of systems. On top of this communication system Salt provides an extremely fast, flexible and easy to use configuration management system called \fBSalt States\fP\&. .sp This unique approach to management makes for a transparent control system that is not only amazingly easy to set up and use, but also capable of solving very complex problems in infrastructures; as will be explored in this walk through. .sp Salt is being used today by some of the largest infrastructures in the world and has a proven ability to scale to astounding proportions without modification. With the proven ability to scale out well beyond many tens of thousands of servers, Salt has also proven to be an excellent choice for small deployments as well, lowering compute and management overhead for infrastructures as small as just a few systems. .SS Installing Salt .sp SaltStack has been made to be very easy to install and get started. Setting up Salt should be as easy as installing Salt via distribution packages on Linux or via the Windows installer. The \fBinstallation documents\fP cover specific platform installation in depth. .SS Starting Salt .sp Salt functions on a master/minion topology. A master server acts as a central control bus for the clients (called minions), and the minions connect back to the master. .SS Setting Up the Salt Master .sp Turning on the Salt Master is easy, just turn it on! The default configuration is suitable for the vast majority of installations. The Salt master can be controlled by the local Linux/Unix service manager: .sp On Systemd based platforms (OpenSuse, Fedora): .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C systemctl start salt\-master .ft P .fi .UNINDENT .UNINDENT .sp On Upstart based systems (Ubuntu, older Fedora/RHEL): .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C service salt\-master start .ft P .fi .UNINDENT .UNINDENT .sp On SysV Init systems (Debian, Gentoo etc.): .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C /etc/init.d/salt\-master start .ft P .fi .UNINDENT .UNINDENT .sp Or the master can be started directly on the command line: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt\-master \-d .ft P .fi .UNINDENT .UNINDENT .sp The Salt Master can also be started in the foreground in debug mode, thus greatly increasing the command output: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt\-master \-l debug .ft P .fi .UNINDENT .UNINDENT .sp The Salt Master needs to bind to 2 TCP network ports on the system, these ports are 4505 and 4506. For more in depth information on firewalling these ports, the firewall tutorial is available \fBhere\fP\&. .SS Setting up a Salt Minion .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 The Salt Minion can operate with or without a Salt Master. This walkthrough assumes that the minion will be connected to the master, for information on how to run a master\-less minion please see the masterless quickstart guide: .sp \fBMasterless Minion Quickstart\fP .UNINDENT .UNINDENT .sp The Salt Minion only needs to be aware of one piece of information to run, the network location of the master. By default the minion will look for the DNS name \fBsalt\fP for the master, making the easiest approach to set internal DNS to resolve the name \fBsalt\fP back to the Salt Master IP. Otherwise the minion configuration file will need to be edited, edit the configuration option \fBmaster\fP to point to the DNS name or the IP of the Salt Master: .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 The default location of the configuration files is \fB/etc/salt\fP\&. Most platforms adhere to this convention, but platforms such as FreeBSD and Microsoft Windows place this file in different locations. .UNINDENT .UNINDENT .sp \fB/etc/salt/minion:\fP .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C master: saltmaster.example.com .ft P .fi .UNINDENT .UNINDENT .sp Now that the master can be found, start the minion in the same way as the master; with the platform init system, or via the command line directly: .sp As a daemon: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt\-minion \-d .ft P .fi .UNINDENT .UNINDENT .sp In the foreground in debug mode: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt\-minion \-l debug .ft P .fi .UNINDENT .UNINDENT .sp Now that the minion is started it will generate cryptographic keys and attempt to connect to the master. The next step is to venture back to the master server and accept the new minion\(aqs public key. .sp When the minion is started, it will generate an \fBid\fP value, unless it has been generated on a previous run and cached in the configuration directory (\fB/etc/salt\fP by default). This is the name by which the minion will attempt to authenticate to the master. The following steps are attempted, in order to try to find a value that is not \fBlocalhost\fP: .INDENT 0.0 .IP 1. 3 The Python function \fBsocket.getfqdn()\fP is run .IP 2. 3 \fB/etc/hostname\fP is checked (non\-Windows only) .IP 3. 3 \fB/etc/hosts\fP (\fB%WINDIR%\esystem32\edrivers\eetc\ehosts\fP on Windows hosts) is checked for hostnames that map to anything within \fB127.0.0.0/8\fP\&. .UNINDENT .sp If none of the above are able to produce an id which is not \fBlocalhost\fP, then a sorted list of IP addresses on the minion (excluding any within \fB127.0.0.0/8\fP) is inspected. The first publicly\-routable IP address is used, if there is one. Otherwise, the first privately\-routable IP address is used. .sp If all else fails, then \fBlocalhost\fP is used as a fallback. .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 Overriding the \fBid\fP .sp The minion id can be manually specified using the \fBid\fP parameter in the minion config file. If this configuration value is specified, it will override all other sources for the \fBid\fP\&. .UNINDENT .UNINDENT .SS Using salt\-key .sp Salt authenticates minions using public key encryption and authentication. For a minion to start accepting commands from the master the minion keys need to be accepted. The \fBsalt\-key\fP command is used to manage all of the keys on the master. To list the keys that are on the master run a salt\-key list command: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt\-key \-L .ft P .fi .UNINDENT .UNINDENT .sp The keys that have been rejected, accepted and pending acceptance are listed. The easiest way to accept the minion key is to accept all pending keys: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt\-key \-A .ft P .fi .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 Keys should be verified! The secure thing to do before accepting a key is to run \fBsalt\-key \-p minion\-id\fP to print the public key for the minion. This can then be compared against the minion\(aqs public key file, which is located (on the minion, of course) at \fB/etc/salt/pki/minion/minion.pub\fP\&. .sp On the master: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C # salt\-key \-p foo.domain.com Accepted Keys: foo.domain.com: \-\-\-\-\-BEGIN PUBLIC KEY\-\-\-\-\- MIICIjANBgkqhkiG9w0BAQEFAAOCAg8AMIICCgKCAgEA0JcA0IEp/yqghK5V2VLM jbG7FWV6qtw/ubTDBnpDGQgrvSNOtd0QcJsAzAtDcHwrudQgyxTZGVJqPY7gLc7P 5b4EFWt5E1w3+KZ+XXy4YtW5oOzVN5BvsJ85g7c0TUnmjL7p3MUUXE4049Ue/zgX jtbFJ0aa1HB8bnlQdWWOeflYRNEQL8482ZCmXXATFP1l5uJA9Pr6/ltdWtQTsXUA bEseUGEpmq83vAkwtZIyJRG2cJh8ZRlJ6whSMg6wr7lFvStHQQzKHt9pRPml3lLK ba2X07myAEJq/lpJNXJm5bkKV0+o8hqYQZ1ndh9HblHb2EoDBNbuIlhYft1uv8Tp 8beaEbq8ZST082sS/NjeL7W1T9JS6w2rw4GlUFuQlbqW8FSl1VDo+Alxu0VAr4GZ gZpl2DgVoL59YDEVrlB464goly2c+eY4XkNT+JdwQ9LwMr83/yAAG6EGNpjT3pZg Wey7WRnNTIF7H7ISwEzvik1GrhyBkn6K1RX3uAf760ZsQdhxwHmop+krgVcC0S93 xFjbBFF3+53mNv7BNPPgl0iwgA9/WuPE3aoE0A8Cm+Q6asZjf8P/h7KS67rIBEKV zrQtgf3aZBbW38CT4fTzyWAP138yrU7VSGhPMm5KfTLywNsmXeaR5DnZl6GGNdL1 fZDM+J9FIGb/50Ee77saAlUCAwEAAQ== \-\-\-\-\-END PUBLIC KEY\-\-\-\-\- .ft P .fi .UNINDENT .UNINDENT .sp On the minion: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C # cat /etc/salt/pki/minion/minion.pub \-\-\-\-\-BEGIN PUBLIC KEY\-\-\-\-\- MIICIjANBgkqhkiG9w0BAQEFAAOCAg8AMIICCgKCAgEA0JcA0IEp/yqghK5V2VLM jbG7FWV6qtw/ubTDBnpDGQgrvSNOtd0QcJsAzAtDcHwrudQgyxTZGVJqPY7gLc7P 5b4EFWt5E1w3+KZ+XXy4YtW5oOzVN5BvsJ85g7c0TUnmjL7p3MUUXE4049Ue/zgX jtbFJ0aa1HB8bnlQdWWOeflYRNEQL8482ZCmXXATFP1l5uJA9Pr6/ltdWtQTsXUA bEseUGEpmq83vAkwtZIyJRG2cJh8ZRlJ6whSMg6wr7lFvStHQQzKHt9pRPml3lLK ba2X07myAEJq/lpJNXJm5bkKV0+o8hqYQZ1ndh9HblHb2EoDBNbuIlhYft1uv8Tp 8beaEbq8ZST082sS/NjeL7W1T9JS6w2rw4GlUFuQlbqW8FSl1VDo+Alxu0VAr4GZ gZpl2DgVoL59YDEVrlB464goly2c+eY4XkNT+JdwQ9LwMr83/yAAG6EGNpjT3pZg Wey7WRnNTIF7H7ISwEzvik1GrhyBkn6K1RX3uAf760ZsQdhxwHmop+krgVcC0S93 xFjbBFF3+53mNv7BNPPgl0iwgA9/WuPE3aoE0A8Cm+Q6asZjf8P/h7KS67rIBEKV zrQtgf3aZBbW38CT4fTzyWAP138yrU7VSGhPMm5KfTLywNsmXeaR5DnZl6GGNdL1 fZDM+J9FIGb/50Ee77saAlUCAwEAAQ== \-\-\-\-\-END PUBLIC KEY\-\-\-\-\- .ft P .fi .UNINDENT .UNINDENT .UNINDENT .UNINDENT .SS Sending the First Commands .sp Now that the minion is connected to the master and authenticated, the master can start to command the minion. Salt commands allow for a vast set of functions to be executed and for specific minions and groups of minions to be targeted for execution. This makes the \fBsalt\fP command very powerful, but the command is also very usable, and easy to understand. .sp The \fBsalt\fP command is comprised of command options, target specification, the function to execute, and arguments to the function. A simple command to start with looks like this: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq test.ping .ft P .fi .UNINDENT .UNINDENT .sp The \fB*\fP is the target, which specifies all minions, and \fBtest.ping\fP tells the minion to run the \fBtest.ping\fP function. The result of running this command will be the master instructing all of the minions to execute \fBtest.ping\fP in parallel and return the result. This is not an actual ICMP ping, but rather a simple function which returns \fBTrue\fP\&. Using \fBtest.ping\fP is a good way of confirming that a minion is connected. .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 Each minion registers itself with a unique minion id. This id defaults to the minion\(aqs hostname, but can be explicitly defined in the minion config as well by using the \fBid\fP parameter. .UNINDENT .UNINDENT .SS Getting to Know the Functions .sp Salt comes with a vast library of functions available for execution, and Salt functions are self documenting. To see what functions are available on the minions execute the \fBsys.doc\fP function: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq sys.doc .ft P .fi .UNINDENT .UNINDENT .sp This will display a very large list of available functions and documentation on them, this documentation is also available \fBhere\fP\&. .sp These functions cover everything from shelling out to package management to manipulating database servers. They comprise a powerful system management API which is the backbone to Salt configuration management and many other aspects of Salt. .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 Salt comes with many plugin systems. The functions that are available via the \fBsalt\fP command are called \fBExecution Modules\fP\&. .UNINDENT .UNINDENT .SS Helpful Functions to Know .sp The \fBcmd\fP module contains functions to shell out on minions, such as \fBcmd.run\fP and \fBcmd.run_all\fP: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq cmd.run \(aqls \-l /etc\(aq .ft P .fi .UNINDENT .UNINDENT .sp The \fBpkg\fP functions automatically map local system package managers to the same salt functions. This means that \fBpkg.install\fP will install packages via yum on Red Hat based systems, apt on Debian systems, etc.: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.install vim .ft P .fi .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 Some custom Linux spins and derivatives of other distros are not properly detected by Salt. If the above command returns an error message saying that \fBpkg.install\fP is not available, then you may need to override the pkg provider. This process is explained \fBhere\fP\&. .UNINDENT .UNINDENT .sp The \fBnetwork.interfaces\fP function will list all interfaces on a minion, along with their IP addresses, netmasks, MAC addresses, etc: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq network.interfaces .ft P .fi .UNINDENT .UNINDENT .SS \fBsalt\-call\fP .sp The examples so far have described running commands from the Master using the \fBsalt\fP command, but when troubleshooting it can be more beneficial to login to the minion directly and use \fBsalt\-call\fP\&. Doing so allows you to see the minion log messages specific to the command you are running (which are \fInot\fP part of the return data you see when running the command from the Master using \fBsalt\fP), making it unnecessary to tail the minion log. More information on \fBsalt\-call\fP and how to use it can be found \fIhere\fP\&. .SS Grains .sp Salt uses a system called \fBGrains\fP to build up static data about minions. This data includes information about the operating system that is running, CPU architecture and much more. The grains system is used throughout Salt to deliver platform data to many components and to users. .sp Grains can also be statically set, this makes it easy to assign values to minions for grouping and managing. A common practice is to assign grains to minions to specify what the role or roles a minion might be. These static grains can be set in the minion configuration file or via the \fBgrains.setval\fP function. .SS Targeting .sp Salt allows for minions to be targeted based on a wide range of criteria. The default targeting system uses globular expressions to match minions, hence if there are minions named \fBlarry1\fP, \fBlarry2\fP, \fBcurly1\fP and \fBcurly2\fP, a glob of \fBlarry*\fP will match \fBlarry1\fP and \fBlarry2\fP, and a glob of \fB*1\fP will match \fBlarry1\fP and \fBcurly1\fP\&. .sp Many other targeting systems can be used other than globs, these systems include: .INDENT 0.0 .TP .B Regular Expressions Target using PCRE compliant regular expressions .TP .B Grains Target based on grains data: \fBTargeting with Grains\fP .TP .B Pillar Target based on pillar data: \fBTargeting with Pillar\fP .TP .B IP Target based on IP addr/subnet/range .TP .B Compound Create logic to target based on multiple targets: \fBTargeting with Compound\fP .TP .B Nodegroup Target with nodegroups: \fBTargeting with Nodegroup\fP .UNINDENT .sp The concepts of targets are used on the command line with salt, but also function in many other areas as well, including the state system and the systems used for ACLs and user permissions. .SS Passing in Arguments .sp Many of the functions available accept arguments, these arguments can be passed in on the command line: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.install vim .ft P .fi .UNINDENT .UNINDENT .sp This example passes the argument \fBvim\fP to the pkg.install function, since many functions can accept more complex input then just a string the arguments are parsed through YAML, allowing for more complex data to be sent on the command line: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq test.echo \(aqfoo: bar\(aq .ft P .fi .UNINDENT .UNINDENT .sp In this case Salt translates the string \(aqfoo: bar\(aq into the dictionary "{\(aqfoo\(aq: \(aqbar\(aq}" .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 Any line that contains a newline will not be parsed by yaml. .UNINDENT .UNINDENT .SS Salt States .sp Now that the basics are covered the time has come to evaluate \fBStates\fP\&. Salt \fBStates\fP, or the \fBState System\fP is the component of Salt made for configuration management. The State system is a fully functional configuration management system which has been designed to be exceptionally powerful while still being simple to use, fast, lightweight, deterministic and with salty levels of flexibility. .sp The state system is already available with a basic salt setup, no additional configuration is required, states can be set up immediately. .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 Before diving into the state system, a brief overview of how states are constructed will make many of the concepts clearer. Salt states are based on data modeling, and build on a low level data structure that is used to execute each state function. Then more logical layers are built on top of each other. The high layers of the state system which this tutorial will cover consists of everything that needs to be known to use states, the two high layers covered here are the \fIsls\fP layer and the highest layer \fIhighstate\fP\&. .sp Again, knowing that there are many layers of data management, will help with understanding states, but they never need to be used. Just as understanding how a compiler functions when learning a programming language, understanding what is going on under the hood of a configuration management system will also prove to be a valuable asset. .UNINDENT .UNINDENT .SS The First SLS Formula .sp The state system is built on sls formulas, these formulas are built out in files on Salt\(aqs file server. To make a very basic sls formula open up a file under /srv/salt named vim.sls and get vim installed: .sp \fB/srv/salt/vim.sls:\fP .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C vim: pkg.installed .ft P .fi .UNINDENT .UNINDENT .sp Now install vim on the minions by calling the sls directly: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq state.sls vim .ft P .fi .UNINDENT .UNINDENT .sp This command will invoke the state system and run the named sls which was just created, \fBvim\fP\&. .sp Now, to beef up the vim sls formula, a vimrc can be added: .sp \fB/srv/salt/vim.sls:\fP .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C vim: pkg.installed /etc/vimrc: file.managed: \- source: salt://vimrc \- mode: 644 \- user: root \- group: root .ft P .fi .UNINDENT .UNINDENT .sp Now the desired vimrc needs to be copied into the Salt file server to /srv/salt/vimrc, in Salt everything is a file, so no path redirection needs to be accounted for. The vimrc file is placed right next to the vim.sls file. The same command as above can be executed to all the vim sls formulas and now include managing the file. .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 Salt does not need to be restarted/reloaded or have the master manipulated in any way when changing sls formulas, they are instantly available. .UNINDENT .UNINDENT .SS Adding Some Depth .sp Obviously maintaining sls formulas right in the root of the file server will not scale out to reasonably sized deployments. This is why more depth is required. Start by making an nginx formula a better way, make an nginx subdirectory and add an init.sls file: .sp \fB/srv/salt/nginx/init.sls:\fP .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C nginx: pkg: \- installed service: \- running \- require: \- pkg: nginx .ft P .fi .UNINDENT .UNINDENT .sp A few things are introduced in this sls formula, first is the service statement which ensures that the nginx service is running, but the nginx service can\(aqt be started unless the package is installed, hence the \fBrequire\fP\&. The \fBrequire\fP statement makes sure that the required component is executed before and that it results in success. .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 The \fIrequire\fP option belongs to a family of options called \fIrequisites\fP\&. Requisites are a powerful component of Salt States, for more information on how requisites work and what is available see: \fBRequisites\fP Also evaluation ordering is available in Salt as well: \fBOrdering States\fP .UNINDENT .UNINDENT .sp Now this new sls formula has a special name, \fBinit.sls\fP, when an sls formula is named \fBinit.sls\fP it inherits the name of the directory path that contains it, so this formula can be referenced via the following command: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq state.sls nginx .ft P .fi .UNINDENT .UNINDENT .sp Now that subdirectories can be used the vim.sls formula can be cleaned up, but to make things more flexible (and to illustrate another point of course), move the vim.sls and vimrc into a new subdirectory called \fBedit\fP and change the vim.sls file to reflect the change: .sp \fB/srv/salt/edit/vim.sls:\fP .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C vim: pkg.installed /etc/vimrc: file.managed: \- source: salt://edit/vimrc \- mode: 644 \- user: root \- group: root .ft P .fi .UNINDENT .UNINDENT .sp The only change in the file is fixing the source path for the vimrc file. Now the formula is referenced as \fBedit.vim\fP because it resides in the edit subdirectory. Now the edit subdirectory can contain formulas for emacs, nano, joe or any other editor that may need to be deployed. .SS Next Reading .sp Two walkthroughs are specifically recommended at this point. First, a deeper run through States, followed by an explanation of Pillar. .INDENT 0.0 .IP 1. 3 \fBStarting States\fP .IP 2. 3 \fBPillar Walkthrough\fP .UNINDENT .sp An understanding of Pillar is extremely helpful in using States. .SS Getting Deeper Into States .sp Two more in\-depth States tutorials exist, which delve much more deeply into States functionality. .INDENT 0.0 .IP 1. 3 Thomas\(aq original states tutorial, \fBHow Do I Use Salt States?\fP, covers much more to get off the ground with States. .IP 2. 3 The \fBStates Tutorial\fP also provides a fantastic introduction. .UNINDENT .sp These tutorials include much more in depth information including templating sls formulas etc. .SS So Much More! .sp This concludes the initial Salt walkthrough, but there are many more things to learn still! These documents will cover important core aspects of Salt: .INDENT 0.0 .IP \(bu 2 \fBPillar\fP .IP \(bu 2 \fBJob Management\fP .UNINDENT .sp A few more tutorials are also available: .INDENT 0.0 .IP \(bu 2 \fBRemote Execution Tutorial\fP .IP \(bu 2 \fBStandalone Minion\fP .UNINDENT .sp This still is only scratching the surface, many components such as the reactor and event systems, extending Salt, modular components and more are not covered here. For an overview of all Salt features and documentation, look at the \fBTable of Contents\fP\&. .SS MinionFS Backend Walkthrough .sp New in version 2014.1.0: (Hydrogen) .sp Sometimes, you might need to propagate files that are generated on a minion. Salt already has a feature to send files from a minion to the master: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt \(aqminion\-id\(aq cp.push /path/to/the/file .ft P .fi .UNINDENT .UNINDENT .sp This command will store the file, including its full path, under \fBcachedir\fP \fB/master/minions/minion\-id/files\fP\&. With the default \fBcachedir\fP the example file above would be stored as \fI/var/cache/salt/master/minions/minion\-id/files/path/to/the/file\fP\&. .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 This walkthrough assumes basic knowledge of Salt and \fBcp.push\fP\&. To get up to speed, check out the \fBwalkthrough\fP\&. .UNINDENT .UNINDENT .sp Since it is not a good idea to expose the whole \fBcachedir\fP, MinionFS should be used to send these files to other minions. .SS Simple Configuration .sp To use the minionfs backend only two configuration changes are required on the master. The \fBfileserver_backend\fP option needs to contain a value of \fBminion\fP and \fBfile_recv\fP needs to be set to true: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C fileserver_backend: \- roots \- minion file_recv: True .ft P .fi .UNINDENT .UNINDENT .sp These changes require a restart of the master, then new requests for the \fBsalt://minion\-id/\fP protocol will send files that are pushed by \fBcp.push\fP from \fBminion\-id\fP to the master. .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 All of the files that are pushed to the master are going to be available to all of the minions. If this is not what you want, please remove \fBminion\fP from \fBfileserver_backend\fP in the master config file. .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 Having directories with the same name as your minions in the root that can be accessed like \fBsalt://minion\-id/\fP might cause confusion. .UNINDENT .UNINDENT .SS Commandline Example .sp Lets assume that we are going to generate SSH keys on a minion called \fBminion\-source\fP and put the public part in \fB~/.ssh/authorized_keys\fP of root user of a minion called \fBminion\-destination\fP\&. .sp First, lets make sure that \fB/root/.ssh\fP exists and has the right permissions: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C [root@salt\-master file]# salt \(aq*\(aq file.mkdir dir_path=/root/.ssh user=root group=root mode=700 minion\-source: None minion\-destination: None .ft P .fi .UNINDENT .UNINDENT .sp We create an RSA key pair without a passphrase [*]: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C [root@salt\-master file]# salt \(aqminion\-source\(aq cmd.run \(aqssh\-keygen \-N "" \-f /root/.ssh/id_rsa\(aq minion\-source: Generating public/private rsa key pair. Your identification has been saved in /root/.ssh/id_rsa. Your public key has been saved in /root/.ssh/id_rsa.pub. The key fingerprint is: 9b:cd:1c:b9:c2:93:8e:ad:a3:52:a0:8b:0a:cc:d4:9b root@minion\-source The key\(aqs randomart image is: +\-\-[ RSA 2048]\-\-\-\-+ | | | | | | | o . | | o o S o | |= + . B o | |o+ E B = | |+ . .+ o | |o ...ooo | +\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-+ .ft P .fi .UNINDENT .UNINDENT .sp and we send the public part to the master to be available to all minions: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C [root@salt\-master file]# salt \(aqminion\-source\(aq cp.push /root/.ssh/id_rsa.pub minion\-source: True .ft P .fi .UNINDENT .UNINDENT .sp now it can be seen by everyone: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C [root@salt\-master file]# salt \(aqminion\-destination\(aq cp.list_master_dirs minion\-destination: \- . \- etc \- minion\-source/root \- minion\-source/root/.ssh .ft P .fi .UNINDENT .UNINDENT .sp Lets copy that as the only authorized key to \fBminion\-destination\fP: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C [root@salt\-master file]# salt \(aqminion\-destination\(aq cp.get_file salt://minion\-source/root/.ssh/id_rsa.pub /root/.ssh/authorized_keys minion\-destination: /root/.ssh/authorized_keys .ft P .fi .UNINDENT .UNINDENT .sp Or we can use a more elegant and salty way to add an SSH key: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C [root@salt\-master file]# salt \(aqminion\-destination\(aq ssh.set_auth_key_from_file user=root source=salt://minion\-source/root/.ssh/id_rsa.pub minion\-destination: new .ft P .fi .UNINDENT .UNINDENT .IP [*] 5 Yes, that was the actual key on my server, but the server is already destroyed. .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 Multi Master Tutorial .sp As of Salt 0.16.0, the ability to connect minions to multiple masters has been made available. The multi\-master system allows for redundancy of Salt masters and facilitates multiple points of communication out to minions. When using a multi\-master setup, all masters are running hot, and any active master can be used to send commands out to the minions. .sp In 0.16.0, the masters do not share any information, keys need to be accepted on both masters, and shared files need to be shared manually or use tools like the git fileserver backend to ensure that the \fBfile_roots\fP are kept consistent. .SS Summary of Steps .INDENT 0.0 .IP 1. 3 Create a redundant master server .IP 2. 3 Copy primary master key to redundant master .IP 3. 3 Start redundant master .IP 4. 3 Configure minions to connect to redundant master .IP 5. 3 Restart minions .IP 6. 3 Accept keys on redundant master .UNINDENT .SS Prepping a Redundant Master .sp The first task is to prepare the redundant master. There is only one requirement when preparing a redundant master, which is that masters share the same private key. When the first master was created, the master\(aqs identifying key was generated and placed in the master\(aqs \fBpki_dir\fP\&. The default location of the key is \fB/etc/salt/pki/master/master.pem\fP\&. Take this key and copy it to the same location on the redundant master. Assuming that no minions have yet been connected to the new redundant master, it is safe to delete any existing key in this location and replace it. .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 There is no logical limit to the number of redundant masters that can be used. .UNINDENT .UNINDENT .sp Once the new key is in place, the redundant master can be safely started. .SS Configure Minions .sp Since minions need to be master\-aware, the new master needs to be added to the minion configurations. Simply update the minion configurations to list all connected masters: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C master: \- saltmaster1.example.com \- saltmaster2.example.com .ft P .fi .UNINDENT .UNINDENT .sp Now the minion can be safely restarted. .sp Now the minions will check into the original master and also check into the new redundant master. Both masters are first\-class and have rights to the minions. .SS Sharing Files Between Masters .sp Salt does not automatically share files between multiple masters. A number of files should be shared or sharing of these files should be strongly considered. .SS Minion Keys .sp Minion keys can be accepted the normal way using \fBsalt\-key\fP on both masters. Keys accepted, deleted, or rejected on one master will NOT be automatically managed on redundant masters; this needs to be taken care of by running salt\-key on both masters or sharing the \fB/etc/salt/pki/master/{minions,minions_pre,minions_rejected}\fP directories between masters. .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 While sharing the \fB/etc/salt/pki/master\fP directory will work, it is strongly discouraged, since allowing access to the \fBmaster.pem\fP key outside of Salt creates a \fISERIOUS\fP security risk. .UNINDENT .UNINDENT .SS File_Roots .sp The \fBfile_roots\fP contents should be kept consistent between masters. Otherwise state runs will not always be consistent on minions since instructions managed by one master will not agree with other masters. .sp The recommended way to sync these is to use a fileserver backend like gitfs or to keep these files on shared storage. .SS Pillar_Roots .sp Pillar roots should be given the same considerations as \fBfile_roots\fP\&. .SS Master Configurations .sp While reasons may exist to maintain separate master configurations, it is wise to remember that each master maintains independent control over minions. Therefore, access controls should be in sync between masters unless a valid reason otherwise exists to keep them inconsistent. .sp These access control options include but are not limited to: .INDENT 0.0 .IP \(bu 2 external_auth .IP \(bu 2 client_acl .IP \(bu 2 peer .IP \(bu 2 peer_run .UNINDENT .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: .UNINDENT .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C root@saltmaster# salt\-key \-\-gen\-keys=[key_name] .ft P .fi .UNINDENT .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: .UNINDENT .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C root@saltmaster# cp key_name.pub /etc/salt/pki/master/minions/[minion_id] .ft P .fi .UNINDENT .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. The difficulty is finding a distribution method which is secure. .INDENT 0.0 .INDENT 3.5 .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 if they gain access to a preseeded minion key. .UNINDENT .UNINDENT .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: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C /etc/salt/pki/minion/minion.pem /etc/salt/pki/minion/minion.pub .ft P .fi .UNINDENT .UNINDENT .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 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: .INDENT 0.0 .INDENT 3.5 .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 .UNINDENT .UNINDENT .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: .INDENT 0.0 .INDENT 3.5 .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 .UNINDENT .UNINDENT .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 Salt Bootstrap .sp The Salt Bootstrap script allows for a user to install the Salt Minion or Master on a variety of system distributions and versions. This shell script known as \fBbootstrap\-salt.sh\fP runs through a series of checks to determine the operating system type and version. It then installs the Salt binaries using the appropriate methods. The Salt Bootstrap script installs the minimum number of packages required to run Salt. This means that in the event you run the bootstrap to install via package, Git will not be installed. Installing the minimum number of packages helps ensure the script stays as lightweight as possible, assuming the user will install any other required packages after the Salt binaries are present on the system. The script source is available on GitHub: \fI\%https://github.com/saltstack/salt\-bootstrap\fP .SS Supported Operating Systems .INDENT 0.0 .IP \(bu 2 Amazon Linux 2012.09 .IP \(bu 2 Arch .IP \(bu 2 CentOS 5/6 .IP \(bu 2 Debian 6.x/7.x .IP \(bu 2 Fedora 17/18 .IP \(bu 2 FreeBSD 9.1 .IP \(bu 2 Gentoo .IP \(bu 2 Linaro .IP \(bu 2 Linux Mint 13/14 .IP \(bu 2 OpenSUSE 12.x .IP \(bu 2 Red Hat 5/6 .IP \(bu 2 Red Hat Enterprise 5/6 .IP \(bu 2 SmartOS .IP \(bu 2 SuSE 11 SP1/11 SP2 .IP \(bu 2 Ubuntu 10.x/11.x/12.x/13.04 .UNINDENT .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 In the event you do not see your distribution or version available please review the develop branch on Github as it main contain updates that are not present in the stable release: \fI\%https://github.com/saltstack/salt\-bootstrap/tree/develop\fP .UNINDENT .UNINDENT .SS Example Usage .sp The Salt Bootstrap script has a wide variety of options that can be passed as well as several ways of obtaining the bootstrap script itself. .sp For example, using \fBcurl\fP to install latest git: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C curl \-L http://bootstrap.saltstack.org | sudo sh \-s \-\- git develop .ft P .fi .UNINDENT .UNINDENT .sp If you have certificate issues using \fBcurl\fP, try the following: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C curl \-\-insecure \-L http://bootstrap.saltstack.org | sudo sh \-s \-\- git develop .ft P .fi .UNINDENT .UNINDENT .sp Using \fBwget\fP to install your distribution\(aqs stable packages: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C wget \-O \- http://bootstrap.saltstack.org | sudo sh .ft P .fi .UNINDENT .UNINDENT .sp If you have certificate issues using \fBwget\fP try the following: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C wget \-\-no\-check\-certificate \-O \- http://bootstrap.saltstack.org | sudo sh .ft P .fi .UNINDENT .UNINDENT .sp Install a specific version from git using \fBwget\fP: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C wget \-O \- http://bootstrap.saltstack.org | sh \-s \-\- \-P git v0.16.4 .ft P .fi .UNINDENT .UNINDENT .sp If you already have python installed, \fBpython 2.6\fP, then it\(aqs as easy as: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C python \-m urllib "http://bootstrap.saltstack.org" | sudo sh \-s \-\- git develop .ft P .fi .UNINDENT .UNINDENT .sp All python versions should support the following one liner: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C python \-c \(aqimport urllib; print urllib.urlopen("http://bootstrap.saltstack.org").read()\(aq | \e sudo sh \-s \-\- git develop .ft P .fi .UNINDENT .UNINDENT .sp On a FreeBSD base system you usually don\(aqt have either of the above binaries available. You \fBdo\fP have \fBfetch\fP available though: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C fetch \-o \- http://bootstrap.saltstack.org | sudo sh .ft P .fi .UNINDENT .UNINDENT .sp If all you want is to install a \fBsalt\-master\fP using latest git: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C curl \-L http://bootstrap.saltstack.org | sudo sh \-s \-\- \-M \-N git develop .ft P .fi .UNINDENT .UNINDENT .sp If you want to install a specific release version (based on the git tags): .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C curl \-L http://bootstrap.saltstack.org | sudo sh \-s \-\- git v0.16.4 .ft P .fi .UNINDENT .UNINDENT .sp Downloading the develop branch (from here standard command line options may be passed): .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C wget https://raw.githubusercontent.com/saltstack/salt\-bootstrap/develop/bootstrap\-salt.sh .ft P .fi .UNINDENT .UNINDENT .SS Command Line Options .sp \fB\-h\fP Display the help message and command line options. .sp \fB\-v\fP Display script version. .sp \fB\-n\fP No colours. .sp \fB\-D\fP Show debug output. .sp \fB\-c\fP Temporary configuration directory. .sp \fB\-k\fP Temporary directory holding the minion keys which will pre\-seed the master. .sp \fB\-M\fP Also install salt\-master. .sp \fB\-S\fP Also install salt\-syndic. .sp \fB\-N\fP Do not install salt\-minion. .sp \fB\-X\fP Do not start daemons after installation. .sp \fB\-C\fP Only run the configuration function. This option automatically bypasses any installation. .sp \fB\-P\fP Allow pip based installations. On some distributions the required salt packages or its dependencies are not available as a package for that distribution. Using this flag allows the script to use pip as a last resort method. .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 This works for functions which actually implement pip based installations. .UNINDENT .UNINDENT .sp \fB\-F\fP Allow copied files to overwrite existing(config, init.d, etc). .sp \fB\-U\fP If set, fully upgrade the system prior to bootstrapping salt. .sp \fB\-K\fP If set, keep the temporary files in the temporary directories specified with \-c and \-k. .SS GitFS Backend Walkthrough .sp While the default location of the salt state tree is on the Salt master, in /srv/salt, the master can create a bridge to external resources for files. One of these resources is the ability for the master to directly pull files from a git repository and serve them to minions. .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 This walkthrough assumes basic knowledge of Salt. To get up to speed, check out the \fBwalkthrough\fP\&. .UNINDENT .UNINDENT .sp The gitfs backend hooks into any number of remote git repositories and caches the data from the repository on the master. This makes distributing a state tree to multiple masters seamless and automated. .sp Salt\(aqs file server also has a concept of environments, when using the gitfs backend, Salt translates git branches and tags into environments, making environment management very simple. Just merging a QA or staging branch up to a production branch can be all that is required to make those file changes available to Salt. .SS Simple Configuration .sp To use the gitfs backend only two configuration changes are required on the master. The \fBfileserver_backend\fP option needs to be set with a value of \fBgit\fP: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C fileserver_backend: \- git .ft P .fi .UNINDENT .UNINDENT .sp To configure what fileserver backends will be searched for requested files. .sp Now the gitfs system needs to be configured with a remote: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C gitfs_remotes: \- git://github.com/saltstack/salt\-states.git .ft P .fi .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 The salt\-states repo is not currently updated with the latest versions of the available states. Please review \fI\%https://github.com/saltstack\-formulas\fP for the latest versions. .UNINDENT .UNINDENT .sp These changes require a restart of the master, then the git repo will be cached on the master and new requests for the \fBsalt://\fP protocol will send files found in the remote git repository via the master. .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 The master caches the files from the git server and serves them out, minions do not connect directly to the git server meaning that only requested files are delivered to minions. .UNINDENT .UNINDENT .SS Multiple Remotes .sp The \fBgitfs_remotes\fP option can accept a list of git remotes, the remotes are then searched in order for the requested file. A simple scenario can illustrate this behavior. .sp Assuming that the \fBgitfs_remotes\fP option specifies three remotes: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C gitfs_remotes: \- git://github.com/example/first.git \- git://github.com/example/second.git \- file:///root/third .ft P .fi .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 This example is purposefully contrived to illustrate the behavior of the gitfs backend. This example should not be read as a recommended way to lay out files and git repos. .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 The \fBfile://\fP prefix denotes a git repository in a local directory. However, it will still use the given \fBfile://\fP URL as a remote, rather than copying the git repo to the salt cache. This means that any refs you want accessible must exist as \fIlocal\fP refs in the specified repo. .UNINDENT .UNINDENT .sp Assume that each repository contains some files: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C first.git: top.sls edit/vim.sls edit/vimrc nginx/init.sls second.git: edit/dev_vimrc haproxy/init.sls third: haproxy/haproxy.conf edit/dev_vimrc .ft P .fi .UNINDENT .UNINDENT .sp The repositories will be searched for files by the master in the order in which they are defined in the configuration, Therefore the remote \fBgit://github.com/example/first.git\fP will be searched first, if the requested file is found then it is served and no further searching is executed. This means that if the file \fBsalt://haproxy/init.sls\fP is requested then it will be pulled from the \fBgit://github.com/example/second.git\fP git repo. If \fBsalt://haproxy/haproxy.conf\fP is requested then it will be pulled from the third repo. .SS Serving from a Subdirectory .sp The \fBgitfs_root\fP option gives the ability to serve files from a subdirectory within the repository. The path is defined relative to the root of the repository. .sp With this repository structure: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C repository.git: somefolder otherfolder top.sls edit/vim.sls edit/vimrc nginx/init.sls .ft P .fi .UNINDENT .UNINDENT .sp Configuration and files can be accessed normally with: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C gitfs_root: somefolder/otherfolder .ft P .fi .UNINDENT .UNINDENT .SS Multiple Backends .sp Sometimes it may make sense to use multiple backends. For instance, if sls files are stored in git, but larger files need to be stored directly on the master. .sp The logic used for multiple remotes is also used for multiple backends. If the \fBfileserver_backend\fP option contains multiple backends: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C fileserver_backend: \- roots \- git .ft P .fi .UNINDENT .UNINDENT .sp Then the \fBroots\fP backend (the default backend of files in \fB/srv/salt\fP) will be searched first for the requested file, then if it is not found on the master the git remotes will be searched. .SS Branches, environments and top.sls files .sp As stated above, when using the \fBgitfs\fP backend, branches will be mapped to environments using the branch name as identifier. There is an exception to this rule thought: the \fBmaster\fP branch is implicitly mapped to the \fBbase\fP environment. Therefore, for a typical \fBbase\fP, \fBqa\fP, \fBdev\fP setup, you\(aqll have to create the following branches: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C master qa dev .ft P .fi .UNINDENT .UNINDENT .sp Also, \fBtop.sls\fP files from different branches will be merged into one big file at runtime. Since this could lead to hardly manageable configurations, the recommended setup is to have the \fBtop.sls\fP file only in your master branch, and use environment\-specific branches for states definitions. .SS GitFS Remotes over SSH .sp In order to configure a \fBgitfs_remotes\fP repository over SSH transport the \fBgit+ssh\fP URL form must be used. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C gitfs_remotes: \- git+ssh://git@github.com/example/salt\-states.git .ft P .fi .UNINDENT .UNINDENT .sp The private key used to connect to the repository must be located in \fB~/.ssh/id_rsa\fP for the user running the salt\-master. .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 GitFS requires the Python module \fBGitPython\fP, version 0.3.0 or newer. If your Master runs Ubuntu 12.04 LTS, you will likely need to install GitPython using \fI\%pip\fP\&. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C # pip install GitPython .ft P .fi .UNINDENT .UNINDENT .UNINDENT .UNINDENT .SS Using Git as an External Pillar Source .sp Git repositories can also be used to provide \fBPillar\fP data, using the \fBExternal Pillar\fP system. To define a git external pillar, you can add a section like the following to your master config file: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C ext_pillar: \- git: .ft P .fi .UNINDENT .UNINDENT .sp The \fB\fP param is the branch containing the pillar SLS tree, and the \fB\fP param is the URI for the repository. The below example would add the \fBmaster\fP branch of the specified repo as an external pillar source. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C ext_pillar: \- git: master https://domain.com/pillar.git .ft P .fi .UNINDENT .UNINDENT .sp More information on the git external pillar can be found \fBhere\fP\&. .SS Why aren\(aqt my custom modules/states/etc. syncing to my Minions? .sp In versions 0.16.3 and older, when using the \fBgit fileserver backend\fP, certain versions of GitPython may generate errors when fetching, which Salt fails to catch. While not fatal to the fetch process, these interrupt the fileserver update that takes place before custom types are synced, and thus interrupt the sync itself. Try disabling the git fileserver backend in the master config, restarting the master, and attempting the sync again. .sp This issue is worked around in Salt 0.16.4 and newer. .SS The MacOS X (Maverick) Developer Step By Step Guide To Salt Installation .sp This document provides a step by step guide to installing a salt cluster (one master, and one minion running on a local VM) on Mac OS X to start playing with salt. It is aimed at developers, so it may be a little too slow for experienced admins. At the end of it, you will have installed a bare Nginx server on a minion using the master. The official (Linux) walkthrough can be found \fI\%here\fP\&. .SS The 5 Cent Salt Intro .sp Since you\(aqre here you\(aqve probably already heard about Salt, so you already know Salt lets you configure and run commands on hordes of servers easily. Here\(aqs a brief overview of a Salt cluster: .INDENT 0.0 .IP \(bu 2 Salt works by having a "master" server sending commands to one or multiple "minion" servers [1]\&. The master server is the "command center". It is going to be the place where you store your configuration files, aka: "which server is the db, which is the web server, and what libraries and software they should have installed". The minions receive orders from the master. Minions are the servers actually performing work for your business. .IP \(bu 2 Salt has two types of configuration files: .sp 1. the "salt communication channels" or "meta" or "config" configuration files (not official names): one for the master (usually is /etc/salt/master , \fBon the master server\fP), and one for minions (default is /etc/salt/minion or /etc/salt/minion.conf, \fBon the minion servers\fP). Those files are used to determine things like the Salt Master IP, port, Salt folder locations, etc.. If these are configured incorrectly, your minions will probably be unable to receive orders from the master, or the master will not know which software a given minion should install. .sp 2. the "business" or "service" configuration files (once again, not an official name): these are configuration files, ending with ".sls" extension, that describe which software should run on which server, along with particular configuration properties for the software that is being installed. These files should be created in the /srv/salt folder by default, but their location can be changed using ... /etc/salt/master configuration file! .UNINDENT .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 This tutorial contains a third important configuration file, not to be confused with the previous two: the virtual machine provisioning configuration file. This in itself is not specifically tied to Salt, but it also contains some Salt configuration. More on that in step 3. Also note that all configuration files are YAML files. So indentation matters. .UNINDENT .UNINDENT .IP [1] 5 Salt also works with "masterless" configuration where a minion is autonomous (in which case salt can be seen as a local configuration tool), or in "multiple master" configuration. See the documentation for more on that. .SS Before Digging In, The Architecture Of The Salt Cluster .SS Salt Master .sp The "Salt master" server is going to be the Mac OS machine, directly. Commands will be run from a terminal app, so Salt will need to be installed on the Mac. This is going to be more convenient for toying around with configuration files. .SS Salt Minion .sp We\(aqll only have one "Salt minion" server. It is going to be running on a Virtual Machine running on the Mac, using VirtualBox. It will run an Ubuntu distribution. .SS Step 1 \- Configuring The Salt Master On Your Mac .sp \fI\%official documentation\fP .sp Because Salt has a lot of dependencies that are not built in Mac OS X, we will use Homebrew to install Salt. Homebrew is a package manager for Mac, it\(aqs great, use it (for this tutorial at least!). Some people spend a lot of time installing libs by hand to better understand dependencies, and then realize how useful a package manager is once they\(aqre configuring a brand new machine and have to do it all over again. It also lets you \fIuninstall\fP things easily. .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 Brew is a Ruby program (Ruby is installed by default with your Mac). Brew downloads, compile and links software. The linking phase is when compiled software is deployed on your machine. It may conflict with manually installed software, especially in the /usr/local directory. It\(aqs ok, remove the manually installed version then refresh the link by typing \fBbrew link \(aqpackageName\(aq\fP\&. Brew has a \fBbrew doctor\fP command that can help you troubleshoot. It\(aqs a great command, use it often. Brew requires xcode command line tools. When you run brew the first time it asks you to install them if they\(aqre not already on your system. Brew installs software in /usr/local/bin (system bins are in /usr/bin). In order to use those bins you need your $PATH to search there first. Brew tells you if your $PATH needs to be fixed. .UNINDENT .UNINDENT .sp \fBTIP:\fP .INDENT 0.0 .INDENT 3.5 Use the keyboard shortcut \fBcmd + shift + period\fP in the "open" Mac OS X dialog box to display hidden files and folders, such as .profile. .UNINDENT .UNINDENT .SS Install Homebrew .sp Install Homebrew here \fI\%http://brew.sh/\fP Or just type .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C ruby \-e "$(curl \-fsSL https://raw.githubusercontent.com/mxcl/homebrew/go)" .ft P .fi .UNINDENT .UNINDENT .sp Now type the following commands in your terminal (you may want to type brew doctor after each to make sure everything\(aqs fine): .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C brew install python brew install swig brew install zmq .ft P .fi .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 zmq is ZeroMQ. It\(aqs a fantastic library used for server to server network communication and is at the core of Salt efficiency. .UNINDENT .UNINDENT .SS Install Salt .sp you should now have everything ready to launch this command: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C pip install salt .ft P .fi .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 There should be no need for \fBsudo pip install salt\fP\&. Brew installed Python for your user, so you should have all the access. In case you would like to check, type \fBwhich python\fP to ensure that it\(aqs /usr/local/bin/python, and \fBwhich pip\fP which should be /usr/local/bin/pip. .UNINDENT .UNINDENT .sp Now type \fBpython\fP in a terminal then, \fBimport salt\fP\&. There should be no errors. Now exit the Python terminal using \fBexit()\fP\&. .SS Create The Master Configuration .sp If the default /etc/salt/master configuration file was not created, copy\-paste it from here: \fI\%http://docs.saltstack.com/ref/configuration/examples.html#configuration\-examples\-master\fP .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 \fB/etc/salt/master\fP is a file, not a folder. .UNINDENT .UNINDENT .sp Salt Master configuration changes. The Salt master needs a few customization to be able to run on Mac OS X: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C sudo launchctl limit maxfiles 4096 8192 .ft P .fi .UNINDENT .UNINDENT .sp In the /etc/salt/master file, change max_open_files to 8192 (or just add the line: \fBmax_open_files: 8192\fP (no quote) if it doesn\(aqt already exists). .sp You should now be able to launch the Salt master: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C sudo salt\-master \-\-log\-level=all .ft P .fi .UNINDENT .UNINDENT .sp There should be no errors when running the above command. .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 This command is supposed to be a daemon, but for toying around, we\(aqll keep it running on a terminal to monitor the activity. .UNINDENT .UNINDENT .sp Now that the master is set, let\(aqs configure a minion on a VM. .SS Step 2 \- Configuring The Minion VM .sp The Salt minion is going to run on a Virtual Machine. There are a lot of software options that let you run virtual machines on a mac, But for this tutorial we\(aqre going to use VirtualBox. In addition to virtualBox, we will use Vagrant, which allows you to create the base VM configuration. .sp Vagrant lets you build ready to use VM images, starting from an OS image and customizing it using "provisioners". In our case, we\(aqll use it to: .INDENT 0.0 .IP \(bu 2 Download the base Ubuntu image .IP \(bu 2 Install salt on that Ubuntu image (Salt is going to be the "provisioner" for the VM). .IP \(bu 2 Launch the VM .IP \(bu 2 SSH into the VM to debug .IP \(bu 2 Stop the VM once you\(aqre done. .UNINDENT .SS Install VirtualBox .sp Go get it here: \fI\%https://www.virtualBox.org/wiki/Downloads\fP (click on VirtualBox for OS X hosts => x86/amd64) .SS Install Vagrant .sp Go get it here: \fI\%http://downloads.vagrantup.com/\fP and choose the latest version (1.3.5 at time of writing), then the .dmg file. double\-click to install it. Make sure the \fBvagrant\fP command is found when run in the terminal. Type \fBvagrant\fP\&. It should display a list of commands. .SS Create The Minion VM Folder .sp Create a folder in which you will store your minion\(aqs VM. In this tutorial, it\(aqs going to be a minion folder in the $home directory. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C cd $home mkdir minion .ft P .fi .UNINDENT .UNINDENT .SS Initialize Vagrant .sp From the minion folder, type .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C vagrant init .ft P .fi .UNINDENT .UNINDENT .sp This command creates a default Vagrantfile configuration file. This configuration file will be used to pass configuration parameters to the Salt provisioner in Step 3. .SS Import Precise64 Ubuntu Box .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C vagrant box add precise64 http://files.vagrantup.com/precise64.box .ft P .fi .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 This box is added at the global Vagrant level. You only need to do it once as each VM will use this same file. .UNINDENT .UNINDENT .SS Modify the Vagrantfile .sp Modify ./minion/Vagrantfile to use th precise64 box. Change the \fBconfig.vm.box\fP line to: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C config.vm.box = "precise64" .ft P .fi .UNINDENT .UNINDENT .sp Uncomment the line creating a host\-only IP. This is the ip of your minion (you can change it to something else if that IP is already in use): .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C config.vm.network :private_network, ip: "192.168.33.10" .ft P .fi .UNINDENT .UNINDENT .sp At this point you should have a VM that can run, although there won\(aqt be much in it. Let\(aqs check that. .SS Checking The VM .sp From the $home/minion folder type: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C vagrant up .ft P .fi .UNINDENT .UNINDENT .sp A log showing the VM booting should be present. Once it\(aqs done you\(aqll be back to the terminal: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C ping 192.168.33.10 .ft P .fi .UNINDENT .UNINDENT .sp The VM should respond to your ping request. .sp Now log inside the VM in ssh using Vagrant again: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C vagrant ssh .ft P .fi .UNINDENT .UNINDENT .sp You should see the shell prompt changing to something similar to \fBvagrant@precise64:~$\fP meaning you\(aqre inside the VM. From there enter the following: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C ping 10.0.2.2 .ft P .fi .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 That ip is the ip of your VM host (the Mac OS X OS). The number is a VirtualBox default and is displayed in the log after the Vagrant ssh command. We\(aqll use that IP to tell the minion where the Salt master is. Once you\(aqre done, end the ssh session by typing \fBexit\fP\&. .UNINDENT .UNINDENT .sp It\(aqs now time to connect the VM to the salt master .SS Step 3 \- Connecting Master and Minion .SS Creating The Minion Configuration File .sp Create the \fB/etc/salt/minion\fP file. In that file, put the following lines, giving the ID for this minion, and the IP of the master: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C master: 10.0.2.2 id: \(aqminion1\(aq file_client: remote .ft P .fi .UNINDENT .UNINDENT .sp Minions authenticate with the master using keys. Keys are generated automatically if you don\(aqt provide one, and you can accept them later on. But this requires you to accept the minion key every time you destroy and recreate a minion (which could be quite often). A better way is to create those keys in advance, feed them to the minion, and authorize them once. .SS Preseed minion keys .sp From the minion folder on your Mac run: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C sudo salt\-key \-\-gen\-keys=minion1 .ft P .fi .UNINDENT .UNINDENT .sp This should create two files: minion1.pem, and minion1.pub. Since those files have been created by sudo, but will be used by vagrant, you need to change ownership: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C sudo chown youruser:yourgroup minion1.pem sudo chown youruser:yourgroup minion1.pub .ft P .fi .UNINDENT .UNINDENT .sp Then copy the .pub file into the list of accepted minions: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C sudo cp minion1.pub /etc/salt/pki/master/minions/minion1 .ft P .fi .UNINDENT .UNINDENT .SS Modify Vagrantfile to Use Salt Provisioner .sp Let\(aqs now modify the Vagrantfile used to provision the Salt VM. Add the following section in the Vagrantfile (note: it should be at the same indentation level as the other properties): .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C # salt\-vagrant config config.vm.provision :salt do |salt| salt.run_highstate = true salt.minion_config = "./minion.conf" salt.minion_key = "./minion1.pem" salt.minion_pub = "./minion1.pub" end .ft P .fi .UNINDENT .UNINDENT .sp Now destroy the vm and recreate it from the /minion folder: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C vagrant destroy vagrant up .ft P .fi .UNINDENT .UNINDENT .sp If everything is fine you should see the following message: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C "Bootstrapping Salt... (this may take a while) Salt successfully configured and installed!" .ft P .fi .UNINDENT .UNINDENT .SS Checking Master\-Minion Communication .sp To make sure the master and minion are talking to each other, enter the following: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C sudo salt \(aq*\(aq test.ping .ft P .fi .UNINDENT .UNINDENT .sp You should see your minion answering the ping. It\(aqs now time to do some configuration. .SS Step 4 \- Configure Services to Install On the Minion .sp In this step we\(aqll use the Salt master to instruct our minion to install Nginx. .SS Checking the system\(aqs original state .sp First, make sure that an HTTP server is not installed on our minion. When opening a browser directed at \fBhttp://192.168.33.10/\fP You should get an error saying the site cannot be reached. .SS Initialize the top.sls file .sp System configuration is done in the /srv/salt/top.sls file (and subfiles/folders), and then applied by running the \fBstate.highstate\fP command to have the Salt master give orders so minions will update their instructions and run the associated commands. .sp First Create an empty file on your Salt master (Mac OS X machine): .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C touch /srv/salt/top.sls .ft P .fi .UNINDENT .UNINDENT .sp When the file is empty, or if no configuration is found for our minion an error is reported: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C sudo salt \(aqminion1\(aq state.highstate .ft P .fi .UNINDENT .UNINDENT .sp Should return an error stating: "No Top file or external nodes data matches found". .SS Create The Nginx Configuration .sp Now is finally the time to enter the real meat of our server\(aqs configuration. For this tutorial our minion will be treated as a web server that needs to have Nginx installed. .sp Insert the following lines into the \fB/srv/salt/top.sls\fP file (which should current be empty). .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C base: \(aqminion1\(aq: \- bin.nginx .ft P .fi .UNINDENT .UNINDENT .sp Now create a \fB/srv/salt/bin/nginx.sls\fP file containing the following: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C nginx: pkg.installed: \- name: nginx service.running: \- enable: True \- reload: True .ft P .fi .UNINDENT .UNINDENT .SS Check Minion State .sp Finally run the state.highstate command again: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C sudo salt \(aqminion1\(aq state.highstate .ft P .fi .UNINDENT .UNINDENT .sp You should see a log showing that the Nginx package has been installed and the service configured. To prove it, open your browser and navigate to \fI\%http://192.168.33.10/\fP, you should see the standard Nginx welcome page. .sp Congratulations! .SS Where To Go From Here .sp A full description of configuration management within Salt (sls files among other things) is available here: \fI\%http://docs.saltstack.com/index.html#configuration\-management\fP .SS Writing Salt Tests .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 THIS TUTORIAL IS A WORK IN PROGRESS .UNINDENT .UNINDENT .sp Salt comes with a powerful integration and unit test suite. The test suite allows for the fully automated run of integration and/or unit tests from a single interface. The integration tests are surprisingly easy to write and can be written to be either destructive or non\-destructive. .SS Gettign Set Up For Tests .sp To walk through adding an integration test, start by getting the latest development code and the test system from github: .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 The develop branch often has failing tests and should always be considered a staging area. For a checkout that tests should be running perfectly on please checkout from a specific release tag. .UNINDENT .UNINDENT .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C git clone git@github.com:saltstack/salt.git pip install git+https://github.com/saltstack/salt\-testing.git#egg=SaltTesting .ft P .fi .UNINDENT .UNINDENT .sp Now that a fresh checkout is available run the test suite .SS Destructive vs Non\-destructive .sp Since Salt is used to change the settings and behavior of systems often the best approach to run tests is to make actual changes to an underlying system. This is where the concept of destructive integration tests comes into play. Tests can be written to alter the system they are running on. This capability is what fills in the gap needed to properly test aspects of system management like package installation. .sp To write a destructive test import and use the \fIdestructiveTest\fP decorator for the test method: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C import integration from salttesting.helpers import destructiveTest class PkgTest(integration.ModuleCase): @destructiveTest def test_pkg_install(self): ret = self.run_function(\(aqpkg.install\(aq, name=\(aqfinch\(aq) self.assertSaltTrueReturn(ret) ret = self.run_function(\(aqpkg.purge\(aq, name=\(aqfinch\(aq) self.assertSaltTrueReturn(ret) .ft P .fi .UNINDENT .UNINDENT .SS Automated Test Runs .sp SaltStack maintains a Jenkins server which can be viewed at \fI\%http://jenkins.saltstack.com\fP\&. The tests executed from this Jenkins server create fresh virtual machines for each test run, then execute the destructive tests on the new clean virtual machine. This allows for the execution of tests across supported platforms. .SS Salt Cloud .SS Salt as a Cloud Controller .sp In Salt 0.14.0 advanced cloud control systems were introduced, allowing for private cloud vms to be managed directly with Salt. This system is generally referred to as \fBSalt Virt\fP\&. .sp The Salt Virt system already exists and is installed within Salt itself, this means that beyond setting up Salt no additional salt code needs to be deployed. .sp The main goal of Salt Virt is the facilitate a very fast and simple cloud. A cloud that can scale and a fully featured cloud. Salt Virt comes with the ability to set up and manage complex virtual machine networking, powerful image and disk management, as well as virtual machine migration, migration with and without shared storage. .sp This means that Salt Virt can be used to create a cloud from a blade center and a SAN, but can also create a cloud out of a swarm of Linux Desktops without a single shared storage system. Salt Virt can make clouds from truly commodity hardware, but can also stand up the power of specialized hardware as well. .SS Setting up Hypervisors .sp The first step to set up the hypervisors involves getting the correct software installed and setting up the hypervisor network interfaces. .SS Installing Hypervisor Software .sp Salt Virt is made to be hypervisor agnostic, but currently the only fully implemented hypervisor is KVM via libvirt. .sp The required software for a hypervisor is libvirt and kvm. For advanced features install libguestfs or qemu\-nbd. .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 Libguestfs and qemu\-nbd allow for virtual machine images to be mounted before startup and get pre\-seeded with configurations and a salt minion .UNINDENT .UNINDENT .sp This sls will set up the needed software for a hypervisor, and run the routines to set up the libvirt pki keys. .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 Package names and setup used is Red Hat specific, different package names will be required for different platforms .UNINDENT .UNINDENT .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C libvirt: pkg: \- installed file: \- managed \- name: /etc/sysconfig/libvirtd \- contents: \(aqLIBVIRTD_ARGS="\-\-listen"\(aq \- require: \- pkg: libvirt libvirt: \- keys \- require: \- pkg: libvirt service: \- running \- name: libvirtd \- require: \- pkg: libvirt \- network: br0 \- libvirt: libvirt \- watch: \- file: libvirt libvirt\-python: pkg: \- installed libguestfs: pkg: \- installed \- pkgs: \- libguestfs \- libguestfs\-tools .ft P .fi .UNINDENT .UNINDENT .SS Hypervisor Network Setup .sp The hypervisors will need to be running a network bridge to serve up network devices for virtual machines, this formula will set up a standard bridge on a hypervisor connecting the bridge to eth0: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C eth0: network.managed: \- enabled: True \- type: eth \- bridge: br0 br0: network.managed: \- enabled: True \- type: bridge \- proto: dhcp \- require: \- network: eth0 .ft P .fi .UNINDENT .UNINDENT .SS Virtual Machine Network Setup .sp Salt Virt comes with a system to model the network interfaces used by the deployed virtual machines, by default a single interface is created for the deployed virtual machine and is bridged to \fBbr0\fP\&. To get going with the default networking setup ensure that the bridge interface named \fBbr0\fP exists on the hypervisor and is bridged to an active network device. .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 To use more advanced networking in Salt Virt read the \fISalt Virt Networking\fP document: .sp \fBSalt Virt Networking\fP .UNINDENT .UNINDENT .SS Libvirt State .sp One of the challenges of deploying a libvirt based cloud is the distribution of libvirt certificates. These certificates allow for virtual machine migration. Salt comes with a system used to auto deploy these certificates. Salt manages the signing authority key and generates keys for libvirt clients on the master, signs them with the certificate authority and uses pillar to distribute them. This is managed via the \fBlibvirt\fP state. Simply execute this formula on the minion to ensure that the certificate is in place and up to date: .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 The above formula includes the calls needed to set up libvirt keys. .UNINDENT .UNINDENT .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C libvirt_keys: libvirt.keys .ft P .fi .UNINDENT .UNINDENT .SS Getting Virtual Machine Images Ready .sp Salt Virt, requires that virtual machine images be provided as these are not generated on the fly. Generating these virtual machine images differs greatly based on the underlying platform. .sp Virtual machine images can be manually created using KVM and running through the installer, but this process is not recommended since it is very manual and prone to errors. .sp Virtual Machine generation applications are available for many platforms: .INDENT 0.0 .TP .B vm\-builder: \fI\%http://wiki.debian.org/VMBuilder\fP .UNINDENT .sp Once virtual machines images are available the easiest way to make them available to Salt Virt is to place them in the Salt file server. Just copy an image into \fB/srv/salt\fP and it can now be used by Salt Virt. .sp For purposes of this demo, the file name \fBcentos.img\fP will be used. .SS Existing Virtual Machine Images .sp Many existing Linux distributions distribute virtual machine images which can be used with Salt Virt. Please be advised that NONE OF THESE IMAGES ARE SUPPORTED BY SALTSTACK. .SS CentOS .sp These images have been prepared for OpenNebula but should work without issue with Salt Virt, only the raw qcow image file is needed: \fI\%http://wiki.centos.org/Cloud/OpenNebula\fP .SS Fedora Linux .sp Images for Fedora Linux can be found here: \fI\%http://cloud.fedoraproject.org\fP .SS Ubuntu Linux .sp Images for Ubuntu Linux can be found here: \fI\%http://cloud\-images.ubuntu.com/\fP .SS Using Salt Virt .sp With hypervisors set up and virtual machine images ready, Salt can start issuing cloud commands. .sp Start by running a Salt Virt hypervisor info command: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt\-run virt.hyper_info .ft P .fi .UNINDENT .UNINDENT .sp This will query what the running hypervisor stats are and display information for all configured hypervisors. This command will also validate that the hypervisors are properly configured. .sp Now that hypervisors are available a virtual machine can be provisioned. The \fBvirt.init\fP routine will create a new virtual machine: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt\-run virt.init centos1 2 512 salt://centos.img .ft P .fi .UNINDENT .UNINDENT .sp This command assumes that the CentOS virtual machine image is sitting in the root of the Salt fileserver. Salt Virt will now select a hypervisor to deploy the new virtual machine on and copy the virtual machine image down to the hypervisor. .sp Once the VM image has been copied down the new virtual machine will be seeded. Seeding the VMs involves setting pre\-authenticated Salt keys on the new VM and if needed, will install the Salt Minion on the new VM before it is started. .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 The biggest bottleneck in starting VMs is when the Salt Minion needs to be installed. Making sure that the source VM images already have Salt installed will GREATLY speed up virtual machine deployment. .UNINDENT .UNINDENT .sp Now that the new VM has been prepared, it can be seen via the \fBvirt.query\fP command: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt\-run virt.query .ft P .fi .UNINDENT .UNINDENT .sp This command will return data about all of the hypervisors and respective virtual machines. .sp Now that the new VM is booted it should have contacted the Salt Master, a \fBtest.ping\fP will reveal if the new VM is running. .SS Migrating Virtual Machines .sp Salt Virt comes with full support for virtual machine migration, and using the libvirt state in the above formula makes migration possible. .sp A few things need to be available to support migration. Many operating systems turn on firewalls when originally set up, the firewall needs to be opened up to allow for libvirt and kvm to cross communicate and execution migration routines. On Red Hat based hypervisors in particular port 16514 needs to be opened on hypervisors: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C iptables \-A INPUT \-m state \-\-state NEW \-m tcp \-p tcp \-\-dport 16514 \-j ACCEPT .ft P .fi .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 More in\-depth information regarding distribution specific firewall settings can read in: .sp \fBOpening the Firewall up for Salt\fP .UNINDENT .UNINDENT .sp Salt also needs an additional flag to be turned on as well. The \fBvirt.tunnel\fP option needs to be turned on. This flag tells Salt to run migrations securely via the libvirt TLS tunnel and to use port 16514. Without \fBvirt.tunnel\fP libvirt tries to bind to random ports when running migrations. To turn on \fBvirt.tunnel\fP simple apply it to the master config file: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C virt.tunnel: True .ft P .fi .UNINDENT .UNINDENT .sp Once the master config has been updated, restart the master and send out a call to the minions to refresh the pillar to pick up on the change: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt \e* saltutil.refresh_modules .ft P .fi .UNINDENT .UNINDENT .sp Now, migration routines can be run! To migrate a VM, simply run the Salt Virt migrate routine: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt\-run virt.migrate centos .ft P .fi .UNINDENT .UNINDENT .SS VNC Consoles .sp Salt Virt also sets up VNC consoles by default, allowing for remote visual consoles to be oped up. The information from a \fBvirt.query\fP routine will display the vnc console port for the specific vms: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C centos CPU: 2 Memory: 524288 State: running Graphics: vnc \- hyper6:5900 Disk \- vda: Size: 2.0G File: /srv/salt\-images/ubuntu2/system.qcow2 File Format: qcow2 Nic \- ac:de:48:98:08:77: Source: br0 Type: bridge .ft P .fi .UNINDENT .UNINDENT .sp The line \fIGraphics: vnc \- hyper6:5900\fP holds the key. First the port named, in this case 5900, will need to be available in the hypervisor\(aqs firewall. Once the port is open, then the console can be easily opened via vncviewer: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C vncviewer hyper6:5900 .ft P .fi .UNINDENT .UNINDENT .sp By default there is no VNC security set up on these ports, which suggests that keeping them firewalled and mandating that SSH tunnels be used to access these VNC interfaces. Keep in mind that activity on a VNC interface that is accessed can be viewed by any other user that accesses that same VNC interface, and any other user logging in can also operate with the logged in user on the virtual machine. .SS Conclusion .sp Now with Salt Virt running, new hypervisors can be seamlessly added just by running the above states on new bare metal machines, and these machines will be instantly available to Salt Virt. .SS Halite .SS Installing and Configuring Halite .sp In this tutorial, we\(aqll walk through installing and setting up Halite. As of 2013\-10\-12, a packaged version of Halite is not available. In addition, the current version of Halite is considered pre\-alpha and is supported only in Salt 0.17 or greater. Additional information is available on GitHub: \fI\%https://github.com/saltstack/halite\fP .sp Before beginning this tutorial, ensure that the salt\-master is installed. To install the salt\-master, please review the installation documentation: \fI\%http://docs.saltstack.com/topics/installation/index.html\fP .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 Halite only works with Salt versions greater than 0.17. .UNINDENT .UNINDENT .SS Installing Halite Via Package .sp On CentOS, RHEL, or Fedora: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C $ yum install python\-halite .ft P .fi .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 By default python\-halite only installs CherryPy. If you would like to use a different webserver please review the instructions below to install pip and your server of choice. The package does not modify the master configuration with \fB/etc/salt/master\fP\&. .UNINDENT .UNINDENT .SS Installing Halite Using pip .sp To begin the installation of Halite from PyPi, you\(aqll need to install pip. The Salt package, as well as the bootstrap, do not install pip by default. .sp On CentOS, RHEL, or Fedora: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C $ yum install python\-pip .ft P .fi .UNINDENT .UNINDENT .sp On Debian: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C $ apt\-get install python\-pip .ft P .fi .UNINDENT .UNINDENT .sp Once you have pip installed, use it to install halite: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C $ pip install \-U halite .ft P .fi .UNINDENT .UNINDENT .sp Depending on the webserver you want to run halite through, you\(aqll need to install that piece as well. On RHEL based distros, use one of the following: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C $ pip install cherrypy .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C $ pip install paste .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C $ yum install python\-devel $ yum install gcc $ pip install gevent .ft P .fi .UNINDENT .UNINDENT .sp On Debian based distributions: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C $ pip install CherryPy .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C $ pip install paste .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C $ apt\-get install gcc $ apt\-get install python\-dev $ apt\-get install libevent\-dev $ pip install gevent .ft P .fi .UNINDENT .UNINDENT .SS Configuring Halite Permissions .sp Configuring Halite access permissions is easy. By default, you only need to ensure that the @runner group is configured. In the \fB/etc/salt/master file\fP, uncomment and modify the following lines: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C external_auth: pam: testuser: \- .* \- \(aq@runner\(aq .ft P .fi .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 You cannot use the root user for pam login; it will fail to authenticate. .UNINDENT .UNINDENT .sp Halite uses the runner manage.status to get the status of minions, so runner permissions are required. As you can see in this example, the root user has been configured. If you aren\(aqt running Halite as the root user, you\(aqll need to modify this value. For example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C external_auth: pam: mytestuser: \- .* \- \(aq@runner\(aq \- \(aq@wheel\(aq .ft P .fi .UNINDENT .UNINDENT .sp Currently Halite allows, but does not require, any wheel modules. .SS Configuring Halite Settings .sp Once you\(aqve configured the permissions for Halite, you\(aqll need to set up the Halite settings in the /etc/salt/master file. Halite supports CherryPy, Paste and Gevent out of the box. .sp To configure cherrypy, add the following to the bottom of your /etc/salt/master file: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C halite: level: \(aqdebug\(aq server: \(aqcherrypy\(aq host: \(aq0.0.0.0\(aq port: \(aq8080\(aq cors: False tls: True certpath: \(aq/etc/pki/tls/certs/localhost.crt\(aq keypath: \(aq/etc/pki/tls/certs/localhost.key\(aq pempath: \(aq/etc/pki/tls/certs/localhost.pem\(aq .ft P .fi .UNINDENT .UNINDENT .sp If you wish to use paste: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C halite: level: \(aqdebug\(aq server: \(aqpaste\(aq host: \(aq0.0.0.0\(aq port: \(aq8080\(aq cors: False tls: True certpath: \(aq/etc/pki/tls/certs/localhost.crt\(aq keypath: \(aq/etc/pki/tls/certs/localhost.key\(aq pempath: \(aq/etc/pki/tls/certs/localhost.pem\(aq .ft P .fi .UNINDENT .UNINDENT .sp To use gevent: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C halite: level: \(aqdebug\(aq server: \(aqgevent\(aq host: \(aq0.0.0.0\(aq port: \(aq8080\(aq cors: False tls: True certpath: \(aq/etc/pki/tls/certs/localhost.crt\(aq keypath: \(aq/etc/pki/tls/certs/localhost.key\(aq pempath: \(aq/etc/pki/tls/certs/localhost.pem\(aq .ft P .fi .UNINDENT .UNINDENT .sp The "cherrypy" and "gevent" servers require the certpath and keypath files to run tls/ssl. The .crt file holds the public cert and the .key file holds the private key. Whereas the "paste" server requires a single .pem file that contains both the cert and key. This can be created simply by concatenating the .crt and .key files. .sp If you want to use a self\-signed cert, you can create one using the Salt.tls module: .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 You might wish to target only a specific minion. The example below targets all connected minions. .UNINDENT .UNINDENT .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq tls.create_self_signed_cert test .ft P .fi .UNINDENT .UNINDENT .sp You can also use \fBsalt\-call\fP to create a self\-signed cert. .. code\-block:: bash .INDENT 0.0 .INDENT 3.5 salt\-call tls.create_self_signed_cert tls .UNINDENT .UNINDENT .sp When using self\-signed certs, browsers will need approval before accepting the cert. If the web application page has been cached with a non\-HTTPS version of the app, then the browser cache will have to be cleared before it will recognize and prompt to accept the self\-signed certificate. .SS Starting Halite .sp Once you\(aqve configured the halite section of your /etc/salt/master, you can restart the salt\-master service, and your halite instance will be available. Depending on your configuration, the instance will be available either at \fI\%http://localhost:8080/app\fP, \fI\%http://domain:8080/app\fP, or \fI\%http://123.456.789.012:8080/app\fP . .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 halite requires an HTML 5 compliant browser. .UNINDENT .UNINDENT .sp All logs relating to halite are logged to the default /var/log/salt/master file. .SS Running Your Halite Instance Through Nginx .SS Running Your Halite Instance Through Apache .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 manifested using matchers in these configurations: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C client_acl: fred: \- web\e*: \- pkg.list_pkgs \- test.* \- apache.* .ft P .fi .UNINDENT .UNINDENT .sp In the above example, fred is able to send commands only to minions which match the specified glob target. This can be expanded to include other functions for other minions based on standard targets. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C external_auth: pam: dave: \- test.ping \- mongo\e*: \- network.* \- log\e*: \- network.* \- pkg.* \- \(aqG@os:RedHat\(aq: \- kmod.* steve: \- .* .ft P .fi .UNINDENT .UNINDENT .sp The above allows for all minions to be hit by test.ping by dave, and adds a few functions that dave can execute on other minions. It also allows steve unrestricted access to salt commands. .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 \fIaccess control system\fP: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C external_auth: pam: thatch: \- \(aqweb*\(aq: \- test.* \- network.* steve: \- .* .ft P .fi .UNINDENT .UNINDENT .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. User steve is given unrestricted access to minion commands. .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 The PAM module does not allow authenticating as \fBroot\fP\&. .UNINDENT .UNINDENT .sp To allow access to \fIwheel modules\fP or \fIrunner modules\fP the following \fB@\fP syntax must be used: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C external_auth: pam: thatch: \- \(aq@wheel\(aq \- \(aq@runner\(aq .ft P .fi .UNINDENT .UNINDENT .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: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C $ salt \-a pam web\e* test.ping .ft P .fi .UNINDENT .UNINDENT .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 \fB\-T\fP option when authenticating: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C $ salt \-T \-a pam web\e* test.ping .ft P .fi .UNINDENT .UNINDENT .sp Now a token will be created that has a expiration of, by default, 12 hours. This token is stored in a file named \fB\&.salt_token\fP in the active user\(aqs home directory. Once the token is created, it is sent with all subsequent communications. The user authentication does not need to be entered again until the token expires. The token expiration time can be set in the Salt master config file. .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 as the Salt State Tree. .sp Pillar was added to Salt in version 0.9.8 .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 Storing sensitive data .sp Unlike state tree, pillar data is only available for the targeted minion specified by the matcher type. This makes it useful for storing sensitive data specific to a particular minion. .UNINDENT .UNINDENT .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 file is identical in behavior and function as \fBfile_roots\fP: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C pillar_roots: base: \- /srv/pillar .ft P .fi .UNINDENT .UNINDENT .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 .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C base: \(aq*\(aq: \- packages .ft P .fi .UNINDENT .UNINDENT .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 \fBos\fP grains: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C dev: \(aqos:Debian\(aq: \- match: grain \- servers .ft P .fi .UNINDENT .UNINDENT .sp \fB/srv/pillar/packages.sls\fP .INDENT 0.0 .INDENT 3.5 .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 .UNINDENT .UNINDENT .sp Now this data can be used from within modules, renderers, State SLS files, and more via the shared pillar \fI\%dict\fP: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C apache: pkg: \- installed \- name: {{ pillar[\(aqapache\(aq] }} .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C git: pkg: \- installed \- name: {{ pillar[\(aqgit\(aq] }} .ft P .fi .UNINDENT .UNINDENT .sp Note that you cannot just list key/value\-information in \fBtop.sls\fP\&. .SS Pillar namespace flattened .sp The separate pillar files all share the same namespace. Given a \fBtop.sls\fP of: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C base: \(aq*\(aq: \- packages \- services .ft P .fi .UNINDENT .UNINDENT .sp a \fBpackages.sls\fP file of: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C bind: bind9 .ft P .fi .UNINDENT .UNINDENT .sp and a \fBservices.sls\fP file of: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C bind: named .ft P .fi .UNINDENT .UNINDENT .sp Then a request for the \fBbind\fP pillar will only return \(aqnamed\(aq; the \(aqbind9\(aq value is not available. It is better to structure your pillar files with more hierarchy. For example your \fBpackage.sls\fP file could look like: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C packages: bind: bind9 .ft P .fi .UNINDENT .UNINDENT .SS Including Other Pillars .sp New in version 0.16.0. .sp Pillar SLS files may include other pillar files, similar to State files. Two syntaxes are available for this purpose. The simple form simply includes the additional pillar as if it were part of the same file: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C include: \- users .ft P .fi .UNINDENT .UNINDENT .sp The full include form allows two additional options \-\- passing default values to the templating engine for the included pillar file as well as an optional key under which to nest the results of the included pillar: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C include: \- users: defaults: sudo: [\(aqbob\(aq, \(aqpaul\(aq] key: users .ft P .fi .UNINDENT .UNINDENT .sp With this form, the included file (users.sls) will be nested within the \(aqusers\(aq key of the compiled pillar. Additionally, the \(aqsudo\(aq value will be available as a template variable to users.sls. .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.items\fP and and \fBpillar.raw\fP\&. \fBpillar.items\fP will return a freshly reloaded pillar and \fBpillar.raw\fP will return the current pillar without a refresh: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pillar.items .ft P .fi .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 Prior to version 0.16.2, this function is named \fBpillar.data\fP\&. This function name is still supported for backwards compatibility. .UNINDENT .UNINDENT .SS Pillar "get" Function .sp New in version 0.14.0. .sp The \fBpillar.get\fP function works much in the same way as the \fBget\fP method in a python dict, but with an enhancement: nested dict components can be extracted using a \fI:\fP delimiter. .sp If a structure like this is in pillar: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C foo: bar: baz: qux .ft P .fi .UNINDENT .UNINDENT .sp Extracting it from the raw pillar in an sls formula or file template is done this way: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C {{ pillar[\(aqfoo\(aq][\(aqbar\(aq][\(aqbaz\(aq] }} .ft P .fi .UNINDENT .UNINDENT .sp Now, with the new \fBpillar.get\fP function the data can be safely gathered and a default can be set, allowing the template to fall back if the value is not available: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C {{ salt[\(aqpillar.get\(aq](\(aqfoo:bar:baz\(aq, \(aqqux\(aq) }} .ft P .fi .UNINDENT .UNINDENT .sp This makes handling nested structures much easier. .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 \fBpillar.get()\fP vs \fBsalt[\(aqpillar.get\(aq]()\fP .sp It should be noted that within templating, the \fBpillar\fP variable is just a dictionary. This means that calling \fBpillar.get()\fP inside of a template will just use the default dictionary \fB\&.get()\fP function which does not include the extra \fB:\fP delimeter functionality. It must be called using the above syntax (\fBsalt[\(aqpillar.get\(aq](\(aqfoo:bar:baz\(aq, \(aqqux\(aq)\fP) to get the salt function, instead of the default dictionary behavior. .UNINDENT .UNINDENT .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. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq saltutil.refresh_pillar .ft P .fi .UNINDENT .UNINDENT .sp This function triggers the minion to asynchronously refresh the pillar and will always return \fBNone\fP\&. .SS Targeting with Pillar .sp Pillar data can be used when targeting minions. This allows for ultimate control and flexibility when targeting minions. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt \-I \(aqsomekey:specialvalue\(aq test.ping .ft P .fi .UNINDENT .UNINDENT .sp Like with \fBGrains\fP, it is possible to use globbing as well as match nested values in Pillar, by adding colons for each level that is being traversed. The below example would match minions with a pillar named \fBfoo\fP, which is a dict containing a key \fBbar\fP, with a value beginning with \fBbaz\fP: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt \-I \(aqfoo:bar:baz*\(aq test.ping .ft P .fi .UNINDENT .UNINDENT .SS Master Config In Pillar .sp For convenience the data stored in the master configuration file is made available in all minion\(aqs pillars. This makes global configuration of services and systems very easy but may not be desired if sensitive data is stored in the master configuration. .sp To disable the master config from being added to the pillar set \fBpillar_opts\fP to \fBFalse\fP: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C pillar_opts: False .ft P .fi .UNINDENT .UNINDENT .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 has been removed. 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: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C master_tops: ext_nodes: cobbler\-external\-nodes .ft P .fi .UNINDENT .UNINDENT .sp for \fBCobbler\fP or: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C master_tops: reclass: inventory_base_uri: /etc/reclass classes_uri: roles .ft P .fi .UNINDENT .UNINDENT .sp for \fBReclass\fP\&. .sp It\(aqs also possible to create custom master_tops modules. These modules must go in a subdirectory called \fItops\fP in the \fIextension_modules\fP directory. The \fIextension_modules\fP directory is not defined by default (the default \fI/srv/salt/_modules\fP will NOT work as of this release) .sp Custom tops modules are written like any other execution module, see the source for the two modules above for examples of fully functional ones. Below is a degenerate example: .sp /etc/salt/master: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C extension_modules: /srv/salt/modules master_tops: customtop: True .ft P .fi .UNINDENT .UNINDENT .sp /srv/salt/modules/tops/customtop.py: .sp \fIsalt minion state.show_top\fP should then display something like: .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. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C # salt\-run jobs.active .ft P .fi .UNINDENT .UNINDENT .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. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C # salt\-run jobs.lookup_jid .ft P .fi .UNINDENT .UNINDENT .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. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C # salt\-run jobs.list_jobs .ft P .fi .UNINDENT .UNINDENT .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 Scheduling is enabled via the \fBschedule\fP option on either the master or minion config files, or via a minion\(aqs pillar data. .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 The scheduler executes different functions on the master and minions. When running on the master the functions reference runner functions, when running on the minion the functions specify execution functions. .UNINDENT .UNINDENT .sp Specify \fBmaxrunning\fP to ensure that there are no more than N copies of a particular routine running. Use this for jobs that may be long\-running and could step on each other or otherwise double execute. The default for \fBmaxrunning\fP is 1. .sp States are executed on the minion, as all states are. You can pass positional arguments are provide a yaml dict of named arguments. .SS States .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C schedule: log\-loadavg: function: cmd.run seconds: 3660 args: \- \(aqlogger \-t salt < /proc/loadavg\(aq kwargs: stateful: False shell: True .ft P .fi .UNINDENT .UNINDENT .SS Highstates .sp To set up a highstate to run on a minion every 60 minutes set this in the minion config or pillar: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C schedule: highstate: function: state.highstate minutes: 60 .ft P .fi .UNINDENT .UNINDENT .sp Time intervals can be specified as seconds, minutes, hours, or days. .SS Runners .sp Runner executions can also be specified on the master within the master configuration file: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C schedule: overstate: function: state.over seconds: 35 minutes: 30 hours: 3 .ft P .fi .UNINDENT .UNINDENT .sp The above configuration will execute the state.over runner every 3 hours, 30 minutes and 35 seconds, or every 12,635 seconds. .SS Scheduler With Returner .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: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C schedule: uptime: function: status.uptime seconds: 60 returner: mysql meminfo: function: status.meminfo minutes: 5 returner: mysql .ft P .fi .UNINDENT .UNINDENT .sp Since specifying the returner repeatedly can be tiresome, the \fBschedule_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/MINION AS AN UNPRIVILEGED USER .sp While the default setup runs the master and minion as the root user, it is generally wise to run the master as an unprivileged user. .sp As of Salt 0.9.10 it is possible to run Salt as as a non\-root user. This can be done by setting the \fBuser\fP parameter in the master configuration file. and restarting the \fBsalt\-master\fP service. .sp The minion has it\(aqs own \fBuser\fP parameter as well, but running the minion as an unprivileged user will keep it from making changes to things like users, installed packages, etc. unless access controls (sudo, etc.) are setup on the minion to permit the non\-root user to make the needed changes. .sp In order to allow Salt to successfully run as a non\-root user, ownership and permissions need to be set such that the desired user can read from and write to the following directories (and their subdirectories, where applicable): .INDENT 0.0 .IP \(bu 2 /etc/salt .IP \(bu 2 /var/cache/salt .IP \(bu 2 /var/log/salt .UNINDENT .sp Ownership can be easily changed with \fBchown\fP, like so: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C # chown \-R user /etc/salt /var/cache/salt /var/log/salt .ft P .fi .UNINDENT .UNINDENT .sp \fBWARNING:\fP .INDENT 0.0 .INDENT 3.5 Running either the master or minion with the \fBroot_dir\fP parameter specified will affect these paths, as will setting options like \fBpki_dir\fP, \fBcachedir\fP, \fBlog_file\fP, and other options that normally live in the above directories. .UNINDENT .UNINDENT .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 Troubleshooting the Salt Master .sp If your Salt master is having issues such as minions not returning data, slow execution times, or a variety of other issues the \fBSalt master troubleshooting page\fP contains details on troubleshooting the most common issues encountered. .SS Troubleshooting the Salt Minion .sp In the event that your Salt minion is having issues a variety of solutions and suggestions are available at the \fBSalt minion troubleshooting page\fP\&. .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: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt\-master \-l debug salt\-minion \-l debug .ft P .fi .UNINDENT .UNINDENT .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 acknowledgment 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: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C nc \-v \-z salt.master.ip 4505 nc \-v \-z salt.master.ip 4506 .ft P .fi .UNINDENT .UNINDENT .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 creating your state tree, it is generally recommended to invoke \fBstate.highstate\fP with \fBsalt\-call\fP\&. 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: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt\-call \-l debug state.highstate .ft P .fi .UNINDENT .UNINDENT .sp The main difference between using \fBsalt\fP and using \fBsalt\-call\fP is that \fBsalt\-call\fP is run from the minion, and it only runs the selected function on that minion. By contrast, \fBsalt\fP is run from the master, and requires you to specify the minions on which to run the command using salt\(aqs \fBtargeting system\fP\&. .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: .INDENT 0.0 .INDENT 3.5 .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 .UNINDENT .UNINDENT .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): .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C [root@salt\-master ~]# ulimit \-n 1024 .ft P .fi .UNINDENT .UNINDENT .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: .INDENT 0.0 .INDENT 3.5 .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 .UNINDENT .UNINDENT .sp Or with the following Salt state: .INDENT 0.0 .INDENT 3.5 .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 .UNINDENT .UNINDENT .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: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C # CentOS 5 and RHEL 5: 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 # CentOS 6 and RHEL 6: chcon system_u:object_r:rpm_exec_t:s0 /usr/bin/salt\-minion chcon system_u:object_r:rpm_exec_t:s0 /usr/bin/salt\-call .ft P .fi .UNINDENT .UNINDENT .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: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt\-master \-l debug salt\-minion \-l debug .ft P .fi .UNINDENT .UNINDENT .sp Then pass the signal to the master or minion when it seems to be unresponsive: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C killall \-SIGUSR1 salt\-master killall \-SIGUSR1 salt\-minion .ft P .fi .UNINDENT .UNINDENT .sp Also under BSD and Mac OS X in addition to SIGUSR1 signal, debug subroutine set up for SIGINFO which has an advantage of being sent by Ctrl+T shortcut. .sp When filing an issue or sending questions to the mailing list for a problem with an unresponsive daemon this information can be invaluable. .SS Salt 0.16.x minions cannot communicate with a 0.17.x master .sp As of release 0.17.1 you can no longer run different versions of Salt on your Master and Minion servers. This is due to a protocol change for security purposes. The Salt team will continue to attempt to ensure versions are as backwards compatible as possible. .SH TROUBLESHOOTING THE SALT MASTER .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 master in the foreground: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C # salt\-master \-l debug .ft P .fi .UNINDENT .UNINDENT .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 does the Master Need Open? .sp 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 acknowledgment that your minion has connected, it could very well be a firewall interfering with the connection. See our \fBfirewall configuration\fP page for help opening the firewall on various platforms. .sp If you\(aqve opened the correct TCP ports 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 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: .INDENT 0.0 .INDENT 3.5 .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 .UNINDENT .UNINDENT .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): .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C [root@salt\-master ~]# ulimit \-n 1024 .ft P .fi .UNINDENT .UNINDENT .sp If this value is not equal to at least twice the number of minions, then it will need to be raised. For example, in an environment with 1800 minions, the \fBnofile\fP limit should be set to no less than 3600. This can be done by creating the file \fB/etc/security/limits.d/99\-salt.conf\fP, with the following contents: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C root hard nofile 4096 root soft nofile 4096 .ft P .fi .UNINDENT .UNINDENT .sp Replace \fBroot\fP with the user under which the master runs, if different. .sp If your master does not have an \fB/etc/security/limits.d\fP directory, the lines can simply be appended to \fB/etc/security/limits.conf\fP\&. .sp As with any change to resource limits, it is best to stay logged into your current shell and open another shell to run \fBulimit \-n\fP again and verify that the changes were applied correctly. Additionally, if your master is running upstart, it may be necessary to specify the \fBnofile\fP limit in \fB/etc/default/salt\-master\fP if upstart isn\(aqt respecting your resource limits: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C limit nofile 4096 4096 .ft P .fi .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 The above is simply an example of how to set these values, and you may wish to increase them even further if your Salt master is doing more than just running Salt. .UNINDENT .UNINDENT .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: .INDENT 0.0 .INDENT 3.5 .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 .UNINDENT .UNINDENT .sp Or with the following Salt state: .INDENT 0.0 .INDENT 3.5 .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 .UNINDENT .UNINDENT .SS Live Python Debug Output .sp If the master seems to be unresponsive, a SIGUSR1 can be passed to the salt\-master threads to display what piece of code is executing. This debug information can be invaluable in tracking down bugs. .sp To pass a SIGUSR1 to the master, first make sure the minion is running in the foreground. Stop the service if it is running as a daemon, and start it in the foreground like so: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C # salt\-master \-l debug .ft P .fi .UNINDENT .UNINDENT .sp Then pass the signal to the master when it seems to be unresponsive: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C # killall \-SIGUSR1 salt\-master .ft P .fi .UNINDENT .UNINDENT .sp When filing an issue or sending questions to the mailing list for a problem with an unresponsive daemon, be sure to include this information if possible. .SS Commands Time Out or Do Not Return Output .sp Depending on your OS (this is most common on Ubuntu due to apt\-get) you may sometimes encounter times where your highstate, or other long running commands do not return output. This is most commonly due to the timeout being reached. By default the timeout is set to 5 seconds. The timeout value can easily be increased by modifying the \fBtimeout\fP line within your \fB/etc/salt/master\fP configuration file. .SS Passing the \-c Option to Salt Returns a Permissions Error .sp Using the \fB\-c\fP option with the Salt command modifies the configuration directory. When the configuratio file is read it will still base data off of the \fBroot_dir\fP setting. This can result in unintended behavior if you are expecting files such as \fB/etc/salt/pki\fP to be pulled from the location specified with \fB\-c\fP\&. Modify the \fBroot_dir\fP setting to address this behavior. .SH TROUBLESHOOTING THE SALT MINION .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 in the foreground: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C # salt\-minion \-l debug .ft P .fi .UNINDENT .UNINDENT .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 does the Minion Need Open? .sp No ports need to be opened on the minion, as it makes outbound connections to the master. If you\(aqve put both your Salt master and minion in debug mode and don\(aqt see an acknowledgment that your minion has connected, it could very well be a firewall interfering with the connection. See our \fBfirewall configuration\fP page for help opening the firewall on various platforms. .sp If you have netcat installed, you can check port connectivity from the minion with the \fBnc\fP command: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C $ nc \-v \-z salt.master.ip.addr 4505 Connection to salt.master.ip.addr 4505 port [tcp/unknown] succeeded! $ nc \-v \-z salt.master.ip.addr 4506 Connection to salt.master.ip.addr 4506 port [tcp/unknown] succeeded! .ft P .fi .UNINDENT .UNINDENT .sp The \fI\%Nmap\fP utility can also be used to check if these ports are open: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C # nmap \-sS \-q \-p 4505\-4506 salt.master.ip.addr Starting Nmap 6.40 ( http://nmap.org ) at 2013\-12\-29 19:44 CST Nmap scan report for salt.master.ip.addr (10.0.0.10) Host is up (0.0026s latency). PORT STATE SERVICE 4505/tcp open unknown 4506/tcp open unknown MAC Address: 00:11:22:AA:BB:CC (Intel) Nmap done: 1 IP address (1 host up) scanned in 1.64 seconds .ft P .fi .UNINDENT .UNINDENT .sp If you\(aqve opened the correct TCP ports 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 initially creating your state tree, it is generally recommended to invoke \fBstate.highstate\fP from the minion with \fBsalt\-call\fP\&. 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: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C # salt\-call \-l debug state.highstate .ft P .fi .UNINDENT .UNINDENT .sp The main difference between using \fBsalt\fP and using \fBsalt\-call\fP is that \fBsalt\-call\fP is run from the minion, and it only runs the selected function on that minion. By contrast, \fBsalt\fP is run from the master, and requires you to specify the minions on which to run the command using salt\(aqs \fBtargeting system\fP\&. .SS Live Python Debug Output .sp If the minion seems to be unresponsive, a SIGUSR1 can be passed to the process to display what piece of code is executing. This debug information can be invaluable in tracking down bugs. .sp To pass a SIGUSR1 to the minion, first make sure the minion is running in the foreground. Stop the service if it is running as a daemon, and start it in the foreground like so: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C # salt\-minion \-l debug .ft P .fi .UNINDENT .UNINDENT .sp Then pass the signal to the minion when it seems to be unresponsive: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C # killall \-SIGUSR1 salt\-minion .ft P .fi .UNINDENT .UNINDENT .sp When filing an issue or sending questions to the mailing list for a problem with an unresponsive daemon, be sure to include this information if possible. .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 of this can be found in the \fBcontext\fP and \fBdefault\fP options from the \fBfile.managed\fP state: .INDENT 0.0 .INDENT 3.5 .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 .UNINDENT .UNINDENT .sp Notice that while the indentation is two spaces per level, for the values under the \fBcontext\fP and \fBdefaults\fP options there is a four\-space indent. If only two spaces are used to indent, then the information will not be loaded correctly. If using a double indent is not desirable, then a deeply\-nested dict can be declared with curly braces: .INDENT 0.0 .INDENT 3.5 .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 .UNINDENT .UNINDENT .SS True/False, Yes/No, On/Off .sp PyYAML will load these values as boolean \fBTrue\fP or \fBFalse\fP\&. Un\-capitalized versions will also be loaded as booleans (\fBtrue\fP, \fBfalse\fP, \fByes\fP, \fBno\fP, \fBon\fP, and \fBoff\fP). This can be especially problematic when constructing Pillar data. Make sure that your Pillars which need to use the string versions of these values are enclosed in quotes. .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 \fBintegers\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: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C /etc/vimrc: file: \- managed \- source: salt://edit/vimrc \- user: root \- group: root \- mode: 644 .ft P .fi .UNINDENT .UNINDENT .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: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C /etc/vimrc: file: \- managed \- source: salt://edit/vimrc \- user: root \- group: root \- mode: \(aq0644\(aq .ft P .fi .UNINDENT .UNINDENT .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: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C vim: pkg.installed .ft P .fi .UNINDENT .UNINDENT .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: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C vim: pkg.installed user.present .ft P .fi .UNINDENT .UNINDENT .sp Similarly declaring a short dec in the same ID dec as a standard dec does not work either... .sp ALSO DOES NOT WORK: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C fred: user.present ssh_auth.present: \- name: AAAAB3NzaC... \- user: fred \- enc: ssh\-dss \- require: \- user: fred .ft P .fi .UNINDENT .UNINDENT .sp The correct way is to define them like this: .INDENT 0.0 .INDENT 3.5 .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 .UNINDENT .UNINDENT .sp Alternatively, they can be defined the "old way", or with multiple "full decs": .INDENT 0.0 .INDENT 3.5 .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 .UNINDENT .UNINDENT .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: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C \- micro: "\eu00b5" \- copyright: "\eu00A9" \- A: "\ex41" \- alpha: "\eu0251" \- Alef: "\eu05d0" .ft P .fi .UNINDENT .UNINDENT .sp List of usable \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: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C repr(u"Text with wrong characters i need to figure out") .ft P .fi .UNINDENT .UNINDENT .sp This shell command can find wrong characters in your SLS files: .INDENT 0.0 .INDENT 3.5 .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 .UNINDENT .UNINDENT .SS Underscores stripped in Integer Definitions .sp If a definition only includes numbers and underscores, it is parsed by YAML as an integer and all underscores are stripped. To ensure the object becomes a string, it should be surrounded by quotes. \fI\%More information here\fP\&. .sp Here\(aqs an example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C >>> import yaml >>> yaml.safe_load(\(aq2013_05_10\(aq) 20130510 >>> yaml.safe_load(\(aq"2013_05_10"\(aq) \(aq2013_05_10\(aq .ft P .fi .UNINDENT .UNINDENT .SS Automatic \fBdatetime\fP conversion .sp If there is a value in a YAML file formatted \fB2014\-01\-20 14:23:23\fP or similar, YAML will automatically convert this to a Python \fBdatetime\fP object. These objects are not msgpack serializable, and so may break core salt functionality. If values such as these are needed in a salt YAML file (specifically a configuration file), they should be formatted with surrounding strings to force YAML to serialize them as strings: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C >>> import yaml >>> yaml.safe_load(\(aq2014\-01\-20 14:23:23\(aq) datetime.datetime(2014, 1, 20, 14, 23, 23) >>> yaml.safe_load(\(aq"2014\-01\-20 14:23:23"\(aq) \(aq2014\-01\-20 14:23:23\(aq .ft P .fi .UNINDENT .UNINDENT .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. .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 Blogs .sp SaltStack Inc. keeps a \fI\%blog\fP with recent news and advancements: .sp \fI\%http://www.saltstack.com/blog/\fP .sp Thomas Hatch also shares news and thoughts on Salt and related projects in his personal 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 Hack the Source .sp If you want to get involved with the development of source code or the documentation efforts, please review the \fBhacking section\fP! .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: .INDENT 0.0 .INDENT 3.5 .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 .UNINDENT .UNINDENT .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. .INDENT 0.0 .INDENT 3.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 .UNINDENT .UNINDENT .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: .INDENT 0.0 .INDENT 3.5 .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 .UNINDENT .UNINDENT .SS Firing Events .sp It is possible to fire events on either the minion\(aqs local bus, or to fire events intended for the master. To fire a local event from the minion, on the command line: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt\-call event.fire \(aq{"data": "message to be sent in the event"}\(aq \(aqtag\(aq .ft P .fi .UNINDENT .UNINDENT .sp To fire an event to be sent to the master, from the minion: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt\-call event.fire_master \(aq{"data": "message for the master"}\(aq \(aqtag\(aq .ft P .fi .UNINDENT .UNINDENT .sp If a process is listening on the minion, it may be useful for a user on the master to fire an event to it: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt minionname event.fire \(aq{"data": "message for the minion"}\(aq \(aqtag\(aq .ft P .fi .UNINDENT .UNINDENT .SS Firing Events From Code .sp Events can be very useful when writing execution modules, in order to inform various processes on the master when a certain task has taken place. In Salt versions previous to 0.17.0, the basic code looks like: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C # Import the proper library import salt.utils.event # Fire deploy action sock_dir = \(aq/var/run/salt/minion\(aq event = salt.utils.event.SaltEvent(\(aqmaster\(aq, sock_dir) event.fire_event(\(aqMessage to be sent\(aq, \(aqtag\(aq) .ft P .fi .UNINDENT .UNINDENT .sp In Salt version 0.17.0, the ability to send a payload with a more complex data structure than a string was added. When using this interface, a Python dictionary should be sent instead. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C # Import the proper library import salt.utils.event # Fire deploy action sock_dir = \(aq/var/run/salt/minion\(aq payload = {\(aqsample\-msg\(aq: \(aqthis is a test\(aq, \(aqexample\(aq: \(aqthis is the same test\(aq} event = salt.utils.event.SaltEvent(\(aqmaster\(aq, sock_dir) event.fire_event(payload, \(aqtag\(aq) .ft P .fi .UNINDENT .UNINDENT .sp It should be noted that this code can be used in 3rd party applications as well. So long as the salt\-minion process is running, the minion socket can be used: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C sock_dir = \(aq/var/run/salt/minion\(aq .ft P .fi .UNINDENT .UNINDENT .sp So long as the salt\-master process is running, the master socket can be used: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C sock_dir = \(aq/var/run/salt/master\(aq .ft P .fi .UNINDENT .UNINDENT .sp This allows 3rd party applications to harness the power of the Salt event bus programmatically, without having to make other calls to Salt. A 3rd party process can listen to the event bus on the master, and another 3rd party process can fire events to the process on the master, which Salt will happily pass along. .SH THE SALT MINE .sp Granted, it took a while for this name to be used in Salt, but version 0.15.0 introduces a new system to Salt called the Salt Mine. .sp The Salt Mine is used to bridge the gap between setting static variables and gathering live data. The Salt mine is used to collect arbitrary data from minions and store it on the master. This data is then made available to all minions via the \fBmine\fP module. .sp The data is gathered on the minion and sent back to the master where only the most recent data is maintained (if long term data is required use returners or the external job cache). .SS Mine Functions .sp To enable the Salt Mine the \fImine_functions\fP option needs to be applied to a minion. This option can be applied via the minion\(aqs configuration file, or the minion\(aqs pillar. The \fImine_functions\fP option dictates what functions are being executed and allows for arguments to be passed in: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C mine_functions: network.interfaces: [] test.ping: [] .ft P .fi .UNINDENT .UNINDENT .SS Mine Interval .sp The Salt Mine functions are executed when the minion starts and at a given interval by the scheduler. The default interval is every 60 minutes and can be adjusted for the minion via the \fImine_interval\fP option: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C mine_interval: 60 .ft P .fi .UNINDENT .UNINDENT .SH SALT CLOUD DOCUMENTATION .SS Cloud Actions .sp Once a VM has been created, there are a number of actions that can be performed on it. The "reboot" action can be used across all providers, but all other actions are specific to the cloud provider. In order to perform an action, you may specify it from the command line, including the name(s) of the VM to perform the action on: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C $ salt\-cloud \-a reboot vm_name $ salt\-cloud \-a reboot vm1 vm2 vm2 .ft P .fi .UNINDENT .UNINDENT .sp Or you may specify a map which includes all VMs to perform the action on: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C $ salt\-cloud \-a reboot \-m /path/to/mapfile .ft P .fi .UNINDENT .UNINDENT .sp The following is a list of actions currently supported by salt\-cloud: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C all providers: \- reboot ec2: \- start \- stop joyent: \- stop .ft P .fi .UNINDENT .UNINDENT .SS Getting Started With AWS EC2 .sp Amazon EC2 is a very widely used public cloud platform and one of the core platforms Salt Cloud has been built to support. .sp Previously, the suggested provider for AWS EC2 was the \fIaws\fP provider. This has been deprecated in favor of the \fIec2\fP provider. Configuration using the old \fIaws\fP provider will still function, but that driver is no longer in active development. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C # Note: This example is for /etc/salt/cloud.providers or any file in the # /etc/salt/cloud.providers.d/ directory. my\-ec2\-southeast\-public\-ips: # Set up the location of the salt master # minion: master: saltmaster.example.com # Set up grains information, which will be common for all nodes # using this provider grains: node_type: broker release: 1.0.1 # Specify whether to use public or private IP for deploy script. # # Valid options are: # private_ips \- The salt\-master is also hosted with EC2 # public_ips \- The salt\-master is hosted outside of EC2 # ssh_interface: public_ips # Set the EC2 access credentials (see below) # id: HJGRYCILJLKJYG key: \(aqkdjgfsgm;woormgl/aserigjksjdhasdfgn\(aq # Make sure this key is owned by root with permissions 0400. # private_key: /etc/salt/my_test_key.pem keyname: my_test_key securitygroup: default # Optionally configure default region # location: ap\-southeast\-1 availability_zone: ap\-southeast\-1b # Configure which user to use to run the deploy script. This setting is # dependent upon the AMI that is used to deploy. It is usually safer to # configure this individually in a profile, than globally. Typical users # are: # # Amazon Linux \-> ec2\-user # RHEL \-> ec2\-user # CentOS \-> ec2\-user # Ubuntu \-> ubuntu # ssh_username: ec2\-user # Optionally add an IAM profile iam_profile: \(aqarn:aws:iam::123456789012:instance\-profile/ExampleInstanceProfile\(aq provider: ec2 my\-ec2\-southeast\-private\-ips: # Set up the location of the salt master # minion: master: saltmaster.example.com # Specify whether to use public or private IP for deploy script. # # Valid options are: # private_ips \- The salt\-master is also hosted with EC2 # public_ips \- The salt\-master is hosted outside of EC2 # ssh_interface: private_ips # Set the EC2 access credentials (see below) # id: HJGRYCILJLKJYG key: \(aqkdjgfsgm;woormgl/aserigjksjdhasdfgn\(aq # Make sure this key is owned by root with permissions 0400. # private_key: /etc/salt/my_test_key.pem keyname: my_test_key securitygroup: default # Optionally configure default region # location: ap\-southeast\-1 availability_zone: ap\-southeast\-1b # Configure which user to use to run the deploy script. This setting is # dependent upon the AMI that is used to deploy. It is usually safer to # configure this individually in a profile, than globally. Typical users # are: # # Amazon Linux \-> ec2\-user # RHEL \-> ec2\-user # CentOS \-> ec2\-user # Ubuntu \-> ubuntu # ssh_username: ec2\-user # Optionally add an IAM profile iam_profile: \(aqmy other profile name\(aq provider: ec2 .ft P .fi .UNINDENT .UNINDENT .SS Access Credentials .sp The \fBid\fP and \fBkey\fP settings may be found in the Security Credentials area of the AWS Account page: .sp \fI\%https://portal.aws.amazon.com/gp/aws/securityCredentials\fP .sp Both are located in the Access Credentials area of the page, under the Access Keys tab. The \fBid\fP setting is labeled Access Key ID, and the \fBkey\fP setting is labeled Secret Access Key. .SS Key Pairs .sp In order to create an instance with Salt installed and configured, a key pair will need to be created. This can be done in the EC2 Management Console, in the Key Pairs area. These key pairs are unique to a specific region. Keys in the us\-east\-1 region can be configured at: .sp \fI\%https://console.aws.amazon.com/ec2/home?region=us\-east\-1#s=KeyPairs\fP .sp Keys in the us\-west\-1 region can be configured at .sp \fI\%https://console.aws.amazon.com/ec2/home?region=us\-west\-1#s=KeyPairs\fP .sp \&...and so on. When creating a key pair, the browser will prompt to download a pem file. This file must be placed in a directory accessable by Salt Cloud, with permissions set to either 0400 or 0600. .SS Security Groups .sp An instance on EC2 needs to belong to a security group. Like key pairs, these are unique to a specific region. These are also configured in the EC2 Management Console. Security groups for the us\-east\-1 region can be configured at: .sp \fI\%https://console.aws.amazon.com/ec2/home?region=us\-east\-1#s=SecurityGroups\fP .sp \&...and so on. .sp A security group defines firewall rules which an instance will adhere to. If the salt\-master is configured outside of EC2, the security group must open the SSH port (usually port 22) in order for Salt Cloud to install Salt. .SS IAM Profile .sp Amazon EC2 instances support the concept of an \fI\%instance profile\fP, which is a logical container for the IAM role. At the time that you launch an EC2 instance, you can associate the instance with an instance profile, which in turn corresponds to the IAM role. Any software that runs on the EC2 instance is able to access AWS using the permissions associated with the IAM role. .sp Scaffolding the profile is a 2 steps configurations: .INDENT 0.0 .INDENT 3.5 .INDENT 0.0 .IP 1. 3 Configure an IAM Role from the \fI\%IAM Management Console\fP\&. .IP 2. 3 Attach this role to a new profile. It can be done with the \fI\%AWS CLI\fP: .INDENT 3.0 .INDENT 3.5 .sp .nf .ft C > aws iam create\-instance\-profile \-\-instance\-profile\-name PROFILE_NAME > aws iam add\-role\-to\-instance\-profile \-\-instance\-profile\-name PROFILE_NAME \-\-role\-name ROLE_NAME .ft P .fi .UNINDENT .UNINDENT .UNINDENT .UNINDENT .UNINDENT .sp Once the profile is created, you can use the \fBPROFILE_NAME\fP to configure your cloud profiles. .SS Cloud Profiles .sp Set up an initial profile at \fB/etc/salt/cloud.profiles\fP: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C base_ec2_private: provider: my\-ec2\-southeast\-private\-ips image: ami\-e565ba8c size: Micro Instance ssh_username: ec2\-user base_ec2_public: provider: my\-ec2\-southeast\-public\-ips image: ami\-e565ba8c size: Micro Instance ssh_username: ec2\-user base_ec2_db: provider: my\-ec2\-southeast\-public\-ips image: ami\-e565ba8c size: m1.xlarge ssh_username: ec2\-user volumes: \- { size: 10, device: /dev/sdf } \- { size: 10, device: /dev/sdg, type: io1, iops: 1000 } \- { size: 10, device: /dev/sdh, type: io1, iops: 1000 } .ft P .fi .UNINDENT .UNINDENT .sp The profile can be realized now with a salt command: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C # salt\-cloud \-p base_ec2 ami.example.com # salt\-cloud \-p base_ec2_public ami.example.com # salt\-cloud \-p base_ec2_private ami.example.com .ft P .fi .UNINDENT .UNINDENT .sp This will create an instance named \fBami.example.com\fP in EC2. The minion that is installed on this instance will have an \fBid\fP of \fBami.example.com\fP\&. If the command was executed on the salt\-master, its Salt key will automatically be signed on the master. .sp Once the instance has been created with salt\-minion installed, connectivity to it can be verified with Salt: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C # salt \(aqami.example.com\(aq test.ping .ft P .fi .UNINDENT .UNINDENT .SS Required Settings .sp The following settings are always required for EC2: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C # Set the EC2 login data my\-ec2\-config: id: HJGRYCILJLKJYG key: \(aqkdjgfsgm;woormgl/aserigjksjdhasdfgn\(aq keyname: test securitygroup: quick\-start private_key: /root/test.pem provider: ec2 .ft P .fi .UNINDENT .UNINDENT .SS Optional Settings .sp EC2 allows a location to be set for servers to be deployed in. Availability zones exist inside regions, and may be added to increase specificity. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C my\-ec2\-config: # Optionally configure default region location: ap\-southeast\-1 availability_zone: ap\-southeast\-1b .ft P .fi .UNINDENT .UNINDENT .sp EC2 instances can have a public or private IP, or both. When an instance is deployed, Salt Cloud needs to log into it via SSH to run the deploy script. By default, the public IP will be used for this. If the salt\-cloud command is run from another EC2 instance, the private IP should be used. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C my\-ec2\-config: # Specify whether to use public or private IP for deploy script # private_ips or public_ips ssh_interface: public_ips .ft P .fi .UNINDENT .UNINDENT .sp Many EC2 instances do not allow remote access to the root user by default. Instead, another user must be used to run the deploy script using sudo. Some common usernames include ec2\-user (for Amazon Linux), ubuntu (for Ubuntu instances), admin (official Debian) and bitnami (for images provided by Bitnami). .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C my\-ec2\-config: # Configure which user to use to run the deploy script ssh_username: ec2\-user .ft P .fi .UNINDENT .UNINDENT .sp Multiple usernames can be provided, in which case Salt Cloud will attempt to guess the correct username. This is mostly useful in the main configuration file: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C my\-ec2\-config: ssh_username: \- ec2\-user \- ubuntu \- admin \- bitnami .ft P .fi .UNINDENT .UNINDENT .sp Multiple security groups can also be specified in the same fashion: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C my\-ec2\-config: securitygroup: \- default \- extra .ft P .fi .UNINDENT .UNINDENT .sp Block device mappings enable you to specify additional EBS volumes or instance store volumes when the instance is launched. This setting is also available on each cloud profile. Note that the number of instance stores varies by instance type. If more mappings are provided than are supported by the instance type, mappings will be created in the order provided and additional mappings will be ignored. Consult the \fI\%AWS documentation\fP for a listing of the available instance stores, device names, and mount points. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C my\-ec2\-config: block_device_mappings: \- DeviceName: /dev/sdb VirtualName: ephemeral0 \- DeviceName: /dev/sdc VirtualName: ephemeral1 .ft P .fi .UNINDENT .UNINDENT .sp You can also use block device mappings to change the size of the root device at the provisioing time. For example, assuming the root device is \(aq/dev/sda\(aq, you can set its size to 100G by using the following configuration. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C my\-ec2\-config: block_device_mappings: \- DeviceName: /dev/sda Ebs.VolumeSize: 100 .ft P .fi .UNINDENT .UNINDENT .sp Tags can be set once an instance has been launched. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C my\-ec2\-config: tag: tag0: value tag2: value .ft P .fi .UNINDENT .UNINDENT .SS Modify EC2 Tags .sp One of the features of EC2 is the ability to tag resources. In fact, under the hood, the names given to EC2 instances by salt\-cloud are actually just stored as a tag called Name. Salt Cloud has the ability to manage these tags: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-a get_tags mymachine salt\-cloud \-a set_tags mymachine tag1=somestuff tag2=\(aqOther stuff\(aq salt\-cloud \-a del_tags mymachine tag1,tag2,tag3 .ft P .fi .UNINDENT .UNINDENT .SS Rename EC2 Instances .sp As mentioned above, EC2 instances are named via a tag. However, renaming an instance by renaming its tag will cause the salt keys to mismatch. A rename function exists which renames both the instance, and the salt keys. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-a rename mymachine newname=yourmachine .ft P .fi .UNINDENT .UNINDENT .SS EC2 Termination Protection .sp EC2 allows the user to enable and disable termination protection on a specific instance. An instance with this protection enabled cannot be destroyed. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-a enable_term_protect mymachine salt\-cloud \-a disable_term_protect mymachine .ft P .fi .UNINDENT .UNINDENT .SS Rename on Destroy .sp When instances on EC2 are destroyed, there will be a lag between the time that the action is sent, and the time that Amazon cleans up the instance. During this time, the instance still retails a Name tag, which will cause a collision if the creation of an instance with the same name is attempted before the cleanup occurs. In order to avoid such collisions, Salt Cloud can be configured to rename instances when they are destroyed. The new name will look something like: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C myinstance\-DEL20f5b8ad4eb64ed88f2c428df80a1a0c .ft P .fi .UNINDENT .UNINDENT .sp In order to enable this, add rename_on_destroy line to the main configuration file: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C my\-ec2\-config: rename_on_destroy: True .ft P .fi .UNINDENT .UNINDENT .SS Listing Images .sp Normally, images can be queried on a cloud provider by passing the \fB\-\-list\-images\fP argument to Salt Cloud. This still holds true for EC2: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-\-list\-images my\-ec2\-config .ft P .fi .UNINDENT .UNINDENT .sp However, the full list of images on EC2 is extremely large, and querying all of the available images may cause Salt Cloud to behave as if frozen. Therefore, the default behavior of this option may be modified, by adding an \fBowner\fP argument to the provider configuration: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C owner: aws\-marketplace .ft P .fi .UNINDENT .UNINDENT .sp The possible values for this setting are \fBamazon\fP, \fBaws\-marketplace\fP, \fBself\fP, \fB\fP or \fBall\fP\&. The default setting is \fBamazon\fP\&. Take note that \fBall\fP and \fBaws\-marketplace\fP may cause Salt Cloud to appear as if it is freezing, as it tries to handle the large amount of data. .sp It is also possible to perform this query using different settings without modifying the configuration files. To do this, call the \fBavail_images\fP function directly: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-f avail_images my\-ec2\-config owner=aws\-marketplace .ft P .fi .UNINDENT .UNINDENT .SS EC2 Images .sp The following are lists of available AMI images, generally sorted by OS. These lists are on 3rd\-party websites, are not managed by Salt Stack in any way. They are provided here as a reference for those who are interested, and contain no warranty (express or implied) from anyone affiliated with Salt Stack. Most of them have never been used, much less tested, by the Salt Stack team. .INDENT 0.0 .IP \(bu 2 \fI\%Arch Linux\fP .IP \(bu 2 \fI\%FreeBSD\fP .IP \(bu 2 \fI\%Fedora\fP .IP \(bu 2 \fI\%CentOS\fP .IP \(bu 2 \fI\%Ubuntu\fP .IP \(bu 2 \fI\%Debian\fP .IP \(bu 2 \fI\%Gentoo\fP .IP \(bu 2 \fI\%OmniOS\fP .IP \(bu 2 \fI\%All Images on Amazon\fP .UNINDENT .SS show_image .sp This is a function that describes an AMI on EC2. This will give insight as to the defaults that will be applied to an instance using a particular AMI. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C $ salt\-cloud \-f show_image ec2 image=ami\-fd20ad94 .ft P .fi .UNINDENT .UNINDENT .SS show_instance .sp This action is a thin wrapper around \-\-full\-query, which displays details on a single instance only. In an environment with several machines, this will save a user from having to sort through all instance data, just to examine a single instance. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C $ salt\-cloud \-a show_instance myinstance .ft P .fi .UNINDENT .UNINDENT .SS ebs_optimized .sp This argument enables switching of the EbsOptimized setting which default to \(aqfalse\(aq. Indicates whether the instance is optimized for EBS I/O. This optimization provides dedicated throughput to Amazon EBS and an optimized configuration stack to provide optimal Amazon EBS I/O performance. This optimization isn\(aqt available with all instance types. Additional usage charges apply when using an EBS\-optimized instance. .sp This setting can be added to the profile or map file for an instance. .sp If set to True, this setting will enable an instance to be EbsOptimized .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C ebs_optimized: True .ft P .fi .UNINDENT .UNINDENT .sp This can also be set as a cloud provider setting in the EC2 cloud configuration: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C my\-ec2\-config: ebs_optimized: True .ft P .fi .UNINDENT .UNINDENT .SS del_root_vol_on_destroy .sp This argument overrides the default DeleteOnTermination setting in the AMI for the EBS root volumes for an instance. Many AMIs contain \(aqfalse\(aq as a default, resulting in orphaned volumes in the EC2 account, which may unknowingly be charged to the account. This setting can be added to the profile or map file for an instance. .sp If set, this setting will apply to the root EBS volume .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C del_root_vol_on_destroy: True .ft P .fi .UNINDENT .UNINDENT .sp This can also be set as a cloud provider setting in the EC2 cloud configuration: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C my\-ec2\-config: del_root_vol_on_destroy: True .ft P .fi .UNINDENT .UNINDENT .SS del_all_vols_on_destroy .sp This argument overrides the default DeleteOnTermination setting in the AMI for the not\-root EBS volumes for an instance. Many AMIs contain \(aqfalse\(aq as a default, resulting in orphaned volumes in the EC2 account, which may unknowingly be charged to the account. This setting can be added to the profile or map file for an instance. .sp If set, this setting will apply to any (non\-root) volumes that were created by salt\-cloud using the \(aqvolumes\(aq setting. .sp The volumes will not be deleted under the following conditions * If a volume is detached before terminating the instance * If a volume is created without this setting and attached to the instance .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C del_all_vols_on_destroy: True .ft P .fi .UNINDENT .UNINDENT .sp This can also be set as a cloud provider setting in the EC2 cloud configuration: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C my\-ec2\-config: del_all_vols_on_destroy: True .ft P .fi .UNINDENT .UNINDENT .sp The setting for this may be changed on all volumes of an existing instance using one of the following commands: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-a delvol_on_destroy myinstance salt\-cloud \-a keepvol_on_destroy myinstance salt\-cloud \-a show_delvol_on_destroy myinstance .ft P .fi .UNINDENT .UNINDENT .sp The setting for this may be changed on a volume on an existing instance using one of the following commands: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-a delvol_on_destroy myinstance device=/dev/sda1 salt\-cloud \-a delvol_on_destroy myinstance volume_id=vol\-1a2b3c4d salt\-cloud \-a keepvol_on_destroy myinstance device=/dev/sda1 salt\-cloud \-a keepvol_on_destroy myinstance volume_id=vol\-1a2b3c4d salt\-cloud \-a show_delvol_on_destroy myinstance device=/dev/sda1 salt\-cloud \-a show_delvol_on_destroy myinstance volume_id=vol\-1a2b3c4d .ft P .fi .UNINDENT .UNINDENT .SS EC2 Termination Protection .sp EC2 allows the user to enable and disable termination protection on a specific instance. An instance with this protection enabled cannot be destroyed. The EC2 driver adds a show_term_protect action to the regular EC2 functionality. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-a show_term_protect mymachine salt\-cloud \-a enable_term_protect mymachine salt\-cloud \-a disable_term_protect mymachine .ft P .fi .UNINDENT .UNINDENT .SS Alternate Endpoint .sp Normally, EC2 endpoints are build using the region and the service_url. The resulting endpoint would follow this pattern: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C ec2.. .ft P .fi .UNINDENT .UNINDENT .sp This results in an endpoint that looks like: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C ec2.us\-east\-1.amazonaws.com .ft P .fi .UNINDENT .UNINDENT .sp There are other projects that support an EC2 compatibility layer, which this scheme does not account for. This can be overridden by specifying the endpoint directly in the main cloud configuration file: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C my\-ec2\-config: endpoint: myendpoint.example.com:1138/services/Cloud .ft P .fi .UNINDENT .UNINDENT .SS Volume Management .sp The EC2 driver has several functions and actions for management of EBS volumes. .SS Creating Volumes .sp A volume may be created, independent of an instance. A zone must be specified. A size or a snapshot may be specified (in GiB). If neither is given, a default size of 10 GiB will be used. If a snapshot is given, the size of the snapshot will be used. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-f create_volume ec2 zone=us\-east\-1b salt\-cloud \-f create_volume ec2 zone=us\-east\-1b size=10 salt\-cloud \-f create_volume ec2 zone=us\-east\-1b snapshot=snap12345678 salt\-cloud \-f create_volume ec2 size=10 type=standard salt\-cloud \-f create_volume ec2 size=10 type=io1 iops=1000 .ft P .fi .UNINDENT .UNINDENT .SS Attaching Volumes .sp Unattached volumes may be attached to an instance. The following values are required; name or instance_id, volume_id and device. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-a attach_volume myinstance volume_id=vol\-12345 device=/dev/sdb1 .ft P .fi .UNINDENT .UNINDENT .SS Show a Volume .sp The details about an existing volume may be retrieved. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-a show_volume myinstance volume_id=vol\-12345 salt\-cloud \-f show_volume ec2 volume_id=vol\-12345 .ft P .fi .UNINDENT .UNINDENT .SS Detaching Volumes .sp An existing volume may be detached from an instance. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-a detach_volume myinstance volume_id=vol\-12345 .ft P .fi .UNINDENT .UNINDENT .SS Deleting Volumes .sp A volume that is not attached to an instance may be deleted. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-f delete_volume ec2 volume_id=vol\-12345 .ft P .fi .UNINDENT .UNINDENT .SS Managing Key Pairs .sp The EC2 driver has the ability to manage key pairs. .SS Creating a Key Pair .sp A key pair is required in order to create an instance. When creating a key pair with this function, the return data will contain a copy of the private key. This private key is not stored by Amazon, and will not be obtainable past this point, and should be stored immediately. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-f create_keypair ec2 keyname=mykeypair .ft P .fi .UNINDENT .UNINDENT .SS Show a Key Pair .sp This function will show the details related to a key pair, not including the private key itself (which is not stored by Amazon). .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-f show_keypair ec2 keyname=mykeypair .ft P .fi .UNINDENT .UNINDENT .SS Delete a Key Pair .sp This function removes the key pair from Amazon. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-f delete_keypair ec2 keyname=mykeypair .ft P .fi .UNINDENT .UNINDENT .SS Getting Started With Azure .sp New in version 2014.1.0. .sp Azure is a cloud service by Microsoft providing virtual machines, SQL services, media services, and more. This document describes how to use Salt Cloud to create a virtual machine on Azure, with Salt installed. .sp You can find more information about Azure at \fI\%http://www.windowsazure.com/\fP\&. .SS Dependencies .INDENT 0.0 .IP \(bu 2 The \fI\%Azure\fP Python SDK. .IP \(bu 2 A Microsoft Azure account .IP \(bu 2 OpenSSL (to generate the certificates) .IP \(bu 2 \fI\%Salt\fP .UNINDENT .SS Configuration .sp Set up the provider config at \fB/etc/salt/cloud.providers.d/azure.conf\fP: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C # Note: This example is for /etc/salt/cloud.providers.d/azure.conf my\-azure\-config: provider: azure subscription_id: 3287abc8\-f98a\-c678\-3bde\-326766fd3617 certificate_path: /etc/salt/azure.pem # Set up the location of the salt master # minion: master: saltmaster.example.com provider: gce .ft P .fi .UNINDENT .UNINDENT .sp The certificate used must be generated by the user. OpenSSL can be used to create the management certificates. Two certificates are needed: a .cer file, which is uploaded to Azure, and a .pem file, which is stored locally. .sp To create the .pem file, execute the following command: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C openssl req \-x509 \-nodes \-days 365 \-newkey rsa:1024 \-keyout /etc/salt/azure.pem \-out /etc/salt/azure.pem .ft P .fi .UNINDENT .UNINDENT .sp To create the .cer file, execute the following command: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C openssl x509 \-inform pem \-in /etc/salt/azure.pem \-outform der \-out /etc/salt/azure.cer .ft P .fi .UNINDENT .UNINDENT .sp After you creating these files, the .cer file will need to be uploaded to Azure via the "Upload" action of the "Settings" tab of the management portal. .SS Cloud Profiles .sp Set up an initial profile at \fB/etc/salt/cloud.profiles\fP: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C azure\-ubuntu: provider: my\-azure\-config image: \(aqb39f27a8b8c64d52b05eac6a62ebad85__Ubuntu\-12_04_3\-LTS\-amd64\-server\-20131003\-en\-us\-30GB\(aq size: Small location: \(aqEast US\(aq ssh_username: azureuser ssh_password: verybadpass slot: production media_link: \(aqhttp://portalvhdabcdefghijklmn.blob.core.windows.net/vhds\(aq .ft P .fi .UNINDENT .UNINDENT .sp These options are described in more detail below. Once configured, the profile can be realized with a salt command: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-p azure\-ubuntu newinstance .ft P .fi .UNINDENT .UNINDENT .sp This will create an salt minion instance named \fBnewinstance\fP in Azure. If the command was executed on the salt\-master, its Salt key will automatically be signed on the master. .sp Once the instance has been created with salt\-minion installed, connectivity to it can be verified with Salt: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt newminion test.ping .ft P .fi .UNINDENT .UNINDENT .SS Profile Options .sp The following options are currently available for Azure. .SS provider .sp The name of the provider as configured in \fI/etc/salt/cloud.providers.d/azure.conf\fP\&. .SS image .sp The name of the image to use to create a VM. Available images can be viewed using the following command: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-\-list\-images my\-azure\-config .ft P .fi .UNINDENT .UNINDENT .SS size .sp The name of the size to use to create a VM. Available sizes can be viewed using the following command: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-\-list\-sizes my\-azure\-config .ft P .fi .UNINDENT .UNINDENT .SS location .sp The name of the location to create a VM in. Available locations can be viewed using the following command: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-\-list\-locations my\-azure\-config .ft P .fi .UNINDENT .UNINDENT .SS ssh_username .sp The user to use to log into the newly\-created VM to install Salt. .SS ssh_password .sp The password to use to log into the newly\-created VM to install Salt. .SS slot .sp The environment to which the hosted service is deployed. Valid values are \fIstaging\fP or \fIproduction\fP\&. When set to \fIproduction\fP, the resulting URL of the new VM will be \fI.cloudapp.net\fP\&. When set to \fIstaging\fP, the resulting URL will contain a generated hash instead. .SS media_link .sp This is the URL of the container that will store the disk that this VM uses. Currently, this container must already exist. If a VM has previously been created in the associated account, a container should already exist. In the web interface, go into the Storage area and click one of the available storage selections. Click the Containers link, and then copy the URL from the container that will be used. It generally looks like: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C http://portalvhdabcdefghijklmn.blob.core.windows.net/vhds .ft P .fi .UNINDENT .UNINDENT .SS Show Instance .sp This action is a thin wrapper around \fB\-\-full\-query\fP, which displays details on a single instance only. In an environment with several machines, this will save a user from having to sort through all instance data, just to examine a single instance. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-a show_instance myinstance .ft P .fi .UNINDENT .UNINDENT .SS Writing Cloud Provider Modules .sp Salt Cloud runs on a module system similar to the main Salt project. The modules inside saltcloud exist in the \fBsalt/cloud/clouds\fP directory of the salt source. .sp There are two basic types of cloud modules. If a cloud provider is supported by libcloud, then using it is the fastest route to getting a module written. The Apache Libcloud project is located at: .sp \fI\%http://libcloud.apache.org/\fP .sp Not every cloud provider is supported by libcloud. Additionally, not every feature in a supported cloud provider is necessary supported by libcloud. In either of these cases, a module can be created which does not rely on libcloud. .SS All Modules .sp The following functions are required by all modules, whether or not they are based on libcloud. .SS The __virtual__() Function .sp This function determines whether or not to make this cloud module available upon execution. Most often, it uses \fBget_configured_provider()\fP to determine if the necessary configuration has been set up. It may also check for necessary imports, to decide whether to load the module. In most cases, it will return a \fBTrue\fP or \fBFalse\fP value. If the name of the driver used does not match the filename, then that name should be returned instead of \fBTrue\fP\&. An example of this may be seen in the Azure module: .sp \fI\%https://github.com/saltstack/salt/blob/develop/salt/cloud/clouds/msazure.py\fP .SS The get_configured_provider() Function .sp This function uses \fBconfig.is_provider_configured()\fP to determine wither all required information for this driver has been configured. The last value in the list of required settings should be followed by a comma. .SS Libcloud Based Modules .sp Writing a cloud module based on libcloud has two major advantages. First of all, much of the work has already been done by the libcloud project. Second, most of the functions necessary to Salt have already been added to the Salt Cloud project. .SS The create() Function .sp The most important function that does need to be manually written is the \fBcreate()\fP function. This is what is used to request a virtual machine to be created by the cloud provider, wait for it to become available, and then (optionally) log in and install Salt on it. .sp A good example to follow for writing a cloud provider module based on libcloud is the module provided for Linode: .sp \fI\%https://github.com/saltstack/salt/blob/develop/salt/cloud/clouds/linode.py\fP .sp The basic flow of a \fBcreate()\fP function is as follows: .INDENT 0.0 .IP \(bu 2 Send a request to the cloud provider to create a virtual machine. .IP \(bu 2 Wait for the virtual machine to become available. .IP \(bu 2 Generate kwargs to be used to deploy Salt. .IP \(bu 2 Log into the virtual machine and deploy Salt. .IP \(bu 2 Return a data structure that describes the newly\-created virtual machine. .UNINDENT .sp At various points throughout this function, events may be fired on the Salt event bus. Four of these events, which are described below, are required. Other events may be added by the user, where appropriate. .sp When the \fBcreate()\fP function is called, it is passed a data structure called \fBvm_\fP\&. This dict contains a composite of information describing the virtual machine to be created. A dict called \fB__opts__\fP is also provided by Salt, which contains the options used to run Salt Cloud, as well as a set of configuration and environment variables. .sp The first thing the \fBcreate()\fP function must do is fire an event stating that it has started the create process. This event is tagged \fBsalt/cloud//creating\fP\&. The payload contains the names of the VM, profile and provider. .sp A set of kwargs is then usually created, to describe the parameters required by the cloud provider to request the virtual machine. .sp An event is then fired to state that a virtual machine is about to be requested. It is tagged as \fBsalt/cloud//requesting\fP\&. The payload contains most or all of the parameters that will be sent to the cloud provider. Any private information (such as passwords) should not be sent in the event. .sp After a request is made, a set of deploy kwargs will be generated. These will be used to install Salt on the target machine. Windows options are supported at this point, and should be generated, even if the cloud provider does not currently support Windows. This will save time in the future if the provider does eventually decide to support Windows. .sp An event is then fired to state that the deploy process is about to begin. This event is tagged \fBsalt/cloud//deploying\fP\&. The payload for the event will contain a set of deploy kwargs, useful for debugging purposed. Any private data, including passwords and keys (including public keys) should be stripped from the deploy kwargs before the event is fired. .sp If any Windows options have been passed in, the \fBsalt.utils.cloud.deploy_windows()\fP function will be called. Otherwise, it will be assumed that the target is a Linux or Unix machine, and the \fBsalt.utils.cloud.deploy_script()\fP will be called. .sp Both of these functions will wait for the target machine to become available, then the necessary port to log in, then a successful login that can be used to install Salt. Minion configuration and keys will then be uploaded to a temporary directory on the target by the appropriate function. On a Windows target, the Windows Minion Installer will be run in silent mode. On a Linux/Unix target, a deploy script (bootstrap\-salt.sh, by default) will be run, which will auto\-detect the operating system, and install Salt using its native package manager. These do not need to be handled by the developer in the cloud module. .sp After the appropriate deploy function completes, a final event is fired which describes the virtual machine that has just been created. This event is tagged \fBsalt/cloud//created\fP\&. The payload contains the names of the VM, profile and provider. .sp Finally, a dict (queried from the provider) which describes the new virtual machine is returned to the user. Because this data is not fired on the event bus it can, and should, return any passwords that were returned by the cloud provider. In some cases (for example, Rackspace), this is the only time that the password can be queried by the user; post\-creation queries may not contain password information (depending upon the provider). .SS The libcloudfuncs Functions .sp A number of other functions are required for all cloud providers. However, with libcloud\-based modules, these are all provided for free by the libcloudfuncs library. The following two lines set up the imports: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C from salt.cloud.libcloudfuncs import * # pylint: disable=W0614,W0401 from salt.utils import namespaced_function .ft P .fi .UNINDENT .UNINDENT .sp And then a series of declarations will make the necessary functions available within the cloud module. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C get_size = namespaced_function(get_size, globals()) get_image = namespaced_function(get_image, globals()) avail_locations = namespaced_function(avail_locations, globals()) avail_images = namespaced_function(avail_images, globals()) avail_sizes = namespaced_function(avail_sizes, globals()) script = namespaced_function(script, globals()) destroy = namespaced_function(destroy, globals()) list_nodes = namespaced_function(list_nodes, globals()) list_nodes_full = namespaced_function(list_nodes_full, globals()) list_nodes_select = namespaced_function(list_nodes_select, globals()) show_instance = namespaced_function(show_instance, globals()) .ft P .fi .UNINDENT .UNINDENT .sp If necessary, these functions may be replaced by removing the appropriate declaration line, and then adding the function as normal. .sp These functions are required for all cloud modules, and are described in detail in the next section. .SS Non\-Libcloud Based Modules .sp In some cases, using libcloud is not an option. This may be because libcloud has not yet included the necessary driver itself, or it may be that the driver that is included with libcloud does not contain all of the necessary features required by the developer. When this is the case, some or all of the functions in \fBlibcloudfuncs\fP may be replaced. If they are all replaced, the libcloud imports should be absent from the Salt Cloud module. .sp A good example of a non\-libcloud provider is the Digital Ocean module: .sp \fI\%https://github.com/saltstack/salt/blob/develop/salt/cloud/clouds/digital_ocean.py\fP .SS The \fBcreate()\fP Function .sp The \fBcreate()\fP function must be created as described in the libcloud\-based module documentation. .SS The get_size() Function .sp This function is only necessary for libcloud\-based modules, and does not need to exist otherwise. .SS The get_image() Function .sp This function is only necessary for libcloud\-based modules, and does not need to exist otherwise. .SS The avail_locations() Function .sp This function returns a list of locations available, if the cloud provider uses multiple data centers. It is not necessary if the cloud provider only uses one data center. It is normally called using the \fB\-\-list\-locations\fP option. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-\-list\-locations my\-cloud\-provider .ft P .fi .UNINDENT .UNINDENT .SS The avail_images() Function .sp This function returns a list of images available for this cloud provider. There are not currently any known cloud providers that do not provide this functionality, though they may refer to images by a different name (for example, "templates"). It is normally called using the \fB\-\-list\-images\fP option. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-\-list\-images my\-cloud\-provider .ft P .fi .UNINDENT .UNINDENT .SS The avail_sizes() Function .sp This function returns a list of sizes available for this cloud provider. Generally, this refers to a combination of RAM, CPU and/or disk space. This functionality may not be present on some cloud providers. For example, the Parallels module breaks down RAM, CPU and disk space into separate options, whereas in other providers, these options are baked into the image. It is normally called using the \fB\-\-list\-sizes\fP option. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-\-list\-sizes my\-cloud\-provider .ft P .fi .UNINDENT .UNINDENT .SS The script() Function .sp This function builds the deploy script to be used on the remote machine. It is likely to be moved into the \fBsalt.utils.cloud\fP library in the near future, as it is very generic and can usually be copied wholesale from another module. An excellent example is in the Azure driver. .SS The destroy() Function .sp This function irreversably destroys a virtual machine on the cloud provider. Before doing so, it should fire an event on the Salt event bus. The tag for this event is \fBsalt/cloud//destroying\fP\&. Once the virtual machine has been destroyed, another event is fired. The tag for that event is \fBsalt/cloud//destroyed\fP\&. .sp This function is normally called with the \fB\-d\fP options: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-d myinstance .ft P .fi .UNINDENT .UNINDENT .SS The list_nodes() Function .sp This function returns a list of nodes available on this cloud provider, using the following fields: .INDENT 0.0 .IP \(bu 2 id (str) .IP \(bu 2 image (str) .IP \(bu 2 size (str) .IP \(bu 2 state (str) .IP \(bu 2 private_ips (list) .IP \(bu 2 public_ips (list) .UNINDENT .sp No other fields should be returned in this function, and all of these fields should be returned, even if empty. The private_ips and public_ips fields should always be of a list type, even if empty, and the other fields should always be of a str type. This function is normally called with the \fB\-Q\fP option: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-Q .ft P .fi .UNINDENT .UNINDENT .SS The list_nodes_full() Function .sp All information available about all nodes should be returned in this function. The fields in the list_nodes() function should also be returned, even if they would not normally be provided by the cloud provider. This is because some functions both within Salt and 3rd party will break if an expected field is not present. This function is normally called with the \fB\-F\fP option: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-F .ft P .fi .UNINDENT .UNINDENT .SS The list_nodes_select() Function .sp This function returns only the fields specified in the \fBquery.selection\fP option in \fB/etc/salt/cloud\fP\&. Because this function is so generic, all of the heavy lifting has been moved into the \fBsalt.utils.cloud\fP library. .sp A function to call \fBlist_nodes_select()\fP still needs to be present. In general, the following code can be used as\-is: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C def list_nodes_select(call=None): \(aq\(aq\(aq Return a list of the VMs that are on the provider, with select fields \(aq\(aq\(aq return salt.utils.cloud.list_nodes_select( list_nodes_full(\(aqfunction\(aq), __opts__[\(aqquery.selection\(aq], call, ) .ft P .fi .UNINDENT .UNINDENT .sp However, depending on the cloud provider, additional variables may be required. For instance, some modules use a \fBconn\fP object, or may need to pass other options into \fBlist_nodes_full()\fP\&. In this case, be sure to update the function appropriately: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C def list_nodes_select(conn=None, call=None): \(aq\(aq\(aq Return a list of the VMs that are on the provider, with select fields \(aq\(aq\(aq if not conn: conn = get_conn() # pylint: disable=E0602 return salt.utils.cloud.list_nodes_select( list_nodes_full(conn, \(aqfunction\(aq), __opts__[\(aqquery.selection\(aq], call, ) .ft P .fi .UNINDENT .UNINDENT .sp This function is normally called with the \fB\-S\fP option: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-S .ft P .fi .UNINDENT .UNINDENT .SS The show_instance() Function .sp This function is used to display all of the information about a single node that is available from the cloud provider. The simplest way to provide this is usually to call \fBlist_nodes_full()\fP, and return just the data for the requested node. It is normally called as an action: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-a show_instance myinstance .ft P .fi .UNINDENT .UNINDENT .SS Actions and Functions .sp Extra functionality may be added to a cloud provider in the form of an \fB\-\-action\fP or a \fB\-\-function\fP\&. Actions are performed against a cloud instance/virtual machine, and functions are performed against a cloud provider. .SS Actions .sp Actions are calls that are performed against a specific instance or virtual machine. The \fBshow_instance\fP action should be available in all cloud modules. Actions are normally called with the \fB\-a\fP option: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-a show_instance myinstance .ft P .fi .UNINDENT .UNINDENT .sp Actions must accept a \fBname\fP as a first argument, may optionally support any number of kwargs as appropriate, and must accept an argument of \fBcall\fP, with a default of \fBNone\fP\&. .sp Before performing any other work, an action should normally verify that it has been called correctly. It may then perform the desired feature, and return useful information to the user. A basic action looks like: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C def show_instance(name, call=None): \(aq\(aq\(aq Show the details from EC2 concerning an AMI \(aq\(aq\(aq if call != \(aqaction\(aq: raise SaltCloudSystemExit( \(aqThe show_instance action must be called with \-a or \-\-action.\(aq ) return _get_node(name) .ft P .fi .UNINDENT .UNINDENT .sp Please note that generic kwargs, if used, are passed through to actions as \fBkwargs\fP and not \fB**kwargs\fP\&. An example of this is seen in the Functions section. .SS Functions .sp Functions are called that are performed against a specific cloud provider. An optional function that is often useful is \fBshow_image\fP, which describes an image in detail. Functions are normally called with the \fB\-f\fP option: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-f show_image my\-cloud\-provider image=\(aqUbuntu 13.10 64\-bit\(aq .ft P .fi .UNINDENT .UNINDENT .sp A function may accept any number of kwargs as appropriate, and must accept an argument of \fBcall\fP with a default of \fBNone\fP\&. .sp Before performing any other work, a function should normally verify that it has been called correctly. It may then perform the desired feature, and return useful information to the user. A basic function looks like: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C def show_image(kwargs, call=None): \(aq\(aq\(aq Show the details from EC2 concerning an AMI \(aq\(aq\(aq if call != \(aqfunction\(aq: raise SaltCloudSystemExit( \(aqThe show_image action must be called with \-f or \-\-function.\(aq ) params = {\(aqImageId.1\(aq: kwargs[\(aqimage\(aq], \(aqAction\(aq: \(aqDescribeImages\(aq} result = query(params) log.info(result) return result .ft P .fi .UNINDENT .UNINDENT .sp Take note that generic kwargs are passed through to functions as \fBkwargs\fP and not \fB**kwargs\fP\&. .SS Core Configuration .sp A number of core configuration options and some options that are global to the VM profiles can be set in the cloud configuration file. By default this file is located at \fB/etc/salt/cloud\fP\&. .SS Minion Configuration .sp The default minion configuration is set up in this file. This is where the minions that are created derive their configuration. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C minion: master: saltmaster.example.com .ft P .fi .UNINDENT .UNINDENT .sp This is the location in particular to specify the location of the salt master. .SS New Cloud Configuration Syntax .sp The data specific to interacting with public clouds is set up here. .sp \fBATTENTION\fP: Since version 0.8.7 a new cloud provider configuration syntax was implemented. It will allow for multiple configurations of the same cloud provider where only minor details can change, for example, the region for an EC2 instance. While the old format is still supported and automatically migrated every time salt\-cloud configuration is parsed, a choice was made to warn the user or even exit with an error if both formats are mixed. .SS Migrating Configurations .sp If you wish to migrate, there are several alternatives. Since the old syntax was mainly done on the main cloud configuration file, see the next before and after migration example. .INDENT 0.0 .IP \(bu 2 Before migration in \fB/etc/salt/cloud\fP: .UNINDENT .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C AWS.id: HJGRYCILJLKJYG AWS.key: \(aqkdjgfsgm;woormgl/aserigjksjdhasdfgn\(aq AWS.keyname: test AWS.securitygroup: quick\-start AWS.private_key: /root/test.pem .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .IP \(bu 2 After migration in \fB/etc/salt/cloud\fP: .UNINDENT .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C providers: my\-aws\-migrated\-config: id: HJGRYCILJLKJYG key: \(aqkdjgfsgm;woormgl/aserigjksjdhasdfgn\(aq keyname: test securitygroup: quick\-start private_key: /root/test.pem provider: aws .ft P .fi .UNINDENT .UNINDENT .sp Notice that it\(aqs not longer required to name a cloud provider\(aqs configuration after it\(aqs provider, it can be an alias, though, an additional configuration key is added, \fBprovider\fP\&. This allows for multiple configuration for the same cloud provider to coexist. .sp While moving towards an improved and extensible configuration handling regarding the cloud providers, \fB\-\-providers\-config\fP, which defaults to \fB/etc/salt/cloud.providers\fP, was added to the cli parser. It allows for the cloud providers configuration to be provided in a different file, and/or even any matching file on a sub\-directory, \fBcloud.providers.d/*.conf\fP which is relative to the providers configuration file(with the above configuration file as an example, \fB/etc/salt/cloud.providers.d/*.conf\fP). .sp So, using the example configuration above, after migration in \fB/etc/salt/cloud.providers\fP or \fB/etc/salt/cloud.providers.d/aws\-migrated.conf\fP: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C my\-aws\-migrated\-config: id: HJGRYCILJLKJYG key: \(aqkdjgfsgm;woormgl/aserigjksjdhasdfgn\(aq keyname: test securitygroup: quick\-start private_key: /root/test.pem provider: aws .ft P .fi .UNINDENT .UNINDENT .sp Notice that on this last migrated example, it \fBno longer\fP includes the \fBproviders\fP starting key. .sp While migrating the cloud providers configuration, if the provider alias(from the above example \fBmy\-aws\-migrated\-config\fP) changes from what you had(from the above example \fBaws\fP), you will also need to change the \fBprovider\fP configuration key in the defined profiles. .INDENT 0.0 .IP \(bu 2 From: .UNINDENT .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C rhel_aws: provider: aws image: ami\-e565ba8c size: Micro Instance .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .IP \(bu 2 To: .UNINDENT .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C rhel_aws: provider: my\-aws\-migrated\-config image: ami\-e565ba8c size: Micro Instance .ft P .fi .UNINDENT .UNINDENT .sp This new configuration syntax even allows you to have multiple cloud configurations under the same alias, for example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C production\-config: \- id: HJGRYCILJLKJYG key: \(aqkdjgfsgm;woormgl/aserigjksjdhasdfgn\(aq keyname: test securitygroup: quick\-start private_key: /root/test.pem \- user: example_user apikey: 123984bjjas87034 provider: rackspace .ft P .fi .UNINDENT .UNINDENT .sp \fBNotice the dash and indentation on the above example.\fP .sp Having multiple entries for a configuration alias also makes the \fBprovider\fP key on any defined profile to change, see the example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C rhel_aws_dev: provider: production\-config:aws image: ami\-e565ba8c size: Micro Instance rhel_aws_prod: provider: production\-config:aws image: ami\-e565ba8c size: High\-CPU Extra Large Instance database_prod: provider: production\-config:rackspace image: Ubuntu 12.04 LTS size: 256 server .ft P .fi .UNINDENT .UNINDENT .sp Notice that because of the multiple entries, one has to be explicit about the provider alias and name, from the above example, \fBproduction\-config:aws\fP\&. .sp This new syntax also changes the interaction with the \fBsalt\-cloud\fP binary. \fB\-\-list\-location\fP, \fB\-\-list\-images\fP and \fB\-\-list\-sizes\fP which needs a cloud provider as an argument. Since 0.8.7 the argument used should be the configured cloud provider alias. If the provider alias only as a single entry, use \fB\fP\&. If it has multiple entries, \fB:\fP should be used. .SS Cloud Configurations .SS Rackspace .sp Rackspace cloud requires two configuration options: .INDENT 0.0 .IP \(bu 2 Using the old format: .UNINDENT .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C RACKSPACE.user: example_user RACKSPACE.apikey: 123984bjjas87034 .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .IP \(bu 2 Using the new configuration format: .UNINDENT .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C my\-rackspace\-config: user: example_user apikey: 123984bjjas87034 provider: rackspace .ft P .fi .UNINDENT .UNINDENT .sp \fBNOTE\fP: With the new providers configuration syntax you would have \fBprovider: rackspace\-config\fP instead of \fBprovider: rackspace\fP on a profile configuration. .SS Amazon AWS .sp A number of configuration options are required for Amazon AWS: .INDENT 0.0 .IP \(bu 2 Using the old format: .UNINDENT .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C AWS.id: HJGRYCILJLKJYG AWS.key: \(aqkdjgfsgm;woormgl/aserigjksjdhasdfgn\(aq AWS.keyname: test AWS.securitygroup: quick\-start AWS.private_key: /root/test.pem .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .IP \(bu 2 Using the new configuration format: .UNINDENT .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C my\-aws\-quick\-start: id: HJGRYCILJLKJYG key: \(aqkdjgfsgm;woormgl/aserigjksjdhasdfgn\(aq keyname: test securitygroup: quick\-start private_key: /root/test.pem provider: aws my\-aws\-default: id: HJGRYCILJLKJYG key: \(aqkdjgfsgm;woormgl/aserigjksjdhasdfgn\(aq keyname: test securitygroup: default private_key: /root/test.pem provider: aws .ft P .fi .UNINDENT .UNINDENT .sp \fBNOTE\fP: With the new providers configuration syntax you would have \fBprovider: my\-aws\-quick\-start\fP or \fBprovider: my\-aws\-default\fP instead of \fBprovider: aws\fP on a profile configuration. .SS Linode .sp Linode requires a single API key, but the default root password also needs to be set: .INDENT 0.0 .IP \(bu 2 Using the old format: .UNINDENT .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C LINODE.apikey: asldkgfakl;sdfjsjaslfjaklsdjf;askldjfaaklsjdfhasldsadfghdkf LINODE.password: F00barbaz .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .IP \(bu 2 Using the new configuration format: .UNINDENT .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C my\-linode\-config: apikey: asldkgfakl;sdfjsjaslfjaklsdjf;askldjfaaklsjdfhasldsadfghdkf password: F00barbaz provider: linode .ft P .fi .UNINDENT .UNINDENT .sp \fBNOTE\fP: With the new providers configuration syntax you would have \fBprovider: my\-linode\-config\fP instead of \fBprovider: linode\fP on a profile configuration. .sp The password needs to be 8 characters and contain lowercase, uppercase and numbers. .SS Joyent Cloud .sp The Joyent cloud requires three configuration parameters. The user name and password that are used to log into the Joyent system, and the location of the private ssh key associated with the Joyent account. The ssh key is needed to send the provisioning commands up to the freshly created virtual machine, .INDENT 0.0 .IP \(bu 2 Using the old format: .UNINDENT .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C JOYENT.user: fred JOYENT.password: saltybacon JOYENT.private_key: /root/joyent.pem .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .IP \(bu 2 Using the new configuration format: .UNINDENT .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C my\-joyent\-config: user: fred password: saltybacon private_key: /root/joyent.pem provider: joyent .ft P .fi .UNINDENT .UNINDENT .sp \fBNOTE\fP: With the new providers configuration syntax you would have \fBprovider: my\-joyent\-config\fP instead of \fBprovider: joyent\fP on a profile configuration. .SS GoGrid .sp To use Salt Cloud with GoGrid log into the GoGrid web interface and create an API key. Do this by clicking on "My Account" and then going to the API Keys tab. .sp The GOGRID.apikey and the GOGRID.sharedsecret configuration parameters need to be set in the configuration file to enable interfacing with GoGrid: .INDENT 0.0 .IP \(bu 2 Using the old format: .UNINDENT .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C GOGRID.apikey: asdff7896asdh789 GOGRID.sharedsecret: saltybacon .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .IP \(bu 2 Using the new configuration format: .UNINDENT .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C my\-gogrid\-config: apikey: asdff7896asdh789 sharedsecret: saltybacon provider: gogrid .ft P .fi .UNINDENT .UNINDENT .sp \fBNOTE\fP: With the new providers configuration syntax you would have \fBprovider: my\-gogrid\-config\fP instead of \fBprovider: gogrid\fP on a profile configuration. .SS OpenStack .sp OpenStack configuration differs between providers, and at the moment several options need to be specified. This module has been officially tested against the HP and the Rackspace implementations, and some examples are provided for both. .INDENT 0.0 .IP \(bu 2 Using the old format: .UNINDENT .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C # For HP OPENSTACK.identity_url: \(aqhttps://region\-a.geo\-1.identity.hpcloudsvc.com:35357/v2.0/\(aq OPENSTACK.compute_name: Compute OPENSTACK.compute_region: \(aqaz\-1.region\-a.geo\-1\(aq OPENSTACK.tenant: myuser\-tenant1 OPENSTACK.user: myuser OPENSTACK.ssh_key_name: mykey OPENSTACK.ssh_key_file: \(aq/etc/salt/hpcloud/mykey.pem\(aq OPENSTACK.password: mypass # For Rackspace OPENSTACK.identity_url: \(aqhttps://identity.api.rackspacecloud.com/v2.0/tokens\(aq OPENSTACK.compute_name: cloudServersOpenStack OPENSTACK.protocol: ipv4 OPENSTACK.compute_region: DFW OPENSTACK.protocol: ipv4 OPENSTACK.user: myuser OPENSTACK.tenant: 5555555 OPENSTACK.password: mypass .ft P .fi .UNINDENT .UNINDENT .sp If you have an API key for your provider, it may be specified instead of a password: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C OPENSTACK.apikey: 901d3f579h23c8v73q9 .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .IP \(bu 2 Using the new configuration format: .UNINDENT .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C # For HP my\-openstack\-hp\-config: identity_url: \(aqhttps://region\-a.geo\-1.identity.hpcloudsvc.com:35357/v2.0/\(aq compute_name: Compute compute_region: \(aqaz\-1.region\-a.geo\-1\(aq tenant: myuser\-tenant1 user: myuser ssh_key_name: mykey ssh_key_file: \(aq/etc/salt/hpcloud/mykey.pem\(aq password: mypass provider: openstack # For Rackspace my\-openstack\-rackspace\-config: identity_url: \(aqhttps://identity.api.rackspacecloud.com/v2.0/tokens\(aq compute_name: cloudServersOpenStack protocol: ipv4 compute_region: DFW protocol: ipv4 user: myuser tenant: 5555555 password: mypass provider: openstack .ft P .fi .UNINDENT .UNINDENT .sp If you have an API key for your provider, it may be specified instead of a password: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C my\-openstack\-hp\-config: apikey: 901d3f579h23c8v73q9 my\-openstack\-rackspace\-config: apikey: 901d3f579h23c8v73q9 .ft P .fi .UNINDENT .UNINDENT .sp \fBNOTE\fP: With the new providers configuration syntax you would have \fBprovider: my\-openstack\-hp\-config\fP or \fBprovider: my\-openstack\-rackspace\-config\fP instead of \fBprovider: openstack\fP on a profile configuration. .sp You will certainly need to configure the \fBuser\fP, \fBtenant\fP and either \fBpassword\fP or \fBapikey\fP\&. .sp If your OpenStack instances only have private IP addresses and a CIDR range of private addresses are not reachable from the salt\-master, you may set your preference to have Salt ignore it. Using the old could configurations syntax: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C OPENSTACK.ignore_cidr: 192.168.0.0/16 .ft P .fi .UNINDENT .UNINDENT .sp Using the new syntax: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C my\-openstack\-config: ignore_cidr: 192.168.0.0/16 .ft P .fi .UNINDENT .UNINDENT .sp For in\-house Openstack Essex installation, libcloud needs the service_type : .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C my\-openstack\-config: identity_url: \(aqhttp://control.openstack.example.org:5000/v2.0/\(aq compute_name : Compute Service service_type : compute .ft P .fi .UNINDENT .UNINDENT .SS Digital Ocean .sp Using Salt for Digital Ocean requires a client_key and an api_key. These can be found in the Digital Ocean web interface, in the "My Settings" section, under the API Access tab. .INDENT 0.0 .IP \(bu 2 Using the old format: .UNINDENT .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C DIGITAL_OCEAN.client_key: wFGEwgregeqw3435gDger DIGITAL_OCEAN.api_key: GDE43t43REGTrkilg43934t34qT43t4dgegerGEgg .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .IP \(bu 2 Using the new configuration format: .UNINDENT .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C my\-digitalocean\-config: provider: digital_ocean client_key: wFGEwgregeqw3435gDger api_key: GDE43t43REGTrkilg43934t34qT43t4dgegerGEgg location: New York 1 .ft P .fi .UNINDENT .UNINDENT .sp \fBNOTE\fP: With the new providers configuration syntax you would have \fBprovider: my\-digitalocean\-config\fP instead of \fBprovider: digital_ocean\fP on a profile configuration. .SS Parallels .sp Using Salt with Parallels requires a user, password and url. These can be obtained from your cloud provider. .INDENT 0.0 .IP \(bu 2 Using the old format: .UNINDENT .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C PARALLELS.user: myuser PARALLELS.password: xyzzy PARALLELS.url: https://api.cloud.xmission.com:4465/paci/v1.0/ .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .IP \(bu 2 Using the new configuration format: .UNINDENT .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C my\-parallels\-config: user: myuser password: xyzzy url: https://api.cloud.xmission.com:4465/paci/v1.0/ provider: parallels .ft P .fi .UNINDENT .UNINDENT .sp \fBNOTE\fP: With the new providers configuration syntax you would have \fBprovider: my\-parallels\-config\fP instead of \fBprovider: parallels\fP on a profile configuration. .SS IBM SmartCloud Enterprise .sp In addition to a username and password, the IBM SCE module requires an SSH key, which is currently configured inside IBM\(aqs web interface. A location is also required to create instances, but not to query their cloud. This is important, because you need to use salt\-cloud \-\-list\-locations (with the other options already set) in order to find the name of the location that you want to use. .INDENT 0.0 .IP \(bu 2 Using the old format: .UNINDENT .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C IBMSCE.user: myuser@mycorp.com IBMSCE.password: mypass IBMSCE.ssh_key_name: mykey IBMSCE.ssh_key_file: \(aq/etc/salt/ibm/mykey.pem\(aq IBMSCE.location: Raleigh .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .IP \(bu 2 Using the new configuration format: .UNINDENT .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C my\-ibmsce\-config: user: myuser@mycorp.com password: mypass ssh_key_name: mykey ssh_key_file: \(aq/etc/salt/ibm/mykey.pem\(aq location: Raleigh provider: ibmsce .ft P .fi .UNINDENT .UNINDENT .sp \fBNOTE\fP: With the new providers configuration syntax you would have \fBprovider: my\-imbsce\-config\fP instead of \fBprovider: ibmsce\fP on a profile configuration. .SS Saltify .sp The Saltify driver is a new, experimental driver for installing Salt on existing machines (virtual or bare metal). Because it does not use an actual cloud provider, it needs no configuration in the main cloud config file. However, it does still require a profile to be set up, and is most useful when used inside a map file. The key parameters to be set are \fBssh_host\fP, \fBssh_username\fP and either \fBssh_keyfile\fP or \fBssh_password\fP\&. These may all be set in either the profile or the map. An example configuration might use the following in cloud.profiles: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C make_salty: provider: saltify .ft P .fi .UNINDENT .UNINDENT .sp And in the map file: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C make_salty: \- myinstance: ssh_host: 54.262.11.38 ssh_username: ubuntu ssh_keyfile: \(aq/etc/salt/mysshkey.pem\(aq sudo: True .ft P .fi .UNINDENT .UNINDENT .SS Extending Profiles and Cloud Providers Configuration .sp As of 0.8.7, the option to extend both the profiles and cloud providers configuration and avoid duplication was added. The extends feature works on the current profiles configuration, but, regarding the cloud providers configuration, \fBonly\fP works in the new syntax and respective configuration files, ie, \fB/etc/salt/salt/cloud.providers\fP or \fB/etc/salt/cloud.providers.d/*.conf\fP\&. .SS Extending Profiles .sp Some example usage on how to use \fBextends\fP with profiles. Consider \fB/etc/salt/salt/cloud.profiles\fP containing: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C development\-instances: provider: my\-ec2\-config size: Micro Instance ssh_username: ec2_user securitygroup: \- default deploy: False Amazon\-Linux\-AMI\-2012.09\-64bit: image: ami\-54cf5c3d extends: development\-instances Fedora\-17: image: ami\-08d97e61 extends: development\-instances CentOS\-5: provider: my\-aws\-config image: ami\-09b61d60 extends: development\-instances .ft P .fi .UNINDENT .UNINDENT .sp The above configuration, once parsed would generate the following profiles data: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C [{\(aqdeploy\(aq: False, \(aqimage\(aq: \(aqami\-08d97e61\(aq, \(aqprofile\(aq: \(aqFedora\-17\(aq, \(aqprovider\(aq: \(aqmy\-ec2\-config\(aq, \(aqsecuritygroup\(aq: [\(aqdefault\(aq], \(aqsize\(aq: \(aqMicro Instance\(aq, \(aqssh_username\(aq: \(aqec2_user\(aq}, {\(aqdeploy\(aq: False, \(aqimage\(aq: \(aqami\-09b61d60\(aq, \(aqprofile\(aq: \(aqCentOS\-5\(aq, \(aqprovider\(aq: \(aqmy\-aws\-config\(aq, \(aqsecuritygroup\(aq: [\(aqdefault\(aq], \(aqsize\(aq: \(aqMicro Instance\(aq, \(aqssh_username\(aq: \(aqec2_user\(aq}, {\(aqdeploy\(aq: False, \(aqimage\(aq: \(aqami\-54cf5c3d\(aq, \(aqprofile\(aq: \(aqAmazon\-Linux\-AMI\-2012.09\-64bit\(aq, \(aqprovider\(aq: \(aqmy\-ec2\-config\(aq, \(aqsecuritygroup\(aq: [\(aqdefault\(aq], \(aqsize\(aq: \(aqMicro Instance\(aq, \(aqssh_username\(aq: \(aqec2_user\(aq}, {\(aqdeploy\(aq: False, \(aqprofile\(aq: \(aqdevelopment\-instances\(aq, \(aqprovider\(aq: \(aqmy\-ec2\-config\(aq, \(aqsecuritygroup\(aq: [\(aqdefault\(aq], \(aqsize\(aq: \(aqMicro Instance\(aq, \(aqssh_username\(aq: \(aqec2_user\(aq}] .ft P .fi .UNINDENT .UNINDENT .sp Pretty cool right? .SS Extending Providers .sp Some example usage on how to use \fBextends\fP within the cloud providers configuration. Consider \fB/etc/salt/salt/cloud.providers\fP containing: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C my\-develop\-envs: \- id: HJGRYCILJLKJYG key: \(aqkdjgfsgm;woormgl/aserigjksjdhasdfgn\(aq keyname: test securitygroup: quick\-start private_key: /root/test.pem location: ap\-southeast\-1 availability_zone: ap\-southeast\-1b provider: aws \- user: myuser@mycorp.com password: mypass ssh_key_name: mykey ssh_key_file: \(aq/etc/salt/ibm/mykey.pem\(aq location: Raleigh provider: ibmsce my\-productions\-envs: \- extends: my\-develop\-envs:ibmsce user: my\-production\-user@mycorp.com location: us\-east\-1 availability_zone: us\-east\-1 .ft P .fi .UNINDENT .UNINDENT .sp The above configuration, once parsed would generate the following providers data: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C \(aqproviders\(aq: { \(aqmy\-develop\-envs\(aq: [ {\(aqavailability_zone\(aq: \(aqap\-southeast\-1b\(aq, \(aqid\(aq: \(aqHJGRYCILJLKJYG\(aq, \(aqkey\(aq: \(aqkdjgfsgm;woormgl/aserigjksjdhasdfgn\(aq, \(aqkeyname\(aq: \(aqtest\(aq, \(aqlocation\(aq: \(aqap\-southeast\-1\(aq, \(aqprivate_key\(aq: \(aq/root/test.pem\(aq, \(aqprovider\(aq: \(aqaws\(aq, \(aqsecuritygroup\(aq: \(aqquick\-start\(aq }, {\(aqlocation\(aq: \(aqRaleigh\(aq, \(aqpassword\(aq: \(aqmypass\(aq, \(aqprovider\(aq: \(aqibmsce\(aq, \(aqssh_key_file\(aq: \(aq/etc/salt/ibm/mykey.pem\(aq, \(aqssh_key_name\(aq: \(aqmykey\(aq, \(aquser\(aq: \(aqmyuser@mycorp.com\(aq } ], \(aqmy\-productions\-envs\(aq: [ {\(aqavailability_zone\(aq: \(aqus\-east\-1\(aq, \(aqlocation\(aq: \(aqus\-east\-1\(aq, \(aqpassword\(aq: \(aqmypass\(aq, \(aqprovider\(aq: \(aqibmsce\(aq, \(aqssh_key_file\(aq: \(aq/etc/salt/ibm/mykey.pem\(aq, \(aqssh_key_name\(aq: \(aqmykey\(aq, \(aquser\(aq: \(aqmy\-production\-user@mycorp.com\(aq } ] } .ft P .fi .UNINDENT .UNINDENT .SS OS Support for Cloud VMs .sp Salt Cloud works primarily by executing a script on the virtual machines as soon as they become available. The script that is executed is referenced in the cloud profile as the \fBscript\fP\&. In older versions, this was the \fBos\fP argument. This was changed in 0.8.2. .sp A number of legacy scripts exist in the deploy directory in the saltcloud source tree. The preferred method is currently to use the salt\-bootstrap script. A stable version is included with each release tarball starting with 0.8.4. The most updated version can be found at: .sp \fI\%https://github.com/saltstack/salt\-bootstrap\fP .sp If you do not specify a script argument, this script will be used at the default. .sp If the Salt Bootstrap script does not meet your needs, you may write your own. The script should be written in bash and is a Jinja template. Deploy scripts need to execute a number of functions to do a complete salt setup. These functions include: .INDENT 0.0 .IP 1. 3 Install the salt minion. If this can be done via system packages this method is HIGHLY preferred. .IP 2. 3 Add the salt minion keys before the minion is started for the first time. The minion keys are available as strings that can be copied into place in the Jinja template under the dict named "vm". .IP 3. 3 Start the salt\-minion daemon and enable it at startup time. .IP 4. 3 Set up the minion configuration file from the "minion" data available in the Jinja template. .UNINDENT .sp A good, well commented, example of this process is the Fedora deployment script: .sp \fI\%https://github.com/saltstack/salt\-cloud/blob/master/saltcloud/deploy/Fedora.sh\fP .sp A number of legacy deploy scripts are included with the release tarball. None of them are as functional or complete as Salt Bootstrap, and are still included for academic purposes. .SS Other Generic Deploy Scripts .sp If you want to be assured of always using the latest Salt Bootstrap script, there are a few generic templates available in the deploy directory of your saltcloud source tree: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C curl\-bootstrap curl\-bootstrap\-git python\-bootstrap wget\-bootstrap wget\-bootstrap\-git .ft P .fi .UNINDENT .UNINDENT .sp These are example scripts which were designed to be customized, adapted, and refit to meet your needs. One important use of them is to pass options to the salt\-bootstrap script, such as updating to specific git tags. .SS Post\-Deploy Commands .sp Once a minion has been deployed, it has the option to run a salt command. Normally, this would be the state.highstate command, which would finish provisioning the VM. Another common option is state.sls, or for just testing, test.ping. This is configured in the main cloud config file: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C start_action: state.highstate .ft P .fi .UNINDENT .UNINDENT .sp This is currently considered to be experimental functionality, and may not work well with all providers. If you experience problems with Salt Cloud hanging after Salt is deployed, consider using Startup States instead: .sp \fI\%http://docs.saltstack.org/en/latest/ref/states/startup.html\fP .SS Skipping the Deploy Script .sp For whatever reason, you may want to skip the deploy script altogether. This results in a VM being spun up much faster, with absolutely no configuration. This can be set from the command line: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-\-no\-deploy \-p micro_aws my_instance .ft P .fi .UNINDENT .UNINDENT .sp Or it can be set from the main cloud config file: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C deploy: False .ft P .fi .UNINDENT .UNINDENT .sp Or it can be set from the provider\(aqs configuration: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C RACKSPACE.user: example_user RACKSPACE.apikey: 123984bjjas87034 RACKSPACE.deploy: False .ft P .fi .UNINDENT .UNINDENT .sp Or even on the VM\(aqs profile settings: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C ubuntu_aws: provider: aws image: ami\-7e2da54e size: Micro Instance deploy: False .ft P .fi .UNINDENT .UNINDENT .sp The default for deploy is True. .sp In the profile, you may also set the script option to \fBNone\fP: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C script: None .ft P .fi .UNINDENT .UNINDENT .sp This is the slowest option, since it still uploads the None deploy script and executes it. .SS Updating Salt Bootstrap .sp Salt Bootstrap can be updated automatically with salt\-cloud: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-u salt\-cloud \-\-update\-bootstrap .ft P .fi .UNINDENT .UNINDENT .sp Bear in mind that this updates to the latest (unstable) version, so use with caution. .SS Keeping /tmp/ Files .sp When Salt Cloud deploys an instance, it uploads temporary files to /tmp/ for salt\-bootstrap to put in place. After the script has run, they are deleted. To keep these files around (mostly for debugging purposes), the \-\-keep\-tmp option can be added: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-p myprofile mymachine \-\-keep\-tmp .ft P .fi .UNINDENT .UNINDENT .sp For those wondering why /tmp/ was used instead of /root/, this had to be done for images which require the use of sudo, and therefore do not allow remote root logins, even for file transfers (which makes /root/ unavailable). .SS Deploy Script Arguments .sp Custom deploy scripts are unlikely to need custom arguments to be passed to them, but salt\-bootstrap has been extended quite a bit, and this may be necessary. script_args can be specified in either the profile or the map file, to pass arguments to the deploy script: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C aws\-amazon: provider: aws image: ami\-1624987f size: Micro Instance ssh_username: ec2\-user script: bootstrap\-salt script_args: \-c /tmp/ .ft P .fi .UNINDENT .UNINDENT .sp This has also been tested to work with pipes, if needed: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C script_args: | head .ft P .fi .UNINDENT .UNINDENT .SS Getting Started With Digital Ocean .sp Digital Ocean is a public cloud provider that specializes in Linux instances. .SS Dependencies .sp The Digital Ocean driver requires no special dependencies outside of Salt. .SS Configuration .sp Using Salt for Digital Ocean requires a client_key and an api_key. These can be found in the Digital Ocean web interface, in the "My Settings" section, under the API Access tab. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C # Note: This example is for /etc/salt/cloud.providers or any file in the # /etc/salt/cloud.providers.d/ directory. my\-digitalocean\-config: provider: digital_ocean client_key: wFGEwgregeqw3435gDger api_key: GDE43t43REGTrkilg43934t34qT43t4dgegerGEgg location: New York 1 .ft P .fi .UNINDENT .UNINDENT .SS Profiles .SS Cloud Profiles .sp Set up an initial profile at \fB/etc/salt/cloud.profiles\fP or in the \fB/etc/salt/cloud.profiles.d/\fP directory: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C digitalocean\-ubuntu: provider: my\-digitalocean\-config image: Ubuntu 12.10 x64 size: 512MB location: New York 1 .ft P .fi .UNINDENT .UNINDENT .sp Sizes can be obtained using the \fB\-\-list\-sizes\fP option for the \fBsalt\-cloud\fP command: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C # salt\-cloud \-\-list\-sizes my\-digitalocean\-config my\-digitalocean\-config: \-\-\-\-\-\-\-\-\-\- digital_ocean: \-\-\-\-\-\-\-\-\-\- 512MB: \-\-\-\-\-\-\-\-\-\- cost_per_hour: 0.00744 cost_per_month: 5.0 cpu: 1 disk: 20 id: 66 memory: 512 name: 512MB slug: None \&...SNIP... .ft P .fi .UNINDENT .UNINDENT .sp Images can be obtained using the \fB\-\-list\-images\fP option for the \fBsalt\-cloud\fP command: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C # salt\-cloud \-\-list\-images my\-digitalocean\-config my\-digitalocean\-config: \-\-\-\-\-\-\-\-\-\- digital_ocean: \-\-\-\-\-\-\-\-\-\- Arch Linux 2013.05 x64: \-\-\-\-\-\-\-\-\-\- distribution: Arch Linux id: 350424 name: Arch Linux 2013.05 x64 public: True slug: None \&...SNIP... .ft P .fi .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 DigitalOcean\(aqs concept of \fBApplications\fP is nothing more than a pre\-configured instance (same as a normal Droplet). You will find examples such \fBDocker 0.7 Ubuntu 13.04 x64\fP and \fBWordpress on Ubuntu 12.10\fP when using the \fB\-\-list\-images\fP option. These names can be used just like the rest of the standard instances when specifying an image in the cloud profile configuration. .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 Additional documentation is available from \fI\%Digital Ocean\fP\&. .UNINDENT .UNINDENT .SS Feature Matrix .sp A number of features are available in most cloud providers, but not all are available everywhere. This may be because the feature isn\(aqt supported by the cloud provider itself, or it may only be that the feature has not yet been added to Salt Cloud. In a handful of cases, it is because the feature does not make sense for a particular cloud provider (Saltify, for instance). .sp This matrix shows which features are available in which cloud providers, as far as Salt Cloud is concerned. This is not a comprehensive list of all features available in all cloud providers, and shoult not be used to make business decisions concerning choosing a cloud provider. In most cases, adding support for a feature to Salt Cloud requires only a little effort. .SS Legacy Drivers .sp Both AWS and Rackspace are listed as "Legacy". This is because those drivers have been replaced by other drivers, which are generally the prerferred method for working with those providers. .sp The EC2 driver should be used instead of the AWS driver, when possible. The OpenStack driver should be used instead of the Rackspace driver, unless the user is dealing with instances in "the old cloud" in Rackspace. .SS Note for Developers .sp When adding new features to a particular cloud provider, please make sure to add the feature to this table. Additionally, if you notice a feature that is not properly listed here, pull requests to fix them is appreciated. .SS Standard Features .sp These are features that are available for almost every provider. .TS center; |l|l|l|l|l|l|l|l|l|l|l|l|l|l|l|. _ T{ T} T{ AWS (Legacy) T} T{ CloudStack T} T{ Digital Ocean T} T{ EC2 T} T{ GoGrid T} T{ IBM SCE T} T{ JoyEnt T} T{ Linode T} T{ OpenStack T} T{ Parallels T} T{ Rackspace (Legacy) T} T{ Saltify T} T{ Softlayer T} T{ Softlayer Hardware T} _ T{ Query T} T{ Yes T} T{ Yes T} T{ Yes T} T{ Yes T} T{ Yes T} T{ Yes T} T{ Yes T} T{ Yes T} T{ Yes T} T{ Yes T} T{ Yes T} T{ T} T{ Yes T} T{ Yes T} _ T{ Full Query T} T{ Yes T} T{ Yes T} T{ Yes T} T{ Yes T} T{ Yes T} T{ Yes T} T{ Yes T} T{ Yes T} T{ Yes T} T{ Yes T} T{ Yes T} T{ T} T{ Yes T} T{ Yes T} _ T{ Selective Query T} T{ Yes T} T{ Yes T} T{ Yes T} T{ Yes T} T{ Yes T} T{ Yes T} T{ Yes T} T{ Yes T} T{ Yes T} T{ Yes T} T{ Yes T} T{ T} T{ Yes T} T{ Yes T} _ T{ List Sizes T} T{ Yes T} T{ Yes T} T{ Yes T} T{ Yes T} T{ Yes T} T{ Yes T} T{ Yes T} T{ Yes T} T{ Yes T} T{ Yes T} T{ Yes T} T{ T} T{ Yes T} T{ Yes T} _ T{ List Images T} T{ Yes T} T{ Yes T} T{ Yes T} T{ Yes T} T{ Yes T} T{ Yes T} T{ Yes T} T{ Yes T} T{ Yes T} T{ Yes T} T{ Yes T} T{ T} T{ Yes T} T{ Yes T} _ T{ List Locations T} T{ Yes T} T{ Yes T} T{ Yes T} T{ Yes T} T{ Yes T} T{ Yes T} T{ Yes T} T{ Yes T} T{ Yes T} T{ Yes T} T{ Yes T} T{ T} T{ Yes T} T{ Yes T} _ T{ create T} T{ Yes T} T{ Yes T} T{ Yes T} T{ Yes T} T{ Yes T} T{ Yes T} T{ Yes T} T{ Yes T} T{ Yes T} T{ Yes T} T{ Yes T} T{ Yes T} T{ Yes T} T{ Yes T} _ T{ destroy T} T{ Yes T} T{ Yes T} T{ Yes T} T{ Yes T} T{ Yes T} T{ Yes T} T{ Yes T} T{ Yes T} T{ Yes T} T{ Yes T} T{ Yes T} T{ T} T{ Yes T} T{ Yes T} _ .TE .SS Actions .sp These are features that are performed on a specific instance, and require an instance name to be passed in. For example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C # salt\-cloud \-a attach_volume ami.example.com .ft P .fi .UNINDENT .UNINDENT .TS center; |l|l|l|l|l|l|l|l|l|l|l|l|l|l|l|. _ T{ Actions T} T{ AWS (Legacy) T} T{ CloudStack T} T{ Digital Ocean T} T{ EC2 T} T{ GoGrid T} T{ IBM SCE T} T{ JoyEnt T} T{ Linode T} T{ OpenStack T} T{ Parallels T} T{ Rackspace (Legacy) T} T{ Saltify T} T{ Softlayer T} T{ Softlayer Hardware T} _ T{ attach_volume T} T{ T} T{ T} T{ T} T{ Yes T} T{ T} T{ T} T{ T} T{ T} T{ T} T{ T} T{ T} T{ T} T{ T} T{ T} _ T{ create_attach_volumes T} T{ Yes T} T{ T} T{ T} T{ Yes T} T{ T} T{ T} T{ T} T{ T} T{ T} T{ T} T{ T} T{ T} T{ T} T{ T} _ T{ del_tags T} T{ Yes T} T{ T} T{ T} T{ Yes T} T{ T} T{ T} T{ T} T{ T} T{ T} T{ T} T{ T} T{ T} T{ T} T{ T} _ T{ delvol_on_destroy T} T{ T} T{ T} T{ T} T{ Yes T} T{ T} T{ T} T{ T} T{ T} T{ T} T{ T} T{ T} T{ T} T{ T} T{ T} _ T{ detach_volume T} T{ T} T{ T} T{ T} T{ Yes T} T{ T} T{ T} T{ T} T{ T} T{ T} T{ T} T{ T} T{ T} T{ T} T{ T} _ T{ disable_term_protect T} T{ Yes T} T{ T} T{ T} T{ Yes T} T{ T} T{ T} T{ T} T{ T} T{ T} T{ T} T{ T} T{ T} T{ T} T{ T} _ T{ enable_term_protect T} T{ Yes T} T{ T} T{ T} T{ Yes T} T{ T} T{ T} T{ T} T{ T} T{ T} T{ T} T{ T} T{ T} T{ T} T{ T} _ T{ get_tags T} T{ Yes T} T{ T} T{ T} T{ Yes T} T{ T} T{ T} T{ T} T{ T} T{ T} T{ T} T{ T} T{ T} T{ T} T{ T} _ T{ keepvol_on_destroy T} T{ T} T{ T} T{ T} T{ Yes T} T{ T} T{ T} T{ T} T{ T} T{ T} T{ T} T{ T} T{ T} T{ T} T{ T} _ T{ list_keypairs T} T{ T} T{ T} T{ Yes T} T{ T} T{ T} T{ T} T{ T} T{ T} T{ T} T{ T} T{ T} T{ T} T{ T} T{ T} _ T{ rename T} T{ Yes T} T{ T} T{ T} T{ Yes T} T{ T} T{ T} T{ T} T{ T} T{ T} T{ T} T{ T} T{ T} T{ T} T{ T} _ T{ set_tags T} T{ Yes T} T{ T} T{ T} T{ Yes T} T{ T} T{ T} T{ T} T{ T} T{ T} T{ T} T{ T} T{ T} T{ T} T{ T} _ T{ show_delvol_on_destroy T} T{ T} T{ T} T{ T} T{ Yes T} T{ T} T{ T} T{ T} T{ T} T{ T} T{ T} T{ T} T{ T} T{ T} T{ T} _ T{ show_instance T} T{ T} T{ T} T{ Yes T} T{ Yes T} T{ T} T{ T} T{ T} T{ T} T{ T} T{ Yes T} T{ T} T{ T} T{ Yes T} T{ Yes T} _ T{ show_term_protect T} T{ T} T{ T} T{ T} T{ Yes T} T{ T} T{ T} T{ T} T{ T} T{ T} T{ T} T{ T} T{ T} T{ T} T{ T} _ T{ start T} T{ Yes T} T{ T} T{ T} T{ Yes T} T{ T} T{ T} T{ Yes T} T{ T} T{ T} T{ Yes T} T{ T} T{ T} T{ T} T{ T} _ T{ stop T} T{ Yes T} T{ T} T{ T} T{ Yes T} T{ T} T{ T} T{ Yes T} T{ T} T{ T} T{ Yes T} T{ T} T{ T} T{ T} T{ T} _ T{ take_action T} T{ T} T{ T} T{ T} T{ T} T{ T} T{ T} T{ Yes T} T{ T} T{ T} T{ T} T{ T} T{ T} T{ T} T{ T} _ .TE .SS Functions .sp These are features that are performed against a specific cloud provider, and require the name of the provider to be passed in. For example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C # salt\-cloud \-f list_images my_digitalocean .ft P .fi .UNINDENT .UNINDENT .TS center; |l|l|l|l|l|l|l|l|l|l|l|l|l|l|l|. _ T{ Functions T} T{ AWS (Legacy) T} T{ CloudStack T} T{ Digital Ocean T} T{ EC2 T} T{ GoGrid T} T{ IBM SCE T} T{ JoyEnt T} T{ Linode T} T{ OpenStack T} T{ Parallels T} T{ Rackspace (Legacy) T} T{ Saltify T} T{ Softlayer T} T{ Softlayer Hardware T} _ T{ block_device_mappings T} T{ Yes T} T{ T} T{ T} T{ T} T{ T} T{ T} T{ T} T{ T} T{ T} T{ T} T{ T} T{ T} T{ T} T{ T} _ T{ create_keypair T} T{ T} T{ T} T{ T} T{ Yes T} T{ T} T{ T} T{ T} T{ T} T{ T} T{ T} T{ T} T{ T} T{ T} T{ T} _ T{ create_volume T} T{ T} T{ T} T{ T} T{ Yes T} T{ T} T{ T} T{ T} T{ T} T{ T} T{ T} T{ T} T{ T} T{ T} T{ T} _ T{ delete_key T} T{ T} T{ T} T{ T} T{ T} T{ T} T{ T} T{ Yes T} T{ T} T{ T} T{ T} T{ T} T{ T} T{ T} T{ T} _ T{ delete_keypair T} T{ T} T{ T} T{ T} T{ Yes T} T{ T} T{ T} T{ T} T{ T} T{ T} T{ T} T{ T} T{ T} T{ T} T{ T} _ T{ delete_volume T} T{ T} T{ T} T{ T} T{ Yes T} T{ T} T{ T} T{ T} T{ T} T{ T} T{ T} T{ T} T{ T} T{ T} T{ T} _ T{ get_image T} T{ T} T{ T} T{ Yes T} T{ T} T{ T} T{ T} T{ Yes T} T{ T} T{ T} T{ Yes T} T{ T} T{ T} T{ T} T{ T} _ T{ get_ip T} T{ T} T{ Yes T} T{ T} T{ T} T{ T} T{ T} T{ T} T{ T} T{ T} T{ T} T{ T} T{ T} T{ T} T{ T} _ T{ get_key T} T{ T} T{ Yes T} T{ T} T{ T} T{ T} T{ T} T{ T} T{ T} T{ T} T{ T} T{ T} T{ T} T{ T} T{ T} _ T{ get_keyid T} T{ T} T{ T} T{ Yes T} T{ T} T{ T} T{ T} T{ T} T{ T} T{ T} T{ T} T{ T} T{ T} T{ T} T{ T} _ T{ get_keypair T} T{ T} T{ Yes T} T{ T} T{ T} T{ T} T{ T} T{ T} T{ T} T{ T} T{ T} T{ T} T{ T} T{ T} T{ T} _ T{ get_networkid T} T{ T} T{ Yes T} T{ T} T{ T} T{ T} T{ T} T{ T} T{ T} T{ T} T{ T} T{ T} T{ T} T{ T} T{ T} _ T{ get_node T} T{ T} T{ T} T{ T} T{ T} T{ T} T{ T} T{ Yes T} T{ T} T{ T} T{ T} T{ T} T{ T} T{ T} T{ T} _ T{ get_password T} T{ T} T{ Yes T} T{ T} T{ T} T{ T} T{ T} T{ T} T{ T} T{ T} T{ T} T{ T} T{ T} T{ T} T{ T} _ T{ get_size T} T{ T} T{ T} T{ Yes T} T{ T} T{ T} T{ T} T{ Yes T} T{ T} T{ T} T{ T} T{ T} T{ T} T{ T} T{ T} _ T{ get_spot_config T} T{ T} T{ T} T{ T} T{ Yes T} T{ T} T{ T} T{ T} T{ T} T{ T} T{ T} T{ T} T{ T} T{ T} T{ T} _ T{ get_subnetid T} T{ T} T{ T} T{ T} T{ Yes T} T{ T} T{ T} T{ T} T{ T} T{ T} T{ T} T{ T} T{ T} T{ T} T{ T} _ T{ iam_profile T} T{ Yes T} T{ T} T{ T} T{ Yes T} T{ T} T{ T} T{ T} T{ T} T{ T} T{ T} T{ T} T{ T} T{ T} T{ T} _ T{ import_key T} T{ T} T{ T} T{ T} T{ T} T{ T} T{ T} T{ Yes T} T{ T} T{ T} T{ T} T{ T} T{ T} T{ T} T{ T} _ T{ key_list T} T{ T} T{ T} T{ T} T{ T} T{ T} T{ T} T{ Yes T} T{ T} T{ T} T{ T} T{ T} T{ T} T{ T} T{ T} _ T{ keyname T} T{ Yes T} T{ T} T{ T} T{ Yes T} T{ T} T{ T} T{ T} T{ T} T{ T} T{ T} T{ T} T{ T} T{ T} T{ T} _ T{ list_availability_zones T} T{ T} T{ T} T{ T} T{ Yes T} T{ T} T{ T} T{ T} T{ T} T{ T} T{ T} T{ T} T{ T} T{ T} T{ T} _ T{ list_custom_images T} T{ T} T{ T} T{ T} T{ T} T{ T} T{ T} T{ T} T{ T} T{ T} T{ T} T{ T} T{ T} T{ Yes T} T{ T} _ T{ list_keys T} T{ T} T{ T} T{ T} T{ T} T{ T} T{ T} T{ Yes T} T{ T} T{ T} T{ T} T{ T} T{ T} T{ T} T{ T} _ T{ list_vlans T} T{ T} T{ T} T{ T} T{ T} T{ T} T{ T} T{ T} T{ T} T{ T} T{ T} T{ T} T{ T} T{ Yes T} T{ Yes T} _ T{ rackconnect T} T{ T} T{ T} T{ T} T{ T} T{ T} T{ T} T{ T} T{ T} T{ Yes T} T{ T} T{ T} T{ T} T{ T} T{ T} _ T{ reboot T} T{ T} T{ T} T{ T} T{ Yes T} T{ T} T{ T} T{ Yes T} T{ T} T{ T} T{ T} T{ T} T{ T} T{ T} T{ T} _ T{ reformat_node T} T{ T} T{ T} T{ T} T{ T} T{ T} T{ T} T{ Yes T} T{ T} T{ T} T{ T} T{ T} T{ T} T{ T} T{ T} _ T{ securitygroup T} T{ Yes T} T{ T} T{ T} T{ Yes T} T{ T} T{ T} T{ T} T{ T} T{ T} T{ T} T{ T} T{ T} T{ T} T{ T} _ T{ securitygroupid T} T{ T} T{ T} T{ T} T{ Yes T} T{ T} T{ T} T{ T} T{ T} T{ T} T{ T} T{ T} T{ T} T{ T} T{ T} _ T{ show_image T} T{ T} T{ T} T{ T} T{ Yes T} T{ T} T{ T} T{ T} T{ T} T{ T} T{ Yes T} T{ T} T{ T} T{ T} T{ T} _ T{ show_key T} T{ T} T{ T} T{ T} T{ T} T{ T} T{ T} T{ Yes T} T{ T} T{ T} T{ T} T{ T} T{ T} T{ T} T{ T} _ T{ show_keypair T} T{ T} T{ T} T{ Yes T} T{ Yes T} T{ T} T{ T} T{ T} T{ T} T{ T} T{ T} T{ T} T{ T} T{ T} T{ T} _ T{ show_volume T} T{ T} T{ T} T{ T} T{ Yes T} T{ T} T{ T} T{ T} T{ T} T{ T} T{ T} T{ T} T{ T} T{ T} T{ T} _ .TE .SS Cloud Functions .sp Cloud functions work much the same way as cloud actions, except that they don\(aqt perform an operation on a specific instance, and so do not need a machine name to be specified. However, since they perform an operation on a specific cloud provider, that provider must be specified. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C $ salt\-cloud \-f show_image ec2 image=ami\-fd20ad94 .ft P .fi .UNINDENT .UNINDENT .SS Getting Started With Google Compute Engine .sp Google Compute Engine (GCE) is Google\-infrastructure as a service that lets you run your large\-scale computing workloads on virtual machines. This document covers how to use Salt Cloud to provision and manage your virtual machines hosted within Google\(aqs infrastructure. .sp You can find out more about GCE and other Google Cloud Platform services at \fI\%https://cloud.google.com\fP\&. .SS Dependencies .INDENT 0.0 .IP \(bu 2 Source install of \fI\%Libcloud\fP (or greater than 0.14.0\-beta3 when available) .IP \(bu 2 PyCrypto >= 2.1. .IP \(bu 2 A Google Cloud Platform account with Compute Engine enabled .IP \(bu 2 A registered Service Account for authorization .IP \(bu 2 Oh, and obviously you\(aqll need \fI\%salt\fP .UNINDENT .SS Google Compute Engine Setup .INDENT 0.0 .IP 1. 3 Sign up for Google Cloud Platform Go to \fI\%https://cloud.google.com\fP and use your Google account to sign up for Google Cloud Platform and complete the guided instructions. .IP 2. 3 Create a Project Next, go to the console at \fI\%https://cloud.google.com/console\fP and create a new Project. Make sure to select your new Project if you are not automatically directed to the Project. .sp Projects are a way of grouping together related users, services, and billing. You may opt to create multiple Projects and the remaining instructions will need to be completed for each Project if you wish to use GCE and Salt Cloud to manage your virtual machines. .IP 3. 3 Enable the Google Compute Engine service In your Project, go to the \fIAPIs & auth\fP section and \fIAPIs\fP link and enable the Google Compute Engine service. .IP 4. 3 Create a Service Account To set up authorization, navigate to \fIAPIs & auth\fP section and then the \fIRegistered apps\fP link and click the \fIREGISTER APP\fP button. Give it a meaningful name like and select \fIWeb Application\fP\&. After clicking the \fIRegister\fP button, select \fICertificate\fP in the next screen. Click the \fIGenerate Certificate\fP button, record the generated email address for use in the \fBservice_account_email_address\fP of your \fB/etc/salt/cloud\fP file. Also download and save the generated private key. .IP 5. 3 You will need to convert the private key to a format compatible with libcloud. The original Google\-generated private key was encrypted using \fInotasecret\fP as a passphrase. Use the following command and record the location of the converted private key and record the location for use in the \fBservice_account_private_key\fP of your \fB/etc/salt/cloud\fP file: .INDENT 3.0 .INDENT 3.5 .sp .nf .ft C openssl pkcs12 \-in ORIG.pkey \-passin pass:notasecret \e \-nodes \-nocerts | openssl rsa \-out NEW.pem .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS Configuration .sp Set up the cloud config at \fB/etc/salt/cloud\fP: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C # Note: This example is for /etc/salt/cloud providers: gce\-config: # Set up the Project name and Service Account authorization # project: "your_project_name" service_account_email_address: "123\-a5gt@developer.gserviceaccount.com" service_account_private_key: "/path/to/your/NEW.pem" # Set up the location of the salt master # minion: master: saltmaster.example.com # Set up grains information, which will be common for all nodes # using this provider grains: node_type: broker release: 1.0.1 provider: gce .ft P .fi .UNINDENT .UNINDENT .SS Cloud Profiles .sp Set up an initial profile at \fB/etc/salt/cloud.profiles\fP: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C all_settings: image: centos\-6 size: n1\-standard\-1 location: europe\-west1\-b network: default tags: \(aq["one", "two", "three"]\(aq metadata: \(aq{"one": "1", "2": "two"}\(aq use_persistent_disk: True delete_boot_pd: False deploy: True make_master: False provider: gce\-config .ft P .fi .UNINDENT .UNINDENT .sp The profile can be realized now with a salt command: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-p all_settings gce\-instance .ft P .fi .UNINDENT .UNINDENT .sp This will create an salt minion instance named \fBgce\-instance\fP in GCE. If the command was executed on the salt\-master, its Salt key will automatically be signed on the master. .sp Once the instance has been created with salt\-minion installed, connectivity to it can be verified with Salt: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt \(aqami.example.com\(aq test.ping .ft P .fi .UNINDENT .UNINDENT .SS GCE Specific Settings .sp Consult the sample profile below for more information about GCE specific settings. Some of them are mandatory and are properly labeled below but typically also include a hard\-coded default. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C all_settings: # Image is used to define what Operating System image should be used # to for the instance. Examples are Debian 7 (wheezy) and CentOS 6. # # MANDATORY # image: centos\-6 # A \(aqsize\(aq, in GCE terms, refers to the instance\(aqs \(aqmachine type\(aq. See # the on\-line documentation for a complete list of GCE machine types. # # MANDATORY # size: n1\-standard\-1 # A \(aqlocation\(aq, in GCE terms, refers to the instance\(aqs \(aqzone\(aq. GCE # has the notion of both Regions (e.g. us\-central1, europe\-west1, etc) # and Zones (e.g. us\-central1\-a, us\-central1\-b, etc). # # MANDATORY # location: europe\-west1\-b # Use this setting to define the network resource for the instance. # All GCE projects contain a network named \(aqdefault\(aq but it\(aqs possible # to use this setting to create instances belonging to a different # network resource. # network: default # GCE supports instance/network tags and this setting allows you to # set custom tags. It should be a list of strings and must be # parse\-able by the python ast.literal_eval() function to convert it # to a python list. # tags: \(aq["one", "two", "three"]\(aq # GCE supports instance metadata and this setting allows you to # set custom metadata. It should be a hash of key/value strings and # parse\-able by the python ast.literal_eval() function to convert it # to a python dictionary. # metadata: \(aq{"one": "1", "2": "two"}\(aq # Use this setting to ensure that when new instances are created, # they will use a persistent disk to preserve data between instance # terminations and re\-creations. # use_persistent_disk: True # In the event that you wish the boot persistent disk to be permanently # deleted when you destroy an instance, set delete_boot_pd to True. # delete_boot_pd: False .ft P .fi .UNINDENT .UNINDENT .sp GCE instances do not allow remote access to the root user by default. Instead, another user must be used to run the deploy script using sudo. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C my\-gce\-config: # Configure which user to use to run the deploy script ssh_username: user ssh_keyfile: /home/user/.ssh/google_compute_engine .ft P .fi .UNINDENT .UNINDENT .SS Single instance details .sp This action is a thin wrapper around \fB\-\-full\-query\fP, which displays details on a single instance only. In an environment with several machines, this will save a user from having to sort through all instance data, just to examine a single instance. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-a show_instance myinstance .ft P .fi .UNINDENT .UNINDENT .SS Destroy, persistent disks, and metadata .sp As noted in the provider configuration, it\(aqs possible to force the boot persistent disk to be deleted when you destroy the instance. The way that this has been implemented is to use the instance metadata to record the cloud profile used when creating the instance. When \fBdestroy\fP is called, if the instance contains a \fBsalt\-cloud\-profile\fP key, it\(aqs value is used to reference the matching profile to determine if \fBdelete_boot_pd\fP is set to \fBTrue\fP\&. .sp Be aware that any GCE instances created with salt cloud will contain this custom \fBsalt\-cloud\-profile\fP metadata entry. .SS List various resources .sp It\(aqs also possible to list several GCE resources similar to what can be done with other providers. The following commands can be used to list GCE zones (locations), machine types (sizes), and images. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-\-list\-locations gce salt\-cloud \-\-list\-sizes gce salt\-cloud \-\-list\-images gce .ft P .fi .UNINDENT .UNINDENT .SS Getting Started With GoGrid .sp GoGrid is a public cloud provider supporting Linux and Windows. .SS Dependencies .sp The GoGrid driver for Salt Cloud requires Libcloud 0.13.2 or higher to be installed. .SS Configuration .sp To use Salt Cloud with GoGrid log into the GoGrid web interface and create an API key. Do this by clicking on "My Account" and then going to the API Keys tab. .sp The \fBapikey\fP and the \fBsharedsecret\fP configuration parameters need to be set in the configuration file to enable interfacing with GoGrid: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C # Note: This example is for /etc/salt/cloud.providers or any file in the # /etc/salt/cloud.providers.d/ directory. my\-gogrid\-config: provider: gogrid apikey: asdff7896asdh789 sharedsecret: saltybacon .ft P .fi .UNINDENT .UNINDENT .SS Profiles .SS Cloud Profiles .sp Set up an initial profile at \fB/etc/salt/cloud.profiles\fP or in the \fB/etc/salt/cloud.profiles.d/\fP directory: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C gogrid_512: provider: my\-gogrid\-config size: 512MB image: CentOS 6.2 (64\-bit) w/ None .ft P .fi .UNINDENT .UNINDENT .sp Sizes can be obtained using the \fB\-\-list\-sizes\fP option for the \fBsalt\-cloud\fP command: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C # salt\-cloud \-\-list\-sizes my\-gogrid\-config my\-gogrid\-config: \-\-\-\-\-\-\-\-\-\- gogrid: \-\-\-\-\-\-\-\-\-\- 512MB: \-\-\-\-\-\-\-\-\-\- bandwidth: None disk: 30 driver: get_uuid: id: 512MB name: 512MB price: 0.095 ram: 512 uuid: bde1e4d7c3a643536e42a35142c7caac34b060e9 \&...SNIP... .ft P .fi .UNINDENT .UNINDENT .sp Images can be obtained using the \fB\-\-list\-images\fP option for the \fBsalt\-cloud\fP command: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C # salt\-cloud \-\-list\-images my\-gogrid\-config my\-gogrid\-config: \-\-\-\-\-\-\-\-\-\- gogrid: \-\-\-\-\-\-\-\-\-\- CentOS 6.4 (64\-bit) w/ None: \-\-\-\-\-\-\-\-\-\- driver: extra: \-\-\-\-\-\-\-\-\-\- get_uuid: id: 18094 name: CentOS 6.4 (64\-bit) w/ None uuid: bfd4055389919e01aa6261828a96cf54c8dcc2c4 \&...SNIP... .ft P .fi .UNINDENT .UNINDENT .SS Getting Started With Joyent .sp Joyent is a public cloud provider supporting SmartOS, Linux, FreeBSD and Windows. .SS Dependencies .sp The Joyent driver for Salt Cloud requires Libcloud 0.13.2 or higher to be installed. .SS Configuration .sp The Joyent cloud requires three configuration parameters. The user name and password that are used to log into the Joyent system, and the location of the private ssh key associated with the Joyent account. The ssh key is needed to send the provisioning commands up to the freshly created virtual machine. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C # Note: This example is for /etc/salt/cloud.providers or any file in the # /etc/salt/cloud.providers.d/ directory. my\-joyent\-config: provider: joyent user: fred password: saltybacon private_key: /root/joyent.pem .ft P .fi .UNINDENT .UNINDENT .SS Profiles .SS Cloud Profiles .sp Set up an initial profile at \fB/etc/salt/cloud.profiles\fP or in the \fB/etc/salt/cloud.profiles.d/\fP directory: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C joyent_512 provider: my\-joyent\-config size: Extra Small 512 MB image: Arch Linux 2013.06 .ft P .fi .UNINDENT .UNINDENT .sp Sizes can be obtained using the \fB\-\-list\-sizes\fP option for the \fBsalt\-cloud\fP command: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C # salt\-cloud \-\-list\-sizes my\-joyent\-config my\-joyent\-config: \-\-\-\-\-\-\-\-\-\- joyent: \-\-\-\-\-\-\-\-\-\- Extra Small 512 MB: \-\-\-\-\-\-\-\-\-\- default: false disk: 15360 id: Extra Small 512 MB memory: 512 name: Extra Small 512 MB swap: 1024 vcpus: 1 \&...SNIP... .ft P .fi .UNINDENT .UNINDENT .sp Images can be obtained using the \fB\-\-list\-images\fP option for the \fBsalt\-cloud\fP command: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C # salt\-cloud \-\-list\-images my\-joyent\-config my\-joyent\-config: \-\-\-\-\-\-\-\-\-\- joyent: \-\-\-\-\-\-\-\-\-\- base: \-\-\-\-\-\-\-\-\-\- description: A 32\-bit SmartOS image with just essential packages installed. Ideal for users who are comfortable with setting up their own environment and tools. disabled: False files: \-\-\-\-\-\-\-\-\-\- \- compression: bzip2 \- sha1: 40cdc6457c237cf6306103c74b5f45f5bf2d9bbe \- size: 82492182 name: base os: smartos owner: 352971aa\-31ba\-496c\-9ade\-a379feaecd52 public: True \&...SNIP... .ft P .fi .UNINDENT .UNINDENT .SS Getting Started With Linode .sp Linode is a public cloud provider with a focus on Linux instances. .SS Dependencies .sp The Linode driver for Salt Cloud requires Libcloud 0.13.2 or higher to be installed. .SS Configuration .sp Linode requires a single API key, but the default root password for new instances also needs to be set: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C # Note: This example is for /etc/salt/cloud.providers or any file in the # /etc/salt/cloud.providers.d/ directory. my\-linode\-config: apikey: asldkgfakl;sdfjsjaslfjaklsdjf;askldjfaaklsjdfhasldsadfghdkf password: F00barbaz provider: linode .ft P .fi .UNINDENT .UNINDENT .sp The password needs to be 8 characters and contain lowercase, uppercase and numbers. .SS Profiles .SS Cloud Profiles .sp Set up an initial profile at \fB/etc/salt/cloud.profiles\fP or in the \fB/etc/salt/cloud.profiles.d/\fP directory: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C linode_1024: provider: my\-linode\-config size: Linode 1024 image: Arch Linux 2013.06 .ft P .fi .UNINDENT .UNINDENT .sp Sizes can be obtained using the \fB\-\-list\-sizes\fP option for the \fBsalt\-cloud\fP command: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C # salt\-cloud \-\-list\-sizes my\-linode\-config my\-linode\-config: \-\-\-\-\-\-\-\-\-\- linode: \-\-\-\-\-\-\-\-\-\- Linode 1024: \-\-\-\-\-\-\-\-\-\- bandwidth: 2000 disk: 49152 driver: get_uuid: id: 1 name: Linode 1024 price: 20.0 ram: 1024 uuid: 03e18728ce4629e2ac07c9cbb48afffb8cb499c4 \&...SNIP... .ft P .fi .UNINDENT .UNINDENT .sp Images can be obtained using the \fB\-\-list\-images\fP option for the \fBsalt\-cloud\fP command: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C # salt\-cloud \-\-list\-images my\-linode\-config my\-linode\-config: \-\-\-\-\-\-\-\-\-\- linode: \-\-\-\-\-\-\-\-\-\- Arch Linux 2013.06: \-\-\-\-\-\-\-\-\-\- driver: extra: \-\-\-\-\-\-\-\-\-\- 64bit: 1 pvops: 1 get_uuid: id: 112 name: Arch Linux 2013.06 uuid: 8457f92eaffc92b7666b6734a96ad7abe1a8a6dd \&...SNIP... .ft P .fi .UNINDENT .UNINDENT .SS Cloud Map File .sp A number of options exist when creating virtual machines. They can be managed directly from profiles and the command line execution, or a more complex map file can be created. The map file allows for a number of virtual machines to be created and associated with specific profiles. .sp Map files have a simple format, specify a profile and then a list of virtual machines to make from said profile: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C fedora_small: \- web1 \- web2 \- web3 fedora_high: \- redis1 \- redis2 \- redis3 cent_high: \- riak1 \- riak2 \- riak3 .ft P .fi .UNINDENT .UNINDENT .sp This map file can then be called to roll out all of these virtual machines. Map files are called from the salt\-cloud command with the \-m option: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C $ salt\-cloud \-m /path/to/mapfile .ft P .fi .UNINDENT .UNINDENT .sp Remember, that as with direct profile provisioning the \-P option can be passed to create the virtual machines in parallel: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C $ salt\-cloud \-m /path/to/mapfile \-P .ft P .fi .UNINDENT .UNINDENT .sp A map file can also be enforced to represent the total state of a cloud deployment by using the \fB\-\-hard\fP option. When using the hard option any vms that exist but are not specified in the map file will be destroyed: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C $ salt\-cloud \-m /path/to/mapfile \-P \-H .ft P .fi .UNINDENT .UNINDENT .sp Be careful with this argument, it is very dangerous! In fact, it is so dangerous that in order to use it, you must explicitly enable it in the main configuration file. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C enable_hard_maps: True .ft P .fi .UNINDENT .UNINDENT .sp A map file can include grains and minion configuration options: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C fedora_small: \- web1: minion: log_level: debug grains: cheese: tasty omelet: du fromage \- web2: minion: log_level: warn grains: cheese: more tasty omelet: with peppers .ft P .fi .UNINDENT .UNINDENT .sp A map file may also be used with the various query options: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C $ salt\-cloud \-m /path/to/mapfile \-Q {\(aqec2\(aq: {\(aqweb1\(aq: {\(aqid\(aq: \(aqi\-e6aqfegb\(aq, \(aqimage\(aq: None, \(aqprivate_ips\(aq: [], \(aqpublic_ips\(aq: [], \(aqsize\(aq: None, \(aqstate\(aq: 0}}, \(aqweb2\(aq: {\(aqAbsent\(aq}} .ft P .fi .UNINDENT .UNINDENT .sp \&...or with the delete option: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C $ salt\-cloud \-m /path/to/mapfile \-d The following virtual machines are set to be destroyed: web1 web2 Proceed? [N/y] .ft P .fi .UNINDENT .UNINDENT .SS Miscellaneous Salt Cloud Options .sp This page describes various miscellaneous options available in Salt Cloud .SS Deploy Script Arguments .sp Custom deploy scripts are unlikely to need custom arguments to be passed to them, but salt\-bootstrap has been extended quite a bit, and this may be necessary. script_args can be specified in either the profile or the map file, to pass arguments to the deploy script: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C ec2\-amazon: provider: ec2 image: ami\-1624987f size: Micro Instance ssh_username: ec2\-user script: bootstrap\-salt script_args: \-c /tmp/ .ft P .fi .UNINDENT .UNINDENT .sp This has also been tested to work with pipes, if needed: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C script_args: | head .ft P .fi .UNINDENT .UNINDENT .SS Sync After Install .sp Salt allows users to create custom modules, grains and states which can be synchronised to minions to extend Salt with further functionality. .sp This option will inform Salt Cloud to synchronise your custom modules, grains, states or all these to the minion just after it has been created. For this to happen, the following line needs to be added to the main cloud configuration file: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C sync_after_install: all .ft P .fi .UNINDENT .UNINDENT .sp The available options for this setting are: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C modules grains states all .ft P .fi .UNINDENT .UNINDENT .SS Setting up New Salt Masters .sp It has become increasingly common for users to set up multi\-hierarchal infrastructures using Salt Cloud. This sometimes involves setting up an instance to be a master in addition to a minion. With that in mind, you can now lay down master configuration on a machine by specifying master options in the profile or map file. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C make_master: True .ft P .fi .UNINDENT .UNINDENT .sp This will cause Salt Cloud to generate master keys for the instance, and tell salt\-bootstrap to install the salt\-master package, in addition to the salt\-minion package. .sp The default master configuration is usually appropriate for most users, and will not be changed unless specific master configuration has been added to the profile or map: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C master: user: root interface: 0.0.0.0 .ft P .fi .UNINDENT .UNINDENT .SS Delete SSH Keys .sp When Salt Cloud deploys an instance, the SSH pub key for the instance is added to the known_hosts file for the user that ran the salt\-cloud command. When an instance is deployed, a cloud provider generally recycles the IP address for the instance. When Salt Cloud attempts to deploy an instance using a recycled IP address that has previously been accessed from the same machine, the old key in the known_hosts file will cause a conflict. .sp In order to mitigate this issue, Salt Cloud can be configured to remove old keys from the known_hosts file when destroying the node. In order to do this, the following line needs to be added to the main cloud configuration file: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C delete_sshkeys: True .ft P .fi .UNINDENT .UNINDENT .SS Keeping /tmp/ Files .sp When Salt Cloud deploys an instance, it uploads temporary files to /tmp/ for salt\-bootstrap to put in place. After the script has run, they are deleted. To keep these files around (mostly for debugging purposes), the \-\-keep\-tmp option can be added: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-p myprofile mymachine \-\-keep\-tmp .ft P .fi .UNINDENT .UNINDENT .sp For those wondering why /tmp/ was used instead of /root/, this had to be done for images which require the use of sudo, and therefore do not allow remote root logins, even for file transfers (which makes /root/ unavailable). .SS Hide Output From Minion Install .sp By default Salt Cloud will stream the output from the minion deploy script directly to STDOUT. Although this can been very useful, in certain cases you may wish to switch this off. The following config option is there to enable or disable this output: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C display_ssh_output: False .ft P .fi .UNINDENT .UNINDENT .SS Connection Timeout .sp There are several stages when deploying Salt where Salt Cloud needs to wait for something to happen. The VM getting it\(aqs IP address, the VM\(aqs SSH port is available, etc. .sp If you find that the Salt Cloud defaults are not enough and your deployment fails because Salt Cloud did not wait log enough, there are some settings you can tweak. .INDENT 0.0 .INDENT 3.5 .IP "Note" .sp All values should be provided in seconds .UNINDENT .UNINDENT .sp You can tweak these settings globally, per cloud provider, or event per profile definition. .SS wait_for_ip_timeout .sp The amount of time Salt Cloud should wait for a VM to start and get an IP back from the cloud provider. Default: 5 minutes. .SS wait_for_ip_interval .sp The amount of time Salt Cloud should sleep while querying for the VM\(aqs IP. Default: 5 seconds. .SS ssh_connect_timeout .sp The amount of time Salt Cloud should wait for a successful SSH connection to the VM. Default: 5 minutes. .SS wait_for_passwd_timeout .sp The amount of time until an ssh connection can be established via password or ssh key. Default 15 seconds. .SS wait_for_fun_timeout .sp Some cloud drivers check for an available IP or a successful SSH connection using a function, namely, SoftLayer and SoftLayer\-HW. So, the amount of time Salt Cloud should retry such functions before failing. Default: 5 minutes. .SS wait_for_spot_timeout .sp The amount of time Salt Cloud should wait before an EC2 Spot instance is available. This setting is only available for the EC2 cloud driver. .SS Getting Started With OpenStack .sp OpenStack is one the most popular cloud projects. It\(aqs an open source project to build public and/or private clouds. You can use Salt Cloud to launch OpenStack instances. .INDENT 0.0 .IP \(bu 2 Using the new format, set up the cloud configuration at \fB/etc/salt/cloud.providers\fP or \fB/etc/salt/cloud.providers.d/openstack.conf\fP: .UNINDENT .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C my\-openstack\-config: # Set the location of the salt\-master # minion: master: saltmaster.example.com # Configure the OpenStack driver # identity_url: http://identity.youopenstack.com/v2.0/ compute_name: nova protocol: ipv4 compute_region: RegionOne # Configure Openstack authentication credentials # user: myname password: 123456 # tenant is the project name tenant: myproject provider: openstack .ft P .fi .UNINDENT .UNINDENT .SS Using nova client to get information from OpenStack .sp One of the best ways to get information about OpenStack is using the novaclient python package (available in pypi as python\-novaclient). The client configuration is a set of environment variables that you can get from the Dashboard. Log in and then go to Project \-> Access & security \-> API Access and download the "OpenStack RC file". Then: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C source /path/to/your/rcfile nova credentials nova endpoints .ft P .fi .UNINDENT .UNINDENT .sp In the \fBnova endpoints\fP output you can see the information about \fBcompute_region\fP and \fBcompute_name\fP\&. .SS Compute Region .sp It depends on the OpenStack cluster that you are using. Please, have a look at the previous sections. .SS Authentication .sp The \fBuser\fP and \fBpassword\fP is the same user as is used to log into the OpenStack Dashboard. .SS Profiles .sp Here is an example of a profile: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C openstack_512: provider: my\-openstack\-config size: m1.tiny image: cirros\-0.3.1\-x86_64\-uec ssh_key_file: /tmp/test.pem .ft P .fi .UNINDENT .UNINDENT .sp \fBsize\fP can be one of the options listed in the output of \fBnova flavor\-list\fP\&. .sp \fBimage\fP can be one of the options listed in the output of \fBnova image\-list\fP\&. .SS Getting Started With Parallels .sp Parallels Cloud Server is a product by Parallels that delivers a cloud hosting solution. The PARALLELS module for Salt Cloud enables you to manage instances hosted by a provider using PCS. Further information can be found at: .sp \fI\%http://www.parallels.com/products/pcs/\fP .INDENT 0.0 .IP \(bu 2 Using the old format, set up the cloud configuration at \fB/etc/salt/cloud\fP: .UNINDENT .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C # Set up the location of the salt master # minion: master: saltmaster.example.com # Set the PARALLELS access credentials (see below) # PARALLELS.user: myuser PARALLELS.password: badpass # Set the access URL for your PARALLELS provider # PARALLELS.url: https://api.cloud.xmission.com:4465/paci/v1.0/ .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .IP \(bu 2 Using the new format, set up the cloud configuration at \fB/etc/salt/cloud.providers\fP or \fB/etc/salt/cloud.providers.d/parallels.conf\fP: .UNINDENT .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C my\-parallels\-config: # Set up the location of the salt master # minion: master: saltmaster.example.com # Set the PARALLELS access credentials (see below) # user: myuser password: badpass # Set the access URL for your PARALLELS provider # url: https://api.cloud.xmission.com:4465/paci/v1.0/ provider: parallels .ft P .fi .UNINDENT .UNINDENT .SS Access Credentials .sp The \fBuser\fP, \fBpassword\fP and \fBurl\fP will be provided to you by your cloud provider. These are all required in order for the PARALLELS driver to work. .SS Cloud Profiles .sp Set up an initial profile at \fB/etc/salt/cloud.profiles\fP or \fB/etc/salt/cloud.profiles.d/parallels.conf\fP: .INDENT 0.0 .IP \(bu 2 Using the old cloud configuration format: .UNINDENT .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C parallels\-ubuntu: provider: parallels image: ubuntu\-12.04\-x86_64 .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .IP \(bu 2 Using the new cloud configuration format and the cloud configuration example from above: .UNINDENT .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C parallels\-ubuntu: provider: my\-parallels\-config image: ubuntu\-12.04\-x86_64 .ft P .fi .UNINDENT .UNINDENT .sp The profile can be realized now with a salt command: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C # salt\-cloud \-p parallels\-ubuntu myubuntu .ft P .fi .UNINDENT .UNINDENT .sp This will create an instance named \fBmyubuntu\fP on the cloud provider. The minion that is installed on this instance will have an \fBid\fP of \fBmyubuntu\fP\&. If the command was executed on the salt\-master, its Salt key will automatically be signed on the master. .sp Once the instance has been created with salt\-minion installed, connectivity to it can be verified with Salt: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C # salt myubuntu test.ping .ft P .fi .UNINDENT .UNINDENT .SS Required Settings .sp The following settings are always required for PARALLELS: .INDENT 0.0 .IP \(bu 2 Using the old cloud configuration format: .UNINDENT .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C PARALLELS.user: myuser PARALLELS.password: badpass PARALLELS.url: https://api.cloud.xmission.com:4465/paci/v1.0/ .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .IP \(bu 2 Using the new cloud configuration format: .UNINDENT .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C my\-parallels\-config: user: myuser password: badpass url: https://api.cloud.xmission.com:4465/paci/v1.0/ provider: parallels .ft P .fi .UNINDENT .UNINDENT .SS Optional Settings .sp Unlike other cloud providers in Salt Cloud, Parallels does not utilize a \fBsize\fP setting. This is because Parallels allows the end\-user to specify a more detailed configuration for their instances, than is allowed by many other cloud providers. The following options are available to be used in a profile, with their default settings listed. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C # Description of the instance. Defaults to the instance name. desc: # How many CPU cores, and how fast they are (in MHz) cpu_number: 1 cpu_power: 1000 # How many megabytes of RAM ram: 256 # Bandwidth available, in kbps bandwidth: 100 # How many public IPs will be assigned to this instance ip_num: 1 # Size of the instance disk (in GiB) disk_size: 10 # Username and password ssh_username: root password: # The name of the image, from \(ga\(gasalt\-cloud \-\-list\-images parallels\(ga\(ga image: ubuntu\-12.04\-x86_64 .ft P .fi .UNINDENT .UNINDENT .SS VM Profiles .sp Salt cloud designates virtual machines inside the profile configuration file. The profile configuration file defaults to \fB/etc/salt/cloud.profiles\fP and is a yaml configuration. The syntax for declaring profiles is simple: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C fedora_rackspace: provider: rackspace image: Fedora 17 size: 256 server script: Fedora .ft P .fi .UNINDENT .UNINDENT .sp A few key pieces of information need to be declared and can change based on the public cloud provider. A number of additional parameters can also be inserted: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C centos_rackspace: provider: rackspace image: CentOS 6.2 size: 1024 server script: RHEL6 minion: master: salt.example.com append_domain: webs.example.com grains: role: webserver .ft P .fi .UNINDENT .UNINDENT .sp The image must be selected from available images. Similarly, sizes must be selected from the list of sizes. To get a list of available images and sizes use the following command: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-\-list\-images openstack salt\-cloud \-\-list\-sizes openstack .ft P .fi .UNINDENT .UNINDENT .sp Some parameters can be specified in the main Salt cloud configuration file and then are applied to all cloud profiles. For instance if only a single cloud provider is being used then the provider option can be declared in the Salt cloud configuration file. .SS Multiple Configuration Files .sp In addition to \fB/etc/salt/cloud.profiles\fP, profiles can also be specified in any file matching \fBcloud.profiles.d/*conf\fP which is a sub\-directory relative to the profiles configuration file(with the above configuration file as an example, \fB/etc/salt/cloud.profiles.d/*.conf\fP). This allows for more extensible configuration, and plays nicely with various configuration management tools as well as version control systems. .SS Larger Example .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C rhel_ec2: provider: ec2 image: ami\-e565ba8c size: Micro Instance script: RHEL6 minion: cheese: edam ubuntu_ec2: provider: ec2 image: ami\-7e2da54e size: Micro Instance script: Ubuntu minion: cheese: edam ubuntu_rackspace: provider: rackspace image: Ubuntu 12.04 LTS size: 256 server script: Ubuntu minion: cheese: edam fedora_rackspace: provider: rackspace image: Fedora 17 size: 256 server script: Fedora minion: cheese: edam cent_linode: provider: linode image: CentOS 6.2 64bit size: Linode 512 script: RHEL6 cent_gogrid: provider: gogrid image: 12834 size: 512MB script: RHEL6 cent_joyent: provider: joyent image: centos\-6 script: RHEL6 size: Small 1GB .ft P .fi .UNINDENT .UNINDENT .SS Getting Started With Rackspace .sp Rackspace is a major public cloud platform which may be configured using either the \fIrackspace\fP or the \fIopenstack\fP driver, depending on your needs. .sp Please note that the \fIrackspace\fP driver is only intended for 1st gen instances, aka, "the old cloud" at Rackspace. It is required for 1st gen instances, but will \fInot\fP work with OpenStack\-based instances. Unless you explicitly have a reason to use it, it is highly recommended that you use the \fIopenstack\fP driver instead. .INDENT 0.0 .TP .B To use the \fIopenstack\fP driver (recommended), set up the cloud configuration at \fB/etc/salt/cloud.providers\fP or \fB/etc/salt/cloud.providers.d/rackspace.conf\fP: .UNINDENT .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C my\-rackspace\-config: # Set the location of the salt\-master # minion: master: saltmaster.example.com # Configure Rackspace using the OpenStack plugin # identity_url: \(aqhttps://identity.api.rackspacecloud.com/v2.0/tokens\(aq compute_name: cloudServersOpenStack protocol: ipv4 # Set the compute region: # compute_region: DFW # Configure Rackspace authentication credentials # user: myname tenant: 123456 apikey: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx provider: openstack .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .TP .B To use the \fIrackspace\fP driver, set up the cloud configuration at \fB/etc/salt/cloud.providers\fP or \fB/etc/salt/cloud.providers.d/rackspace.conf\fP: .UNINDENT .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C my\-rackspace\-config: provider: rackspace # The Rackspace login user user: fred # The Rackspace user\(aqs apikey apikey: 901d3f579h23c8v73q9 .ft P .fi .UNINDENT .UNINDENT .sp The settings that follow are for using Rackspace with the \fIopenstack\fP driver, and will not work with the \fIrackspace\fP driver. .SS Compute Region .sp Rackspace currently has six compute regions which may be used: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C DFW \-> Dallas/Forth Worth ORD \-> Chicago SYD \-> Sydney LON \-> London IAD \-> Northern Virginia HKG \-> Hong Kong .ft P .fi .UNINDENT .UNINDENT .sp Note: Currently the LON region is only avaiable with a UK account, and UK accounts cannot access other regions .SS Authentication .sp The \fBuser\fP is the same user as is used to log into the Rackspace Control Panel. The \fBtenant\fP and \fBapikey\fP can be found in the API Keys area of the Control Panel. The \fBapikey\fP will be labeled as API Key (and may need to be generated), and \fBtenant\fP will be labeled as Cloud Account Number. .sp An initial profile can be configured in \fB/etc/salt/cloud.profiles\fP or \fB/etc/salt/cloud.profiles.d/rackspace.conf\fP: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C openstack_512: provider: my\-rackspace\-config size: 512 MB Standard image: Ubuntu 12.04 LTS (Precise Pangolin) .ft P .fi .UNINDENT .UNINDENT .sp To instantiate a machine based on this profile: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C # salt\-cloud \-p openstack_512 myinstance .ft P .fi .UNINDENT .UNINDENT .sp This will create a virtual machine at Rackspace with the name \fBmyinstance\fP\&. This operation may take several minutes to complete, depending on the current load at the Rackspace data center. .sp Once the instance has been created with salt\-minion installed, connectivity to it can be verified with Salt: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C # salt myinstance test.ping .ft P .fi .UNINDENT .UNINDENT .SS RackConnect Environments .sp Rackspace offers a hybrid hosting configuration option called RackConnect that allows you to use a physical firewall appliance with your cloud servers. When this service is in use the public_ip assigned by nova will be replaced by a NAT ip on the firewall. For salt\-cloud to work properly it must use the newly assigned "access ip" instead of the Nova assigned public ip. You can enable that capability by adding this to your profiles: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C openstack_512: provider: my\-openstack\-config size: 512 MB Standard image: Ubuntu 12.04 LTS (Precise Pangolin) rackconnect: True .ft P .fi .UNINDENT .UNINDENT .SS Managed Cloud Environments .sp Rackspace offers a managed service level of hosting. As part of the managed service level you have the ability to choose from base of lamp installations on cloud server images. The post build process for both the base and the lamp installations used Chef to install things such as the cloud monitoring agent and the cloud backup agent. It also takes care of installing the lamp stack if selected. In order to prevent the post installation process from stomping over the bootstrapping you can add the below to your profiles. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C openstack_512: provider: my\-rackspace\-config size: 512 MB Standard image: Ubuntu 12.04 LTS (Precise Pangolin) managedcloud: True .ft P .fi .UNINDENT .UNINDENT .SS First and Next Generation Images .sp Rackspace provides two sets of virtual machine images, \fIfirst\fP and \fInext\fP generation. As of \fB0.8.9\fP salt\-cloud will default to using the \fInext\fP generation images. To force the use of first generation images, on the profile configuration please add: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C FreeBSD\-9.0\-512: provider: my\-rackspace\-config size: 512 MB Standard image: FreeBSD 9.0 force_first_gen: True .ft P .fi .UNINDENT .UNINDENT .SS Using the Salt Modules for Cloud .sp In addition to the \fBsalt\-cloud\fP command, Salt Cloud can be called from Salt, in a variety of different ways. Most users will be interested in either the execution module or the state module, but it is also possible to call Salt Cloud as a runner. .sp Because the actual work will be performed on a remote minion, the normal Salt Cloud configuration must exist on any target minion that needs to execute a Salt Cloud command. Because Salt Cloud now supports breaking out configuration into individual files, the configuration is easily managed using Salt\(aqs own \fBfile.managed\fP state function. For example, the following directories allow this configuration to be managed easily: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C /etc/salt/cloud.providers.d/ /etc/salt/cloud.profiles.d/ .ft P .fi .UNINDENT .UNINDENT .SS Minion Keys .sp Keep in mind that when creating minions, Salt Cloud will create public and private minion keys, upload them to the minion, and place the public key on the machine that created the minion. It will \fInot\fP attempt to place any public minion keys on the master, unless the minion which was used to create the instance is also the Salt Master. This is because granting arbitrary minions access to modify keys on the master is a serious security risk, and must be avoided. .SS Execution Module .sp The \fBcloud\fP module is available to use from the command line. At the moment, almost every standard Salt Cloud feature is available to use. The following commands are available: .SS list_images .sp This command is designed to show images that are available to be used to create an instance using Salt Cloud. In general they are used in the creation of profiles, but may also be used to create an instance directly (see below). Listing images requires a provider to be configured, and specified: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt myminion cloud.list_images my\-cloud\-provider .ft P .fi .UNINDENT .UNINDENT .SS list_sizes .sp This command is designed to show sizes that are available to be used to create an instance using Salt Cloud. In general they are used in the creation of profiles, but may also be used to create an instance directly (see below). This command is not available for all cloud providers; see the provider\-specific documentation for details. Listing sizes requires a provider to be configured, and specified: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt myminion cloud.list_sizes my\-cloud\-provider .ft P .fi .UNINDENT .UNINDENT .SS list_locations .sp This command is designed to show locations that are available to be used to create an instance using Salt Cloud. In general they are used in the creation of profiles, but may also be used to create an instance directly (see below). This command is not available for all cloud providers; see the provider\-specific documentation for details. Listing locations requires a provider to be configured, and specified: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt myminion cloud.list_locations my\-cloud\-provider .ft P .fi .UNINDENT .UNINDENT .SS query .sp This command is used to query all configured cloud providers, and display all instances associated with those accounts. By default, it will run a standard query, returning the following fields: .INDENT 0.0 .TP .B \fBid\fP The name or ID of the instance, as used by the cloud provider. .TP .B \fBimage\fP The disk image that was used to create this instance. .TP .B \fBprivate_ips\fP Any public IP addresses currently assigned to this instance. .TP .B \fBpublic_ips\fP Any private IP addresses currently assigned to this instance. .TP .B \fBsize\fP The size of the instance; can refer to RAM, CPU(s), disk space, etc., depending on the cloud provider. .TP .B \fBstate\fP The running state of the instance; for example, \fBrunning\fP, \fBstopped\fP, \fBpending\fP, etc. This state is dependent upon the provider. .UNINDENT .sp This command may also be used to perform a full query or a select query, as described below. The following usages are available: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt myminion cloud.query salt myminion cloud.query list_nodes salt myminion cloud.query list_nodes_full .ft P .fi .UNINDENT .UNINDENT .SS full_query .sp This command behaves like the \fBquery\fP command, but lists all information concerning each instance as provided by the cloud provider, in addition to the fields returned by the \fBquery\fP command. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt myminion cloud.full_query .ft P .fi .UNINDENT .UNINDENT .SS select_query .sp This command behaves like the \fBquery\fP command, but only returned select fields as defined in the \fB/etc/salt/cloud\fP configuration file. A sample configuration for this section of the file might look like: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C query.selection: \- id \- key_name .ft P .fi .UNINDENT .UNINDENT .sp This configuration would only return the \fBid\fP and \fBkey_name\fP fields, for those cloud providers that support those two fields. This would be called using the following command: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt myminion cloud.select_query .ft P .fi .UNINDENT .UNINDENT .SS profile .sp This command is used to create an instance using a profile that is configured on the target minion. Please note that the profile must be configured before this command can be used with it. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt myminion cloud.profile ec2\-centos64\-x64 my\-new\-instance .ft P .fi .UNINDENT .UNINDENT .sp Please note that the execution module does \fInot\fP run in parallel mode. Using multiple minions to create instances can effectively perform parallel instance creation. .SS create .sp This command is similar to the \fBprofile\fP command, in that it is used to create a new instance. However, it does not require a profile to be pre\-configured. Instead, all of the options that are normally configured in a profile are passed directly to Salt Cloud to create the instance: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt myminion cloud.create my\-ec2\-config my\-new\-instance \e image=ami\-1624987f size=\(aqMicro Instance\(aq ssh_username=ec2\-user \e securitygroup=default delvol_on_destroy=True .ft P .fi .UNINDENT .UNINDENT .sp Please note that the execution module does \fInot\fP run in parallel mode. Using multiple minions to create instances can effectively perform parallel instance creation. .SS destroy .sp This command is used to destroy an instance or instances. This command will search all configured providers and remove any instance(s) which matches the name(s) passed in here. The results of this command are \fInon\-reversable\fP and should be used with caution. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt myminion cloud.destroy myinstance salt myminion cloud.destroy myinstance1,myinstance2 .ft P .fi .UNINDENT .UNINDENT .SS action .sp This command implements both the \fBaction\fP and the \fBfunction\fP commands used in the standard \fBsalt\-cloud\fP command. If one of the standard \fBaction\fP commands is used, an instance name must be provided. If one of the standard \fBfunction\fP commands is used, a provider configuration must be named. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt myminion cloud.action start instance=myinstance salt myminion cloud.action show_image provider=my\-ec2\-config \e image=ami\-1624987f .ft P .fi .UNINDENT .UNINDENT .sp The actions available are largely dependant upon the module for the specific cloud provider. The following actions are available for all cloud providers: .INDENT 0.0 .TP .B \fBlist_nodes\fP This is a direct call to the \fBquery\fP function as described above, but is only performed against a single cloud provider. A provider configuration must be included. .TP .B \fBlist_nodes_select\fP This is a direct call to the \fBfull_query\fP function as described above, but is only performed against a single cloud provider. A provider configuration must be included. .TP .B \fBlist_nodes_select\fP This is a direct call to the \fBselect_query\fP function as described above, but is only performed against a single cloud provider. A provider configuration must be included. .TP .B \fBshow_instance\fP This is a thin wrapper around \fBlist_nodes\fP, which returns the full information about a single instance. An instance name must be provided. .UNINDENT .SS State Module .sp A subset of the execution module is available through the \fBcloud\fP state module. Not all functions are currently included, because there is currently insufficient code for them to perform statefully. For example, a command to create an istance may be issued with a series of options, but those options cannot currently be statefully managed. Additional states to manage these options will be released at a later time. .SS cloud.present .sp This state will ensure that an instance is present inside a particular cloud provider. Any option that is normally specified in the \fBcloud.create\fP execution module and function may be declared here, but only the actual presence of the instance will be managed statefully. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C my\-instance\-name: cloud.present: \- provider: my\-ec2\-config \- image: ami\-1624987f \- size: \(aqMicro Instance\(aq \- ssh_username: ec2\-user \- securitygroup: default \- delvol_on_destroy: True .ft P .fi .UNINDENT .UNINDENT .SS cloud.profile .sp This state will ensure that an instance is present inside a particular cloud provider. This function calls the \fBcloud.profile\fP execution module and function, but as with \fBcloud.present\fP, only the actual presence of the instance will be managed statefully. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C my\-instance\-name: cloud.present: \- profile ec2\-centos64\-x64 .ft P .fi .UNINDENT .UNINDENT .SS cloud.absent .sp This state will ensure that an instance (identified by name) does not exist in any of the cloud providers configured on the target minion. Please note that this state is \fInon\-reversable\fP and may be considered especially destructive when issued as a cloud state. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C my\-instance\-name: cloud.absent .ft P .fi .UNINDENT .UNINDENT .SS Runner Module .sp The \fBcloud\fP runner module is executed on the master, and performs actions using the configuration and Salt modules on the master itself. This means that any public minion keys will also be properly accepted by the master. .sp Using the functions in the runner module is no different than using those in the execution module, outside of the behavior described in the above paragraph. The following functions are available inside the runner: .INDENT 0.0 .IP \(bu 2 list_images .IP \(bu 2 list_sizes .IP \(bu 2 list_locations .IP \(bu 2 query .IP \(bu 2 full_query .IP \(bu 2 select_query .IP \(bu 2 profile .IP \(bu 2 destroy .IP \(bu 2 action .UNINDENT .sp Outside of the standard usage of \fBsalt\-run\fP itself, commands are executed as usual: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt\-run cloud.profile ec2\-centos64\-x86_64 my\-instance\-name .ft P .fi .UNINDENT .UNINDENT .SS CloudClient .sp The execution, state and runner modules ultimately all use the CloudClient library that ships with Salt. To use the CloudClient library locally (either on the master or a minion), create a client object and issue a command against it: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C import salt.cloud import pprint client = salt.cloud.CloudClient(\(aq/etc/salt/cloud\(aq) nodes = client.query() pprint.pprint(nodes) .ft P .fi .UNINDENT .UNINDENT .SS Getting Started With SoftLayer .sp SoftLayer is a public cloud provider, and baremetal hardware hosting provider. .SS Dependencies .sp The SoftLayer driver for Salt Cloud requires the softlayer package, which is available at PyPi: .sp \fI\%https://pypi.python.org/pypi/SoftLayer\fP .sp This package can be installed using \fIpip\fP or \fIeasy_install\fP: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C # pip install softlayer # easy_install softlayer .ft P .fi .UNINDENT .UNINDENT .SS Configuration .sp Set up the cloud config at \fB/etc/salt/cloud.providers\fP: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C # Note: These examples are for /etc/salt/cloud.providers my\-softlayer: # Set up the location of the salt master minion: master: saltmaster.example.com # Set the SoftLayer access credentials (see below) user: MYUSER1138 apikey: \(aqe3b68aa711e6deadc62d5b76355674beef7cc3116062ddbacafe5f7e465bfdc9\(aq provider: softlayer my\-softlayer\-hw: # Set up the location of the salt master minion: master: saltmaster.example.com # Set the SoftLayer access credentials (see below) user: MYUSER1138 apikey: \(aqe3b68aa711e6deadc62d5b76355674beef7cc3116062ddbacafe5f7e465bfdc9\(aq provider: softlayer_hw .ft P .fi .UNINDENT .UNINDENT .SS Access Credentials .sp The \fIuser\fP setting is the same user as is used to log into the SoftLayer Administration area. The \fIapikey\fP setting is found inside the Admin area after logging in: .INDENT 0.0 .IP \(bu 2 Hover over the \fIAdministrative\fP menu item. .IP \(bu 2 Click the \fIAPI Access\fP link. .IP \(bu 2 The \fIapikey\fP is located next to the \fIuser\fP setting. .UNINDENT .SS Profiles .SS Cloud Profiles .sp Set up an initial profile at \fB/etc/salt/cloud.profiles\fP: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C base_softlayer_ubuntu: provider: my\-softlayer image: UBUNTU_LATEST cpu_number: 1 ram: 1024 disk_size: 100 local_disk: True hourly_billing: True domain: example.com location: sjc01 # Optional max_net_speed: 1000 private_vlan: 396 private_network: True private_ssh: True # May be used _instead_of_ image global_identifier: 320d8be5\-46c0\-dead\-cafe\-13e3c51 .ft P .fi .UNINDENT .UNINDENT .sp Most of the above items are required; optional items are specified below. .SS image .sp Images to build an instance can be found using the \fI\-\-list\-images\fP option: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C # salt\-cloud \-\-list\-images my\-softlayer .ft P .fi .UNINDENT .UNINDENT .sp The setting used will be labeled as \fItemplate\fP\&. .SS cpu_number .sp This is the number of CPU cores that will be used for this instance. This number may be dependent upon the image that is used. For instance: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C Red Hat Enterprise Linux 6 \- Minimal Install (64 bit) (1 \- 4 Core): \-\-\-\-\-\-\-\-\-\- name: Red Hat Enterprise Linux 6 \- Minimal Install (64 bit) (1 \- 4 Core) template: REDHAT_6_64 Red Hat Enterprise Linux 6 \- Minimal Install (64 bit) (5 \- 100 Core): \-\-\-\-\-\-\-\-\-\- name: Red Hat Enterprise Linux 6 \- Minimal Install (64 bit) (5 \- 100 Core) template: REDHAT_6_64 .ft P .fi .UNINDENT .UNINDENT .sp Note that the template (meaning, the \fIimage\fP option) for both of these is the same, but the names suggests how many CPU cores are supported. .SS ram .sp This is the amount of memory, in megabytes, that will be allocated to this instance. .SS disk_size .sp The amount of disk space that will be allocated to this image, in megabytes. .SS local_disk .sp When true the disks for the computing instance will be provisioned on the host which it runs, otherwise SAN disks will be provisioned. .SS hourly_billing .sp When true the computing instance will be billed on hourly usage, otherwise it will be billed on a monthly basis. .SS domain .sp The domain name that will be used in the FQDN (Fully Qualified Domain Name) for this instance. The \fIdomain\fP setting will be used in conjunction with the instance name to form the FQDN. .SS location .sp Images to build an instance can be found using the \fI\-\-list\-locations\fP option: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C # salt\-cloud \-\-list\-location my\-softlayer .ft P .fi .UNINDENT .UNINDENT .SS max_net_speed .sp Specifies the connection speed for the instance\(aqs network components. This setting is optional. By default, this is set to 10. .SS public_vlan .sp If it is necessary for an instance to be created within a specific frontend VLAN, the ID for that VLAN can be specified in either the provider or profile configuration. .sp This ID can be queried using the \fIlist_vlans\fP function, as described below. This setting is optional. .SS private_vlan .sp If it is necessary for an instance to be created within a specific backend VLAN, the ID for that VLAN can be specified in either the provider or profile configuration. .sp This ID can be queried using the \fIlist_vlans\fP function, as described below. This setting is optional. .SS private_network .sp If a server is to only be used internally, meaning it does not have a public VLAN associated with it, this value would be set to True. This setting is optional. The default is False. .SS private_ssh .sp Whether to run the deploy script on the server using the public IP address or the private IP address. If set to True, Salt Cloud will attempt to SSH into the new server using the private IP address. The default is False. This settiong is optional. .SS global_identifier .sp When creating an instance using a custom template, this option is set to the corresponding value obtained using the \fIlist_custom_images\fP function. This option will not be used if an \fIimage\fP is set, and if an \fIimage\fP is not set, it is required. .sp The profile can be realized now with a salt command: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C # salt\-cloud \-p base_softlayer_ubuntu myserver .ft P .fi .UNINDENT .UNINDENT .sp Using the above configuration, this will create \fImyserver.example.com\fP\&. .sp Once the instance has been created with salt\-minion installed, connectivity to it can be verified with Salt: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C # salt \(aqmyserver.example.com\(aq test.ping .ft P .fi .UNINDENT .UNINDENT .SS Cloud Profiles .sp Set up an initial profile at \fB/etc/salt/cloud.profiles\fP: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C base_softlayer_hw_centos: provider: my\-softlayer\-hw # CentOS 6.0 \- Minimal Install (64 bit) image: 13963 # 2 x 2.0 GHz Core Bare Metal Instance \- 2 GB Ram size: 1921 # 250GB SATA II hdd: 19 # San Jose 01 location: 168642 domain: example.com # Optional vlan: 396 port_speed: 273 banwidth: 248 .ft P .fi .UNINDENT .UNINDENT .sp Most of the above items are required; optional items are specified below. .SS image .sp Images to build an instance can be found using the \fI\-\-list\-images\fP option: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C # salt\-cloud \-\-list\-images my\-softlayer\-hw .ft P .fi .UNINDENT .UNINDENT .sp A list of \fIid\(gas and names will be provided. The \(ganame\fP will describe the operating system and architecture. The \fIid\fP will be the setting to be used in the profile. .SS size .sp Sizes to build an instance can be found using the \fI\-\-list\-sizes\fP option: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C # salt\-cloud \-\-list\-sizes my\-softlayer\-hw .ft P .fi .UNINDENT .UNINDENT .sp A list of \fIid\(gas and names will be provided. The \(ganame\fP will describe the speed and quantity of CPU cores, and the amount of memory that the hardware will contain. The \fIid\fP will be the setting to be used in the profile. .SS hdd .sp There are currently two sizes of hard disk drive (HDD) that are available for hardware instances on SoftLayer: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C 19: 250GB SATA II 1267: 500GB SATA II .ft P .fi .UNINDENT .UNINDENT .sp The \fIhdd\fP setting in the profile will be either 19 or 1267. Other sizes may be added in the future. .SS location .sp Locations to build an instance can be found using the \fI\-\-list\-images\fP option: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C # salt\-cloud \-\-list\-locations my\-softlayer\-hw .ft P .fi .UNINDENT .UNINDENT .sp A list of IDs and names will be provided. The \fIlocation\fP will describe the location in human terms. The \fIid\fP will be the setting to be used in the profile. .SS domain .sp The domain name that will be used in the FQDN (Fully Qualified Domain Name) for this instance. The \fIdomain\fP setting will be used in conjunction with the instance name to form the FQDN. .SS vlan .sp If it is necessary for an instance to be created within a specific VLAN, the ID for that VLAN can be specified in either the provider or profile configuration. .sp This ID can be queried using the \fIlist_vlans\fP function, as described below. .SS port_speed .sp Specifies the speed for the instance\(aqs network port. This setting refers to an ID within the SoftLayer API, which sets the port speed. This setting is optional. The default is 273, or, 100 Mbps Public & Private Networks. The following settings are available: .INDENT 0.0 .IP \(bu 2 273: 100 Mbps Public & Private Networks .IP \(bu 2 274: 1 Gbps Public & Private Networks .IP \(bu 2 21509: 10 Mbps Dual Public & Private Networks (up to 20 Mbps) .IP \(bu 2 21513: 100 Mbps Dual Public & Private Networks (up to 200 Mbps) .IP \(bu 2 2314: 1 Gbps Dual Public & Private Networks (up to 2 Gbps) .IP \(bu 2 272: 10 Mbps Public & Private Networks .UNINDENT .SS bandwidth .sp Specifies the network bandwidth available for the instance. This setting refers to an ID within the SoftLayer API, which sets the bandwidth. This setting is optional. The default is 248, or, 5000 GB Bandwidth. The following settings are available: .INDENT 0.0 .IP \(bu 2 248: 5000 GB Bandwidth .IP \(bu 2 129: 6000 GB Bandwidth .IP \(bu 2 130: 8000 GB Bandwidth .IP \(bu 2 131: 10000 GB Bandwidth .IP \(bu 2 36: Unlimited Bandwidth (10 Mbps Uplink) .IP \(bu 2 125: Unlimited Bandwidth (100 Mbps Uplink) .UNINDENT .SS Actions .sp The following actions are currently supported by the SoftLayer Salt Cloud driver. .SS show_instance .sp This action is a thin wrapper around \fI\-\-full\-query\fP, which displays details on a single instance only. In an environment with several machines, this will save a user from having to sort through all instance data, just to examine a single instance. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C $ salt\-cloud \-a show_instance myinstance .ft P .fi .UNINDENT .UNINDENT .SS Functions .sp The following functions are currently supported by the SoftLayer Salt Cloud driver. .SS list_vlans .sp This function lists all VLANs associated with the account, and all known data from the SoftLayer API concerning those VLANs. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C $ salt\-cloud \-f list_vlans my\-softlayer $ salt\-cloud \-f list_vlans my\-softlayer\-hw .ft P .fi .UNINDENT .UNINDENT .sp The \fIid\fP returned in this list is necessary for the \fIvlan\fP option when creating an instance. .SS list_custom_images .sp This function lists any custom templates associated with the account, that can be used to create a new instance. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C $ salt\-cloud \-f list_custom_images my\-softlayer .ft P .fi .UNINDENT .UNINDENT .sp The \fIglobalIdentifier\fP returned in this list is necessary for the \fIglobal_identifier\fP option when creating an image using a custom template. .SS Optional Products for SoftLayer HW .sp The softlayer_hw provider supports the ability to add optional products, which are supported by SoftLayer\(aqs API. These products each have an ID associated with them, that can be passed into Salt Cloud with the \fIoptional_products\fP option: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C softlayer_hw_test: provider: my\-softlayer\-hw # CentOS 6.0 \- Minimal Install (64 bit) image: 13963 # 2 x 2.0 GHz Core Bare Metal Instance \- 2 GB Ram size: 1921 # 250GB SATA II hdd: 19 # San Jose 01 location: 168642 domain: example.com optional_products: # MySQL for Linux \- id: 28 # Business Continuance Insurance \- id: 104 .ft P .fi .UNINDENT .UNINDENT .sp These values can be manually obtained by looking at the source of an order page on the SoftLayer web interface. For convenience, many of these values are listed here: .SS Public Secondary IP Addresses .INDENT 0.0 .IP \(bu 2 22: 4 Public IP Addresses .IP \(bu 2 23: 8 Public IP Addresses .UNINDENT .SS Primary IPv6 Addresses .INDENT 0.0 .IP \(bu 2 17129: 1 IPv6 Address .UNINDENT .SS Public Static IPv6 Addresses .INDENT 0.0 .IP \(bu 2 1481: /64 Block Static Public IPv6 Addresses .UNINDENT .SS OS\-Specific Addon .INDENT 0.0 .IP \(bu 2 17139: XenServer Advanced for XenServer 6.x .IP \(bu 2 17141: XenServer Enterprise for XenServer 6.x .IP \(bu 2 2334: XenServer Advanced for XenServer 5.6 .IP \(bu 2 2335: XenServer Enterprise for XenServer 5.6 .IP \(bu 2 13915: Microsoft WebMatrix .IP \(bu 2 21276: VMware vCenter 5.1 Standard .UNINDENT .SS Control Panel Software .INDENT 0.0 .IP \(bu 2 121: cPanel/WHM with Fantastico and RVskin .IP \(bu 2 20778: Parallels Plesk Panel 11 (Linux) 100 Domain w/ Power Pack .IP \(bu 2 20786: Parallels Plesk Panel 11 (Windows) 100 Domain w/ Power Pack .IP \(bu 2 20787: Parallels Plesk Panel 11 (Linux) Unlimited Domain w/ Power Pack .IP \(bu 2 20792: Parallels Plesk Panel 11 (Windows) Unlimited Domain w/ Power Pack .IP \(bu 2 2340: Parallels Plesk Panel 10 (Linux) 100 Domain w/ Power Pack .IP \(bu 2 2339: Parallels Plesk Panel 10 (Linux) Unlimited Domain w/ Power Pack .IP \(bu 2 13704: Parallels Plesk Panel 10 (Windows) Unlimited Domain w/ Power Pack .UNINDENT .SS Database Software .INDENT 0.0 .IP \(bu 2 29: MySQL 5.0 for Windows .IP \(bu 2 28: MySQL for Linux .IP \(bu 2 21501: Riak 1.x .IP \(bu 2 20893: MongoDB .IP \(bu 2 30: Microsoft SQL Server 2005 Express .IP \(bu 2 92: Microsoft SQL Server 2005 Workgroup .IP \(bu 2 90: Microsoft SQL Server 2005 Standard .IP \(bu 2 94: Microsoft SQL Server 2005 Enterprise .IP \(bu 2 1330: Microsoft SQL Server 2008 Express .IP \(bu 2 1340: Microsoft SQL Server 2008 Web .IP \(bu 2 1337: Microsoft SQL Server 2008 Workgroup .IP \(bu 2 1334: Microsoft SQL Server 2008 Standard .IP \(bu 2 1331: Microsoft SQL Server 2008 Enterprise .IP \(bu 2 2179: Microsoft SQL Server 2008 Express R2 .IP \(bu 2 2173: Microsoft SQL Server 2008 Web R2 .IP \(bu 2 2183: Microsoft SQL Server 2008 Workgroup R2 .IP \(bu 2 2180: Microsoft SQL Server 2008 Standard R2 .IP \(bu 2 2176: Microsoft SQL Server 2008 Enterprise R2 .UNINDENT .SS Anti\-Virus & Spyware Protection .INDENT 0.0 .IP \(bu 2 594: McAfee VirusScan Anti\-Virus \- Windows .IP \(bu 2 414: McAfee Total Protection \- Windows .UNINDENT .SS Insurance .INDENT 0.0 .IP \(bu 2 104: Business Continuance Insurance .UNINDENT .SS Monitoring .INDENT 0.0 .IP \(bu 2 55: Host Ping .IP \(bu 2 56: Host Ping and TCP Service Monitoring .UNINDENT .SS Notification .INDENT 0.0 .IP \(bu 2 57: Email and Ticket .UNINDENT .SS Advanced Monitoring .INDENT 0.0 .IP \(bu 2 2302: Monitoring Package \- Basic .IP \(bu 2 2303: Monitoring Package \- Advanced .IP \(bu 2 2304: Monitoring Package \- Premium Application .UNINDENT .SS Response .INDENT 0.0 .IP \(bu 2 58: Automated Notification .IP \(bu 2 59: Automated Reboot from Monitoring .IP \(bu 2 60: 24x7x365 NOC Monitoring, Notification, and Response .UNINDENT .SS Intrusion Detection & Protection .INDENT 0.0 .IP \(bu 2 413: McAfee Host Intrusion Protection w/Reporting .UNINDENT .SS Hardware & Software Firewalls .INDENT 0.0 .IP \(bu 2 411: APF Software Firewall for Linux .IP \(bu 2 894: Microsoft Windows Firewall .IP \(bu 2 410: 10Mbps Hardware Firewall .IP \(bu 2 409: 100Mbps Hardware Firewall .IP \(bu 2 408: 1000Mbps Hardware Firewall .UNINDENT .SS Troubleshooting Salt Cloud .sp This page describes various steps for troubleshooting problems that may arise while using Salt Cloud. .SS Generic Troubleshooting Steps .sp This section describes a set of instructions that are useful to a large number of situations, and are likely to solve most issues that arise. .INDENT 0.0 .INDENT 3.5 .IP "Version Compatibility" .sp One of the most common issues that Salt Cloud users run into is import errors. These are often caused by version compatibility issues with Salt. .sp Salt 0.16.x works with Salt Cloud 0.8.9 or greater. .sp Salt 0.17.x requires Salt Cloud 0.8.11. .sp Releases after 0.17.x (0.18 or greater) should not encounter issues as Salt Cloud has been merged into Salt itself. .UNINDENT .UNINDENT .SS Debug Mode .sp Frequently, running Salt Cloud in debug mode will reveal information about a deployment which would otherwise not be obvious: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-p myprofile myinstance \-l debug .ft P .fi .UNINDENT .UNINDENT .sp Keep in mind that a number of messages will appear that look at first like errors, but are in fact intended to give developers factual information to assist in debugging. A number of messages that appear will be for cloud providers that you do not have configured; in these cases, the message usually is intended to confirm that they are not configured. .SS Salt Bootstrap .sp By default, Salt Cloud uses the Salt Bootstrap script to provision instances: .sp This script is packaged with Salt Cloud, but may be updated without updating the Salt package: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-u .ft P .fi .UNINDENT .UNINDENT .SS The Bootstrap Log .sp If the default deploy script was used, there should be a file in the \fB/tmp/\fP directory called \fBbootstrap\-salt.log\fP\&. This file contains the full output from the deployment, including any errors that may have occurred. .SS Keeping Temp Files .sp Salt Cloud uploads minion\-specific files to instances once they are available via SSH, and then executes a deploy script to put them into the correct place and install Salt. The \fB\-\-keep\-tmp\fP option will instruct Salt Cloud not to remove those files when finished with them, so that the user may inspect them for problems: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-p myprofile myinstance \-\-keep\-tmp .ft P .fi .UNINDENT .UNINDENT .sp By default, Salt Cloud will create a directory on the target instance called \fB/tmp/.saltcloud/\fP\&. This directory should be owned by the user that is to execute the deploy script, and should have permissions of \fB0700\fP\&. .sp Most cloud providers are configured to use \fBroot\fP as the default initial user for deployment, and as such, this directory and all files in it should be owned by the \fBroot\fP user. .sp The \fB/tmp/.saltcloud/\fP directory should the following files: .INDENT 0.0 .IP \(bu 2 A \fBdeploy.sh\fP script. This script should have permissions of \fB0755\fP\&. .IP \(bu 2 A \fB\&.pem\fP and \fB\&.pub\fP key named after the minion. The \fB\&.pem\fP file should have permissions of \fB0600\fP\&. Ensure that the \fB\&.pem\fP and \fB\&.pub\fP files have been properly copied to the \fB/etc/salt/pki/minion/\fP directory. .IP \(bu 2 A file called \fBminion\fP\&. This file should have been copied to the \fB/etc/salt/\fP directory. .IP \(bu 2 Optionally, a file called \fBgrains\fP\&. This file, if present, should have been copied to the \fB/etc/salt/\fP directory. .UNINDENT .SS Unprivileged Primary Users .sp Some providers, most notably EC2, are configured with a different primary user. Some common examples are \fBec2\-user\fP, \fBubuntu\fP, \fBfedora\fP and \fBbitnami\fP\&. In these cases, the \fB/tmp/.saltcloud/\fP directory and all files in it should be owned by this user. .sp Some providers, such as EC2, are configured to not require these users to provide a password when using the \fBsudo\fP command. Because it is more secure to require \fBsudo\fP users to provide a password, other providers are configured that way. .sp If this instance is required to provide a password, it needs to be configured in Salt Cloud. A password for sudo to use may be added to either the provider configuration or the profile configuration: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C sudo_password: mypassword .ft P .fi .UNINDENT .UNINDENT .SS \fB/tmp/\fP is Mounted as \fBnoexec\fP .sp It is more secure to mount the \fB/tmp/\fP directory with a \fBnoexec\fP option. This is uncommon on most cloud providers, but very common in private environments. To see if the \fB/tmp/\fP directory is mounted this way, run the following command: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C mount | grep tmp .ft P .fi .UNINDENT .UNINDENT .sp The if the output of this command includes a line that looks like this, then the \fB/tmp/\fP directory is mounted as \fBnoexec\fP: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C tmpfs on /tmp type tmpfs (rw,noexec) .ft P .fi .UNINDENT .UNINDENT .sp If this is the case, then the \fBdeploy_command\fP will need to be changed in order to run the deploy script through the \fBsh\fP command, rather than trying to execute it directly. This may be specified in either the provider or the profile config: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C deploy_command: sh /tmp/.saltcloud/deploy.sh .ft P .fi .UNINDENT .UNINDENT .sp Please note that by default, Salt Cloud will place its files in a directory called \fB/tmp/.saltcloud/\fP\&. This may be also be changed in the provider or profile configuration: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C tmp_dir: /tmp/.saltcloud/ .ft P .fi .UNINDENT .UNINDENT .sp If this directory is changed, then the \fBdeploy_command\fP need to be changed in order to reflect the \fBtmp_dir\fP configuration. .SS Executing the Deploy Script Manually .sp If all of the files needed for deployment were successfully uploaded to the correct locations, and contain the correct permissions and ownerships, the deploy script may be executed manually in order to check for other issues: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C cd /tmp/.saltcloud/ \&./deploy.sh .ft P .fi .UNINDENT .UNINDENT .SS Spinning up Windows Minions .sp It is possible to use Salt Cloud to spin up Windows instances, and then install Salt on them. This functionality is available on all cloud providers that are supported by Salt Cloud. However, it may not necessarily be available on all Windows images. .SS Requirements .sp Salt Cloud makes use of \fIsmbclient\fP and \fIwinexe\fP to set up the Windows Salt Minion installer. \fIsmbclient\fP may be part of either the \fIsamba\fP package, or its own \fIsmbclient\fP package, depending on the distribution. \fIwinexe\fP is less commonly available in distribution\-specific repositories. However, it is currently being built for various distributions in 3rd party channels: .INDENT 0.0 .IP \(bu 2 \fI\%RPMs at pbone.net\fP .IP \(bu 2 \fI\%OpenSuse Build Service\fP .UNINDENT .sp Additionally, a copy of the Salt Minion Windows installer must be present on the system on which Salt Cloud is running. This installer may be downloaded from saltstack.com: .INDENT 0.0 .IP \(bu 2 \fI\%SaltStack Download Area\fP .UNINDENT .SS Firewall Settings .sp Because Salt Cloud makes use of \fIsmbclient\fP and \fIwinexe\fP, port 445 must be open on the target image. This port is not generally open by default on a standard Windows distribution, and care must be taken to use an image in which this port is open, or the Windows firewall is disabled. .SS Configuration .sp Configuration is set as usual, with some extra configuration settings. The location of the Windows installer on the machine that Salt Cloud is running on must be specified. This may be done in any of the regular configuration files (main, providers, profiles, maps). For example: .sp Setting the installer in \fB/etc/salt/cloud.providers\fP: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C my\-softlayer: provider: softlayer user: MYUSER1138 apikey: \(aqe3b68aa711e6deadc62d5b76355674beef7cc3116062ddbacafe5f7e465bfdc9\(aq minion: master: saltmaster.example.com win_installer: /root/Salt\-Minion\-0.17.0\-AMD64\-Setup.exe win_username: Administrator win_password: letmein .ft P .fi .UNINDENT .UNINDENT .sp The default Windows user is \fIAdministrator\fP, and the default Windows password is blank. .SS Install Salt Cloud .sp Salt Cloud is now part of Salt proper. It was merged in as of \fBSalt version 2014.1.0\fP\&. .sp Salt Cloud depends on \fBapache\-libcloud\fP\&. Libcloud can be installed via pip with \fBpip install apache\-libcloud\fP\&. .SS Installing Salt Cloud for development .sp Installing Salt for development enables Salt Cloud development as well, just make sure \fBapache\-libcloud\fP is installed as per above paragraph. .sp See these instructions: \fBInstalling Salt for development\fP\&. .sp Salt cloud is a public cloud provisioning tool. Salt cloud is made to integrate Salt into cloud providers in a clean way so that minions on public cloud systems can be quickly and easily modeled and provisioned. .sp Salt cloud allows for cloud based minions to be managed via virtual machine maps and profiles. This means that individual cloud VMs can be created, or large groups of cloud VMs can be created at once or managed. .sp Virtual machines created with Salt cloud install salt on the target virtual machine and assign it to the specified master. This means that virtual machines can be provisioned and then potentially never logged into. .sp While Salt Cloud has been made to work with Salt, it is also a generic cloud management platform and can be used to manage non Salt centric clouds. .SH GETTING STARTED .INDENT 0.0 .IP \(bu 2 \fBInstalling salt cloud\fP .UNINDENT .sp Some quick guides covering getting started with each of the various cloud providers. .INDENT 0.0 .IP \(bu 2 \fBGetting Started With Azure\fP .IP \(bu 2 \fBGetting Started With Digital Ocean\fP .IP \(bu 2 \fBGetting Started With EC2\fP .IP \(bu 2 \fBGetting Started With GoGrid\fP .IP \(bu 2 \fBGetting Started With Google Compute Engine\fP .IP \(bu 2 \fBGetting Started With Joyent\fP .IP \(bu 2 \fBGetting Started With Linode\fP .IP \(bu 2 \fBGetting Started With OpenStack\fP .IP \(bu 2 \fBGetting Started With Parallels\fP .IP \(bu 2 \fBGetting Started With Rackspace\fP .IP \(bu 2 \fBGetting Started With SoftLayer\fP .UNINDENT .SH CORE CONFIGURATION .sp The core configuration of Salt cloud is handled in the cloud configuration file. This file is comprised of global configurations for interfacing with cloud providers. .INDENT 0.0 .IP \(bu 2 \fBCore Configuration\fP .UNINDENT .SH WINDOWS CONFIGURATION .sp Salt Cloud may be used to spin up a Windows minion, and then install the Salt Minion client on that instance. At this time, Salt Cloud itself still needs to be run from a Linux or Unix machine. .INDENT 0.0 .IP \(bu 2 \fBWindows Configuration\fP .UNINDENT .SH USING SALT CLOUD .sp Salt cloud works via profiles and maps. Simple profiles for cloud VMs are defined and can be used directly, or a map can be defined specifying a large group of virtual machines to create. .INDENT 0.0 .IP \(bu 2 \fBProfiles\fP .IP \(bu 2 \fBMaps\fP .UNINDENT .sp Once a VM has been deployed, a number of actions may be available to perform on it, depending on the specific cloud provider. .INDENT 0.0 .IP \(bu 2 \fBActions\fP .UNINDENT .sp Depending on your cloud provider, a number of functions may also be available which do not require a VM to be specified. .INDENT 0.0 .IP \(bu 2 \fBFunctions\fP .UNINDENT .SH MISCELLANEOUS OPTIONS .INDENT 0.0 .IP \(bu 2 \fBMiscellaneous\fP .UNINDENT .SH TROUBLESHOOTING STEPS .INDENT 0.0 .IP \(bu 2 \fBTroubleshooting\fP .UNINDENT .SH EXTENDING SALT CLOUD .sp Salt Cloud extensions work in a way similar to Salt modules. Therefore extending Salt cloud to manage more public cloud providers and operating systems is easy. .INDENT 0.0 .IP \(bu 2 \fBAdding Cloud Providers\fP .IP \(bu 2 \fBAdding OS Support\fP .UNINDENT .SH USING SALT CLOUD FROM SALT .sp Several Salt Cloud modules exist within Salt itself in order to manage cloud instances using Salt\(aqs own powerful feature set. .INDENT 0.0 .IP \(bu 2 \fBUsing Salt Cloud from Salt\fP .UNINDENT .SH FEATURE COMPARISON .sp A table is available which compares various features available across all supported cloud providers. .INDENT 0.0 .IP \(bu 2 \fBFeatures\fP .UNINDENT .SH LEGACY RELEASES .sp Changed in version 2014.1.0: (Hydrogen) Release notes will be part of Salt\(aqs main release notes starting with Salt\(aqs 2014.1.0 (Hydrogen) release. .INDENT 0.0 .IP \(bu 2 \fBLegacy Release Notes\fP .UNINDENT .SH REFERENCE .INDENT 0.0 .IP \(bu 2 \fBCommand\-line interface\fP .IP \(bu 2 \fBFull table of contents\fP .UNINDENT .SH VIRTUAL MACHINE DISK PROFILES .sp Salt Virt allows for the disks created for deployed virtual machines to be finely configured. The configuration is a simple data structure which is read from the \fBconfig.option\fP function, meaning that the configuration can be stored in the minion config file, the master config file, or the minion\(aqs pillar. .sp This configuration option is called \fBvirt.disk\fP\&. The default \fBvirt.disk\fP data structure looks like this: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C virt.disk: default: \- system: size: 8192 format: qcow2 model: virtio .ft P .fi .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 The format and model does not need to be defined, Salt will default to the optimal format used by the underlying hypervisor, in the case of kvm this it is \fBqcow2\fP and \fBvirtio\fP\&. .UNINDENT .UNINDENT .sp This configuration sets up a disk profile called default. The default profile creates a single system disk on the virtual machine. .SS Define More Profiles .sp Many environments will require more complex disk profiles and may require more than one profile, this can be easily accomplished: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C virt.disk: default: \- system: size: 8192 database: \- system: size: 8192 \- data: size: 30720 web: \- system: size: 1024 \- logs: size: 5120 .ft P .fi .UNINDENT .UNINDENT .sp This configuration allows for one of three profiles to be selected, allowing virtual machines to be created with different storage needs of the deployed vm. .SH SALT VIRT - THE SALTSTACK CLOUD CONTROLLER .sp The Salt Virt cloud controller capability was initial added to Salt in version 0.14.0 as an alpha technology. .sp The initial Salt Virt system supports core cloud operations: .INDENT 0.0 .IP \(bu 2 Virtual machine deployment .IP \(bu 2 Inspection of deployed VMs .IP \(bu 2 Virtual machine migration .IP \(bu 2 Network profiling .IP \(bu 2 Automatic VM integration with all aspects of Salt .IP \(bu 2 Image Pre\-seeding .UNINDENT .sp Many features are currently under development to enhance the capabilities of the Salt Virt systems. .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 It is noteworthy that Salt was originally developed with the intent of using the Salt communication system as the backbone to a cloud controller. This means that the Salt Virt system is not an afterthought, simply a system that took the back seat to other development. The original attempt to develop the cloud control aspects of Salt was a project called butter. This project never took off, but was functional and proves the early viability of Salt to be a cloud controller. .UNINDENT .UNINDENT .SS Salt Virt Tutorial .sp A tutorial about how to get Salt Virt up and running has been added to the tutorial section: .sp \fBCloud Controller Tutorial\fP .SS The Salt Virt Runner .sp The point of interaction with the cloud controller is the \fBvirt\fP runner. The \fBvirt\fP runner comes with routines to execute specific virtual machine routines. .sp Reference documentation for the virt runner is available with the runner module documentation: .sp \fBVirt Runner Reference\fP .SS Based on Live State Data .sp The Salt Virt system is based on using Salt to query live data about hypervisors and then using the data gathered to make decisions about cloud operations. This means that no external resources are required to run Salt Virt, and that the information gathered about the cloud is live and accurate. .SH VIRTUAL MACHINE NETWORK PROFILES .sp Salt Virt allows for the network devices created for deployed virtual machines to be finely configured. The configuration is a simple data structure which is read from the \fBconfig.option\fP function, meaning that the configuration can be stored in the minion config file, the master config file, or the minion\(aqs pillar. .sp This configuration option is called \fBvirt.nic\fP\&. By default the \fBvirt.nic\fP option is empty but defaults to a data structure which looks like this: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C virt.nic: default: eth0: bridge: br0 model: virtio .ft P .fi .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 The model does not need to be defined, Salt will default to the optimal model used by the underlying hypervisor, in the case of kvm this model is \fBvirtio\fP .UNINDENT .UNINDENT .sp This configuration sets up a network profile called default. The default profile creates a single Ethernet device on the virtual machine that is bridged to the hypervisor\(aqs \fBbr0\fP interface. This default setup does not require setting up the \fBvirt.nic\fP configuration, and is the reason why a default install only requires setting up the \fBbr0\fP bridge device on the hypervisor. .SS Define More Profiles .sp Many environments will require more complex network profiles and may require more than one profile, this can be easily accomplished: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C virt.nic: dual: eth0: bridge: service_br eth1: bridge: storage_br single: eth0: bridge: service_br triple: eth0: bridge: service_br eth1: bridge: storage_br eth2: bridge: dmz_br all: eth0: bridge: service_br eth1: bridge: storage_br eth2: bridge: dmz_br eth3: bridge: database_br dmz: eth0: bridge: service_br eth1: bridge: dmz_br database: eth0: bridge: service_br eth1: bridge: database_br .ft P .fi .UNINDENT .UNINDENT .sp This configuration allows for one of six profiles to be selected, allowing virtual machines to be created which attach to different network depending on the needs of the deployed vm. .SH SALT SSH .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 SALT\-SSH IS ALPHA SOFTWARE AND MAY NOT BE READY FOR PRODUCTION USE .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 On many systems, \fBsalt\-ssh\fP will be in its own package, usually named \fBsalt\-ssh\fP\&. .UNINDENT .UNINDENT .sp In version 0.17.0 of Salt a new transport system was introduced, the ability to use SSH for Salt communication. This addition allows for Salt routines to be executed on remote systems entirely through ssh, bypassing the need for a Salt Minion to be running on the remote systems and the need for a Salt Master. .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 The Salt SSH system does not supercede the standard Salt communication systems, it simply offers an SSH based alternative that does not require ZeroMQ and a remote agent. Be aware that since all communication with Salt SSH is executed via SSH it is substantially slower than standard Salt with ZeroMQ. .UNINDENT .UNINDENT .sp Salt SSH is very easy to use, simply set up a basic \fIroster\fP file of the systems to connect to and run \fBsalt\-ssh\fP commands in a similar way as standard \fBsalt\fP commands. .SS Salt SSH Roster .sp The roster system in Salt allows for remote minions to be easily defined. .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 See the \fBRoster documentation\fP for more details. .UNINDENT .UNINDENT .sp Simply create the roster file, the default location is \fI/etc/salt/roster\fP: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C web1: 192.168.42.1 .ft P .fi .UNINDENT .UNINDENT .sp This is a very basic roster file where a Salt ID is being assigned to an IP address. A more elaborate roster can be created: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C web1: host: 192.168.42.1 # The IP addr or DNS hostname user: fred # Remote executions will be executed as user fred passwd: foobarbaz # The password to use for login, if omitted, keys are used sudo: True # Whether to sudo to root, not enabled by default web2: host: 192.168.42.2 .ft P .fi .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 sudo works only if NOPASSWD is set for user in /etc/sudoers: \fBfred ALL=(ALL) NOPASSWD: ALL\fP .UNINDENT .UNINDENT .SS Calling Salt SSH .sp The \fBsalt\-ssh\fP command can be easily executed in the same was as a salt command: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt\-ssh \(aq*\(aq test.ping .ft P .fi .UNINDENT .UNINDENT .sp Commands with \fBsalt\-ssh\fP follow the same syntax as the \fBsalt\fP command. .sp The standard salt functions are available! The output is the same as \fBsalt\fP and many of the same flags are available. Please see \fI\%http://docs.saltstack.com/ref/cli/salt\-ssh.html\fP for all of the available options. .SS Raw Shell Calls .sp By default \fBsalt\-ssh\fP runs Salt execution modules on the remote system, but \fBsalt\-ssh\fP can also execute raw shell commands: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt\-ssh \(aq*\(aq \-r \(aqifconfig\(aq .ft P .fi .UNINDENT .UNINDENT .SS States Via Salt SSH .sp The Salt State system can also be used with \fBsalt\-ssh\fP\&. The state system abstracts the same interface to the user in \fBsalt\-ssh\fP as it does when using standard \fBsalt\fP\&. The intent is that Salt Formulas defined for standard \fBsalt\fP will work seamlessly with \fBsalt\-ssh\fP and vice\-versa. .sp The standard Salt States walkthroughs function by simply replacing \fBsalt\fP commands with \fBsalt\-ssh\fP\&. .SS Targeting with Salt SSH .sp Due to the fact that the targeting approach differs in salt\-ssh, only glob and regex targets are supported as of this writing, the remaining target systems still need to be implemented. .SS Configuring Salt SSH .sp Salt SSH takes its configuration from a master configuration file. Normally, this file is in \fB/etc/salt/master\fP\&. If one wishes to use a customized configuration file, the \fB\-c\fP option to Salt SSH facilitates passing in a directory to look inside for a configuration file named \fBmaster\fP\&. .SS Running Salt SSH as non\-root user .sp By default, Salt read all the configuration from /etc/salt/. If you are running Salt SSH with a regular user you have to modify some paths or you will get "Permission denied" messages. You have to modify two parameters: \fBpki_dir\fP and \fBcachedir\fP\&. Those should point to a full path writable for the user. .sp It\(aqs recommed not to modify /etc/salt for this purpose. Create a private copy of /etc/salt for the user and run the command with \fB\-c /new/config/path\fP\&. .SH SALT ROSTERS .sp Salt rosters are plugable systems added in Salt 0.17.0 to facilitate the \fBsalt\-ssh\fP system. The roster system was created because \fBsalt\-ssh\fP needs a means to identify which systems need to be targeted for execution. .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 The Roster System is not needed or used in standard Salt because the master does not need to be initially aware of target systems, since the Salt Minion checks itself into the master. .UNINDENT .UNINDENT .sp Since the roster system is pluggable, it can be easily augmented to attach to any existing systems to gather information about what servers are presently available and should be attached to by \fBsalt\-ssh\fP\&. By default the roster file is located at /etc/salt/roster. .SS How Rosters Work .sp The roster system compiles a data structure internally refered to as \fItargets\fP\&. The \fItargets\fP is a list of target systems and attributes about how to connect to said systems. The only requirement for a roster module in Salt is to return the \fItargets\fP data structure. .SS Targets Data .sp The information which can be stored in a roster \fItarget\fP is the following: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C : # The id to reference the target system with host: # The IP address or DNS name of the remote host user: # The user to log in as passwd: # The password to log in with # Optional parameters port: # The target system\(aqs ssh port number sudo: # Boolean to run command via sudo priv: # File path to ssh private key, defaults to salt\-ssh.rsa timeout: # Number of seconds to wait for response .ft P .fi .UNINDENT .UNINDENT .SH RUNNING THE TESTS .sp There are requirements, in addition to Salt\(aqs requirements, which needs to be installed in order to run the test suite. Install one of the lines below, depending on the relevant Python version: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C pip install \-r dev_requirements_python26.txt pip install \-r dev_requirements_python27.txt .ft P .fi .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 In Salt 0.17, testing libraries were migrated into their own repo. To install them: .INDENT 0.0 .INDENT 3.5 .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C pip install git+https://github.com/saltstack/salt\-testing.git#egg=SaltTesting .ft P .fi .UNINDENT .UNINDENT .UNINDENT .UNINDENT .sp Failure to install SaltTesting will result in import errors similar to the following: .INDENT 0.0 .INDENT 3.5 .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C ImportError: No module named salttesting .ft P .fi .UNINDENT .UNINDENT .UNINDENT .UNINDENT .UNINDENT .UNINDENT .sp Once all require requirements are set, use \fBtests/runtests.py\fP to run the tests, see \fB\-\-help\fP for more info. .sp And alternative way of invoking the tests is available in setup.py, run the tests with the following command: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C \&./setup.py test .ft P .fi .UNINDENT .UNINDENT .sp Examples: .INDENT 0.0 .IP \(bu 2 Run unit tests only: \fBsudo ./tests/runtests.py \-\-unit\-tests\fP .IP \(bu 2 Run a specific set of integration tests only: \fBsudo ./tests/runtests.py \-n integration.modules.virt \-vv\fP .IP \(bu 2 Run a specific set of unit tests only: \fB\&./tests/runtests.py \-n unit.modules.virt_test \-vv\fP .UNINDENT .SS Running The Tests In A Docker Container .sp If the \fBruntests.py\fP binary supports the \fB\-\-docked\fP option flag, you can choose to execute the tests suite under the provided \fI\%docker\fP container. You need to have your \fI\%docker\fP properly configured on your system and the containers need to have access to the internet. .sp Here\(aqs a simple usage example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C tests/runtests.py \-\-docked=ubuntu\-12.04 \-v .ft P .fi .UNINDENT .UNINDENT .sp You can also provide the full \fIdocker\fP container repository: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C tests/runtests.py \-\-docked=salttest/ubuntu\-12.04 \-v .ft P .fi .UNINDENT .UNINDENT .sp The SaltStack team is creating some containers which will have the necessary dependencies pre\-installed allowing you, for example, to run the destructive tests without making a single destructive change to your system, or, to run the tests suite under a different distribution than the one you\(aqre currently using. .sp You can see the current list of test suite images on our \fI\%docker repository\fP\&. .sp If you wish to provide your own \fI\%docker\fP container, you can submit pull requests against our \fI\%docker salt test containers\fP repository. .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. .INDENT 0.0 .IP \(bu 2 \fBWriting unit tests\fP .UNINDENT .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: .INDENT 0.0 .INDENT 3.5 .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 .UNINDENT .UNINDENT .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: .INDENT 0.0 .INDENT 3.5 .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 .UNINDENT .UNINDENT .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: .INDENT 0.0 .INDENT 3.5 .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 .UNINDENT .UNINDENT .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 WRITING UNIT TESTS .SS Introduction .sp Like many software projects, Salt has two broad\-based testing approaches \-\- integration testing and unit testing. While integration testing focuses on the interaction between components in a sandboxed environment, unit testing focuses on the singular implementation of individual functions. .SS Preparing to Write a Unit Test .sp Unit tests live in: \fI\%tests/unit/\fP\&. .sp Most commonly, the following imports are necessary to create a unit test: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C # Import Salt Testing libs from salttesting import skipIf, TestCase from salttesting.helpers import ensure_in_syspath .ft P .fi .UNINDENT .UNINDENT .sp If you need mock support to your tests, please also import: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C from salttesting.mock import NO_MOCK, NO_MOCK_REASON, MagicMock, patch, call .ft P .fi .UNINDENT .UNINDENT .SS A Simple Example .sp Let\(aqs assume that we\(aqre testing a very basic function in an imaginary Salt execution module. Given a module called \fBfib.py\fP that has a function called \(aqcalculate(num_of_results)\(aq, which given a \(aqnum_of_results\(aq, produces a list of sequential Fibonacci numbers of that length. .sp A unit test to test this function might be commonly placed in a file called \fBtests/unit/modules/fib_test.py\fP\&. The convention is to place unit tests for Salt execution modules in \fBtest/unit/modules/\fP and to name the tests module suffixed with \fB_test.py\fP\&. .sp Tests are grouped around test cases, which are logically grouped sets of tests against a piece of functionality in the tested software. Test cases are created as Python classes in the unit test module. To return to our example, here\(aqs how we might write the skeleton for testing \fBfib.py\fP: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C # Import Salt Testing libs from salttesting import TestCase # Import Salt execution module to test from salt.modules import fib # Create test case class and inherit from Salt\(aqs customized TestCase class FibTestCase(TestCase): \(aq\(aq\(aq If we want to set up variables common to all unit tests, we can do so by defining a setUp method, which will be run automatically before tests begin. \(aq\(aq\(aq def setUp(self): # Declare a simple set of five Fibonacci numbers starting at zero that we know are correct. self.fib_five = [0, 1, 1, 2, 3] def test_fib(self): \(aq\(aq\(aq To create a unit test, we should prefix the name with \(gatest_\(aq so that it\(aqs recognized by the test runner. \(aq\(aq\(aq self.assertEqual(fib.calculate(5), self.fib_five) .ft P .fi .UNINDENT .UNINDENT .sp At this point, the test can now be run, either individually or as a part of a full run of the test runner. To ease development, a single test can be executed: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C tests/runtests.py \-n unit.modules.fib_test .ft P .fi .UNINDENT .UNINDENT .sp This will produce output indicating the success or failure of the tests in given test case. For more detailed results, one can also include a flag to increase verbosity: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C tests/runtests.py \-n unit.modules.fib_test \-v .ft P .fi .UNINDENT .UNINDENT .sp To review the results of a particular run, take a note of the log location given in the output for each test: .INDENT 0.0 .INDENT 3.5 \fBLogging tests on /var/folders/nl/d809xbq577l3qrbj3ymtpbq80000gn/T/salt\-runtests.log\fP .UNINDENT .UNINDENT .SS Evaluating Truth .sp A longer discussion on the types of assertions one can make can be found by reading \fI\%Python\(aqs documentation on unit testing\fP\&. .SS Tests Using Mock Objects .sp In many cases, the very purpose of a Salt module is to interact with some external system, whether it be to control a database, manipulate files on a filesystem or many other examples. In these varied cases, it\(aqs necessary to design a unit test which can test the function whilst replacing functions which might actually call out to external systems. One might think of this as "blocking the exits" for code under tests and redirecting the calls to external systems with our own code which produces known results during the duration of the test. .sp To achieve this behavior, Salt makes heavy use of the \fI\%MagicMock package\fP\&. .sp To understand how one might integrate Mock into writing a unit test for Salt, let\(aqs imagine a scenario in which we\(aqre testing an execution module that\(aqs designed to operate on a database. Furthermore, let\(aqs imagine two separate methods, here presented in pseduo\-code in an imaginary execution module called \(aqdb.py. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C def create_user(username): qry = \(aqCREATE USER {0}\(aq.format(username) execute_query(qry) def execute_query(qry): # Connect to a database and actually do the query... .ft P .fi .UNINDENT .UNINDENT .sp Here, let\(aqs imagine that we want to create a unit test for the \fIcreate_user\fP function. In doing so, we want to avoid any calls out to an external system and so while we are running our unit tests, we want to replace the actual interaction with a database with a function that can capture the parameters sent to it and return pre\-defined values. Therefore, our task is clear \-\- to write a unit test which tests the functionality of \fIcreate_user\fP while also replacing \(aqexecute_query\(aq with a mocked function. .sp To begin, we set up the skeleton of our class much like we did before, but with additional imports for MagicMock: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C # Import Salt Testing libs from salttesting import TestCase # Import Salt execution module to test from salt.modules import db # NEW! \-\- Import Mock libraries from salttesting.mock import NO_MOCK, NO_MOCK_REASON, MagicMock, patch, call # Create test case class and inherit from Salt\(aqs customized TestCase @skipIf(NO_MOCK, NO_MOCK_REASON) # Skip this test case if we don\(aqt have access to mock! class DbTestCase(TestCase): def test_create_user(self): # First, we replace \(aqexecute_query\(aq with our own mock function db.execute_query = MagicMock() # Now that the exits are blocked, we can run the function under test. db.create_user(\(aqtestuser\(aq) # We could now query our mock object to see which calls were made to it. ## print db.execute_query.mock_calls \(aq\(aq\(aq We want to test to ensure that the correct query was formed. This is a contrived example, just designed to illustrate the concepts at hand. We\(aqre going to first contruct a call() object that represents the way we expect our mocked execute_query() function to have been called. Then, we\(aqll examine the list of calls that were actually made to to execute_function(). By comparing our expected call to execute_query() with create_user()\(aqs call to execute_query(), we can determine the success or failure of our unit test. \(aq\(aq\(aq expected_call = call(\(aqCREATE USER testuser\(aq) # Do the comparison! Will assert False if execute_query() was not called with the given call db.execute_query.assert_has_calls(expected_call) .ft P .fi .UNINDENT .UNINDENT .SS Modifying \fB__salt__\fP In Place .sp At times, it becomes necessary to make modifications to a module\(aqs view of functions in its own \fB__salt__\fP dictionary. Luckily, this process is quite easy. .sp Below is an example that uses MagicMock\(aqs \fBpatch\fP functionality to insert a function into \fB__salt__\fP that\(aqs actually a MagicMock instance. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C def show_patch(self): with patch.dict(my_module.__salt__, {\(aqfunction.to_replace\(aq: MagicMock()}: # From this scope, carry on with testing, with a modified __salt__! .ft P .fi .UNINDENT .UNINDENT .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 \fBtag\fP\&. Event tags allow for fast top level filtering of events. In addition to the tag, each event has a data structure. This data structure is a dict, which contains information about the event. .SS Mapping Events to Reactor SLS Files .sp Reactor SLS files and event tags are associated in the master config file. By default this is /etc/salt/master, or /etc/salt/master.d/reactor.conf. .sp In the master config section \(aqreactor:\(aq is a list of event tags to be matched and each event tag has a list of reactor SLS files to be run. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C reactor: # Master config section "reactor" \- \(aqsalt/minion/*/start\(aq: # Match tag "salt/minion/*/start" \- /srv/reactor/start.sls # Things to do when a minion starts \- /srv/reactor/monitor.sls # Other things to do \- \(aqsalt/cloud/*/destroyed\(aq: # Globs can be used to matching tags \- /srv/reactor/decommision.sls # Things to do when a server is removed .ft P .fi .UNINDENT .UNINDENT .sp Reactor sls files are similar to state and pillar sls files. They are by default yaml + Jinja templates and are passed familar context variables. .sp They differ because of the addtion of the \fBtag\fP and \fBdata\fP variables. .INDENT 0.0 .IP \(bu 2 The \fBtag\fP variable is just the tag in the fired event. .IP \(bu 2 The \fBdata\fP variable is the event\(aqs data dict. .UNINDENT .sp Here is a simple reactor sls: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C {% if data[\(aqid\(aq] == \(aqmysql1\(aq %} highstate_run: cmd.state.highstate: \- tgt: mysql1 {% endif %} .ft P .fi .UNINDENT .UNINDENT .sp This simple reactor file uses Jinja to further refine the reaction to be made. If the \fBid\fP in the event data is \fBmysql1\fP (in other words, if the name of the minion is \fBmysql1\fP) 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 \fBmysql1\fP minion with a function of \fBstate.highstate\fP\&. Similarly, a runner can be called: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C {% if data[\(aqdata\(aq][\(aqoverstate\(aq] == \(aqrefresh\(aq %} overstate_run: runner.state.over {% endif %} .ft P .fi .UNINDENT .UNINDENT .sp This example will execute the state.overstate runner and initiate an overstate execution. .SS Fire an event .sp To fire an event from a minion call \fBevent.fire_master\fP .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt\-call event.fire_master \(aq{"overstate": "refresh"}\(aq \(aqfoo\(aq .ft P .fi .UNINDENT .UNINDENT .sp After this is called, any reactor sls files matching event tag \fBfoo\fP will execute with \fB{{ data[\(aqdata\(aq][\(aqoverstate\(aq] }}\fP equal to \fB\(aqrefresh\(aq\fP\&. .sp See \fBsalt.modules.event\fP for more information. .SS Knowing what event is being fired .sp Knowing exactly which event is being fired and what data is has for use in the sls files can be challenging. The easiest way to see exactly what\(aqs going on is to use the \fBeventlisten.py\fP script. This script is not part of packages but is part of the source. .sp If the master process is using the default socket, no additional options will be required. Otherwise, you will need to specify the socket location. .sp Example usage: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C wget https://raw.githubusercontent.com/saltstack/salt/develop/tests/eventlisten.py python eventlisten.py # OR python eventlisten.py \-\-sock\-dir /path/to/var/run/salt .ft P .fi .UNINDENT .UNINDENT .sp Example output: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C Event fired at Fri Dec 20 10:43:00 2013 ************************* Tag: salt/auth Data: {\(aq_stamp\(aq: \(aq2013\-12\-20_10:47:54.584699\(aq, \(aqact\(aq: \(aqaccept\(aq, \(aqid\(aq: \(aqfuzzer.domain.tld\(aq, \(aqpub\(aq: \(aq\-\-\-\-\-BEGIN PUBLIC KEY\-\-\-\-\-\enMIICIDANBgk+TRIMMED+EMZ8CAQE=\en\-\-\-\-\-END PUBLIC KEY\-\-\-\-\-\en\(aq, \(aqresult\(aq: True} Event fired at Fri Dec 20 10:43:01 2013 ************************* Tag: salt/minion/fuzzer.domain.tld/start Data: {\(aq_stamp\(aq: \(aq2013\-12\-20_10:43:01.638387\(aq, \(aqcmd\(aq: \(aq_minion_event\(aq, \(aqdata\(aq: \(aqMinion fuzzer.domain.tld started at Fri Dec 20 10:43:01 2013\(aq, \(aqid\(aq: \(aqfuzzer.domain.tld\(aq, \(aqpretag\(aq: None, \(aqtag\(aq: \(aqsalt/minion/fuzzer.domain.tld/start\(aq} .ft P .fi .UNINDENT .UNINDENT .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 files formula 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 \fBLocalClient\fP and the \fBRunners\fP\&. The \fBstate declaration\fP field takes a reference to the function to call in each interface. So to trigger a salt\-run call the \fBstate declaration\fP field will start with \fBrunner\fP, followed by the runner function to call. This means that a call to what would be on the command line \fBsalt\-run manage.up\fP will be \fBrunner.manage.up\fP\&. An example of this in a reactor formula would look like this: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C manage_up: runner.manage.up .ft P .fi .UNINDENT .UNINDENT .sp If the runner takes arguments then they can be specified as well: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C overstate_dev_env: runner.state.over: \- env: dev .ft P .fi .UNINDENT .UNINDENT .sp Executing remote commands maps to the \fBLocalClient\fP interface which is used by the \fBsalt\fP command. This interface more specifically maps to the \fBcmd_async\fP method inside of the \fBLocalClient\fP class. This means that the arguments passed are being passed to the \fBcmd_async\fP method, not the remote method. A field starts with \fBcmd\fP to use the \fBLocalClient\fP subsystem. The result is, to execute a remote command, a reactor fomular would look like this: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C clean_tmp: cmd.cmd.run: \- tgt: \(aq*\(aq \- arg: \- rm \-rf /tmp/* .ft P .fi .UNINDENT .UNINDENT .sp The \fBarg\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: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq cmd.run \(aqrm \-rf /tmp/*\(aq .ft P .fi .UNINDENT .UNINDENT .sp Use the \fBexpr_form\fP argument to specify a matcher: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C clean_tmp: cmd.cmd.run: \- tgt: \(aqos:Ubuntu\(aq \- expr_form: grain \- arg: \- rm \-rf /tmp/* clean_tmp: cmd.cmd.run: \- tgt: \(aqG@roles:hbase_master\(aq \- expr_form: compound \- arg: \- rm \-rf /tmp/* .ft P .fi .UNINDENT .UNINDENT .sp An interesting trick to pass data from the Reactor script to \fBstate.highstate\fP or \fBstate.sls\fP is to pass it as inline Pillar data since both functions take a keyword argument named \fBpillar\fP\&. .sp The following example uses Salt\(aqs Reactor to listen for the event that is fired when the key for a new minion is accepted on the master using \fBsalt\-key\fP\&. .sp \fB/etc/salt/master.d/reactor.conf\fP: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C reactor: \- \(aqsalt/key\(aq: \- /srv/salt/haproxy/react_new_minion.sls .ft P .fi .UNINDENT .UNINDENT .sp The Reactor then fires a \fBstate.sls\fP command targeted to the HAProxy servers and passes the ID of the new minion from the event to the state file via inline Pillar. .sp Note, the Pillar data will need to be passed as a string since that is how it is passed at the CLI. That string will be parsed as YAML on the minion (same as how it works at the CLI). .sp \fB/srv/salt/haproxy/react_new_minion.sls\fP: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C {% if data[\(aqact\(aq] == \(aqaccept\(aq and data[\(aqid\(aq].startswith(\(aqweb\(aq) %} add_new_minion_to_pool: cmd.state.sls: \- tgt: \(aqhaproxy*\(aq \- arg: \- haproxy.refresh_pool \- \(aqpillar={new_minion: {{ data[\(aqid\(aq] }}}\(aq {% endif %} .ft P .fi .UNINDENT .UNINDENT .sp The above command is equivalent to the following command at the CLI: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt \(aqhaproxy*\(aq state.sls haproxy.refresh_pool \(aqpillar={new_minion: minionid}\(aq .ft P .fi .UNINDENT .UNINDENT .sp Finally, that data is available in the state file using the normal Pillar lookup syntax. The following example is grabbing web server names and IP addresses from \fISalt Mine\fP\&. If this state is invoked from the Reactor then the custom Pillar value from above will be available and the new minion will be added to the pool but with the \fBdisabled\fP flag so that HAProxy won\(aqt yet direct traffic to it. .sp \fB/srv/salt/haproxy/refresh_pool.sls\fP: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C {% set new_minion = salt[\(aqpillar.get\(aq](\(aqnew_minion\(aq) %} listen web *:80 balance source {% for server,ip in salt[\(aqmine.get\(aq](\(aqweb*\(aq, \(aqnetwork.interfaces\(aq, [\(aqeth0\(aq]).items() %} {% if server == new_minion %} server {{ server }} {{ ip }}:80 disabled {% else %} server {{ server }} {{ ip }}:80 check {% endif %} {% endfor %} .ft P .fi .UNINDENT .UNINDENT .SS A complete example .sp In this example, we\(aqre going to assume that we have a group of servers that will come online at random and need to have keys automatically accepted. We\(aqll also add that we don\(aqt want all servers being automatically accepted. For this example, we\(aqll assume that all hosts that have an id that starts with \(aqink\(aq will be automatically accepted and have state.highstate executed. On top of thise, we\(aqre going to add that a host coming up that was replaced (meaning a new key) will also be accepted. .sp Our master configuration will be rather simple. All minions that attempte to authenticate will match the \fBtag\fP of \fBsalt/auth\fP\&. When it comes to the minion key being accepted, we get a more refined \fBtag\fP that includes the minion id, which we can use for matching. .sp \fB/etc/salt/master.d/reactor.conf\fP: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C reactor: \- \(aqsalt/auth\(aq: \- /srv/reactor/auth\-pending.sls \- \(aqsalt/minion/ink*/start\(aq: \- /srv/reactor/auth\-complete.sls .ft P .fi .UNINDENT .UNINDENT .sp In this sls file, we say that if the key was rejected we will delete the key on the master and then also tell the master to ssh in to the minion and tell it to restart the minion, since a minion process will die if the key is rejected. .sp We also say that if the key is pending and the id starts with ink we will accept the key. A minion that is waiting on a pending key will retry authentication authentication every ten second by default. .sp \fB/srv/reactor/auth\-pending.sls\fP: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C {# Ink server faild to authenticate \-\- remove accepted key #} {% if not data[\(aqresult\(aq] and data[\(aqid\(aq].startswith(\(aqink\(aq) %} minion_remove: wheel.key.delete: \- match: {{ data[\(aqid\(aq] }} minion_rejoin: cmd.cmd.run: \- tgt: salt\-master.domain.tld \- arg: \- ssh \-o UserKnownHostsFile=/dev/null \-o StrictHostKeyChecking=no "{{ data[\(aqid\(aq] }}" \(aqsleep 10 && /etc/init.d/salt\-minion restart\(aq {% endif %} {# Ink server is sending new key \-\- accept this key #} {% if \(aqact\(aq in data and data[\(aqact\(aq] == \(aqpend\(aq and data[\(aqid\(aq].startswith(\(aqink\(aq) %} minion_add: wheel.key.accept: \- match: {{ data[\(aqid\(aq] }} {% endif %} .ft P .fi .UNINDENT .UNINDENT .sp No if statements are needed here because we already limited this action to just Ink servers in the master configuration. .sp \fB/srv/reactor/auth\-complete.sls\fP: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C {# When an Ink server connects, run state.highstate. #} highstate_run: cmd.state.highstate: \- tgt: {{ data[\(aqid\(aq] }} .ft P .fi .UNINDENT .UNINDENT .SH SALT FORMULAS .sp Formulas are pre\-written Salt States. They are as open\-ended as Salt States themselves and can be used for tasks such as installing a package, configuring and starting a service, setting up users or permissions, and many other common tasks. .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 Formulas require Salt 0.17 or later. .sp More accurately, Formulas are not tested on earlier versions of Salt so your mileage may vary. .sp All Formulas require the grains execution module that shipped with Salt 0.16.4. Earlier Salt versions may copy \fI\%https://github.com/saltstack/salt/blob/develop/salt/modules/grains.py\fP into the \fB/srv/salt/_modules\fP directory and it will be automatically distributed to all minions. .sp Some Formula utilize features added in Salt 0.17 and will not work on earlier Salt versions. .UNINDENT .UNINDENT .sp All official Salt Formulas are found as separate Git repositories in the "saltstack\-formulas" organization on GitHub: .sp \fI\%https://github.com/saltstack\-formulas\fP .sp As an example, quickly install and configure the popular memcached server using sane defaults simply by including the \fBmemcached\-formula\fP repository into an existing Salt States tree. .SS Installation .sp Each Salt Formula is an individual Git repository designed as a drop\-in addition to an existing Salt State tree. Formulas can be installed in the following ways. .SS Adding a Formula as a GitFS remote .sp One design goal of Salt\(aqs GitFS fileserver backend was to facilitate reusable States so this is a quick and natural way to use Formulas. .sp \fBSEE ALSO:\fP .INDENT 0.0 .INDENT 3.5 \fISetting up GitFS\fP .UNINDENT .UNINDENT .INDENT 0.0 .IP 1. 3 Add one or more Formula repository URLs as remotes in the \fBgitfs_remotes\fP list in the Salt Master configuration file. .IP 2. 3 Restart the Salt master. .UNINDENT .SS Adding a Formula directory manually .sp Since Formulas are simply directories they can be copied onto the local file system by using Git to clone the repository or by downloading and expanding a tarball or zip file of the directory. .INDENT 0.0 .IP \(bu 2 Clone the repository manually and add a new entry to \fBfile_roots\fP pointing to the clone\(aqs directory. .IP \(bu 2 Clone the repository manually and then copy or link the Formula directory into \fBfile_roots\fP\&. .UNINDENT .SS Usage .sp Each Formula is intended to be immediately usable with sane defaults without any additional configuration. Many formulas are also configurable by including data in Pillar; see the \fBpillar.example\fP file in each Formula repository for available options. .SS Including a Formula in an existing State tree .sp Formula may be included in an existing \fBsls\fP file. This is often useful when a state you are writing needs to \fBrequire\fP or \fBextend\fP a state defined in the formula. .sp Here is an example of a state that uses the \fBepel\-formula\fP in a \fBrequire\fP declaration which directs Salt to not install the \fBpython26\fP package until after the EPEL repository has also been installed: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C include: \- epel python26: pkg: \- installed \- require: \- pkg: epel .ft P .fi .UNINDENT .UNINDENT .SS Including a Formula from a Top File .sp Some Formula perform completely standalone installations that are not referenced from other state files. It is usually cleanest to include these Formula directly from a Top File. .sp For example the easiest way to set up an OpenStack deployment on a single machine is to include the \fBopenstack\-standalone\-formula\fP directly from a \fBtop.sls\fP file: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C base: \(aqmyopenstackmaster\(aq: \- openstack .ft P .fi .UNINDENT .UNINDENT .sp Quickly deploying OpenStack across several dedicated machines could also be done directly from a Top File and may look something like this: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C base: \(aqcontroller\(aq: \- openstack.horizon \- openstack.keystone \(aqhyper\-*\(aq: \- openstack.nova \- openstack.glance \(aqstorage\-*\(aq: \- openstack.swift .ft P .fi .UNINDENT .UNINDENT .SS Configuring Formula using Pillar .sp Salt Formulas are designed to work out of the box with no additional configuration. However, many Formula support additional configuration and customization through \fIPillar\fP\&. Examples of available options can be found in a file named \fBpillar.example\fP in the root directory of each Formula repository. .SS Modifying default Formula behavior .sp Remember that Formula are regular Salt States and can be used with all Salt\(aqs normal mechanisms for determining execution order. Formula can be required from other States with \fBrequire\fP declarations, they can be modified using \fBextend\fP, they can made to watch other states with \fBwatch_in\fP, they can be used as templates for other States with \fBuse\fP\&. Don\(aqt be shy to read through the source for each Formula! .SS Reporting problems & making additions .sp Each Formula is a separate repository on GitHub. If you encounter a bug with a Formula please file an issue in the respective repository! Send fixes and additions as a pull request. Add tips and tricks to the repository wiki. .SS Writing Formulas .sp Each Formula is a separate repository in the \fI\%saltstack\-formulas\fP organization on GitHub. .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 Get involved creating new Formulas .sp The best way to create new Formula repositories for now is to create a repository in your own account on GitHub and notify a SaltStack employee when it is ready. We will add you as a collaborator on the \fI\%saltstack\-formulas\fP organization and help you transfer the repository over. Ping a SaltStack employee on IRC (\fB#salt\fP on Freenode) or send an email to the Salt mailing list. .UNINDENT .UNINDENT .SS Repository structure .sp A basic Formula repository should have the following layout: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C foo\-formula |\-\- foo/ | |\-\- map.jinja | |\-\- init.sls | \(ga\-\- bar.sls |\-\- CHANGELOG.rst |\-\- LICENSE |\-\- pillar.example |\-\- README.rst \(ga\-\- VERSION .ft P .fi .UNINDENT .UNINDENT .sp \fBSEE ALSO:\fP .INDENT 0.0 .INDENT 3.5 \fBtemplate\-formula\fP .sp The \fBtemplate\-formula\fP repository has a pre\-built layout that serves as the basic structure for a new formula repository. Just copy the files from there and edit them. .UNINDENT .UNINDENT .SS \fBREADME.rst\fP .sp The README should detail each available \fB\&.sls\fP file by explaining what it does, whether it has any dependencies on other formulas, whether it has a target platform, and any other installation or usage instructions or tips. .sp A sample skeleton for the \fBREADME.rst\fP file: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C foo === Install and configure the FOO service. \&.. note:: See the full \(gaSalt Formulas installation and usage instructions \(ga_. Available states \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- \(ga\(gafoo\(ga\(ga Install the \(ga\(gafoo\(ga\(ga package and enable the service. \(ga\(gafoo.bar\(ga\(ga Install the \(ga\(gabar\(ga\(ga package. .ft P .fi .UNINDENT .UNINDENT .SS \fBCHANGELOG.rst\fP .sp The \fBCHANGELOG.rst\fP file should detail the individual versions, their release date and a set of bullet points for each version highlighting the overall changes in a given version of the formula. .sp A sample skeleton for the \fICHANGELOG.rst\fP file: .sp \fBCHANGELOG.rst\fP: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C foo formula =========== 0.0.2 (2013\-01\-01) \- Re\-organized formula file layout \- Fixed filename used for upstart logger template \- Allow for pillar message to have default if none specified .ft P .fi .UNINDENT .UNINDENT .SS \fBmap.jinja\fP .sp It is useful to have a single source for platform\-specific or other parameterized information that can be reused throughout a Formula. See "\fIconventions\-formula\-parameterization\fP" below for more information. Such a file should be named \fBmap.jinja\fP and live alongside the state files. .sp The following is an example from the MySQL Formula that has been slightly modified to be more readable and less terse. .sp In essence, it is a simple dictionary that serves as a lookup table. The \fBgrains.filter_by\fP function then does a lookup on that table using the \fBos_family\fP grain (by default) and sets the result to a variable that can be used throughout the formula. .sp \fBSEE ALSO:\fP .INDENT 0.0 .INDENT 3.5 \fBgrains.filter_by\fP .UNINDENT .UNINDENT .sp \fBmap.jinja\fP: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C {% set mysql_lookup_table = { \(aqDebian\(aq: { \(aqserver\(aq: \(aqmysql\-server\(aq, \(aqclient\(aq: \(aqmysql\-client\(aq, \(aqservice\(aq: \(aqmysql\(aq, \(aqconfig\(aq: \(aq/etc/mysql/my.cnf\(aq, }, \(aqRedHat\(aq: { \(aqserver\(aq: \(aqmysql\-server\(aq, \(aqclient\(aq: \(aqmysql\(aq, \(aqservice\(aq: \(aqmysqld\(aq, \(aqconfig\(aq: \(aq/etc/my.cnf\(aq, }, \(aqGentoo\(aq: { \(aqserver\(aq: \(aqdev\-db/mysql\(aq, \(aqmysql\-client\(aq: \(aqdev\-db/mysql\(aq, \(aqservice\(aq: \(aqmysql\(aq, \(aqconfig\(aq: \(aq/etc/mysql/my.cnf\(aq, }, } %} {% set mysql = salt[\(aqgrains.filter_by\(aq](mysql_lookup_table, merge=salt[\(aqpillar.get\(aq](\(aqmysql:lookup\(aq)) .ft P .fi .UNINDENT .UNINDENT .sp The above example is used to help explain how the mapping works. In most map files you will see the following structure: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C {% set mysql = salt[\(aqgrains.filter_by\(aq]({ \(aqDebian\(aq: { \(aqserver\(aq: \(aqmysql\-server\(aq, \(aqclient\(aq: \(aqmysql\-client\(aq, \(aqservice\(aq: \(aqmysql\(aq, \(aqconfig\(aq: \(aq/etc/mysql/my.cnf\(aq, \(aqpython\(aq: \(aqpython\-mysqldb\(aq, }, \(aqRedHat\(aq: { \(aqserver\(aq: \(aqmysql\-server\(aq, \(aqclient\(aq: \(aqmysql\(aq, \(aqservice\(aq: \(aqmysqld\(aq, \(aqconfig\(aq: \(aq/etc/my.cnf\(aq, \(aqpython\(aq: \(aqMySQL\-python\(aq, }, \(aqGentoo\(aq: { \(aqserver\(aq: \(aqdev\-db/mysql\(aq, \(aqmysql\-client\(aq: \(aqdev\-db/mysql\(aq, \(aqservice\(aq: \(aqmysql\(aq, \(aqconfig\(aq: \(aq/etc/mysql/my.cnf\(aq, \(aqpython\(aq: \(aqdev\-python/mysql\-python\(aq, }, }, merge=salt[\(aqpillar.get\(aq](\(aqmysql:lookup\(aq)) %} .ft P .fi .UNINDENT .UNINDENT .sp The \fBmerge\fP keyword specifies the location of a dictionary in Pillar that can be used to override values returned from the lookup table. If the value exists in Pillar it will take precedence, otherwise \fBmerge\fP will be ignored. This is useful when software or configuration files is installed to non\-standard locations. For example, the following Pillar would replace the \fBconfig\fP value from the call above. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C mysql: lookup: config: /usr/local/etc/mysql/my.cnf .ft P .fi .UNINDENT .UNINDENT .sp Any of the values defined above can be fetched for the current platform in any state file using the following syntax: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C {% from "mysql/map.jinja" import mysql with context %} mysql\-server: pkg: \- installed \- name: {{ mysql.server }} service: \- running \- name: {{ mysql.service }} \- require: \- pkg: mysql\-server mysql\-config: file: \- managed \- name: {{ mysql.config }} \- source: salt://mysql/conf/my.cnf \- watch: \- service: mysql\-server .ft P .fi .UNINDENT .UNINDENT .SS SLS files .sp Each state in a Formula should use sane defaults (as much as is possible) and use Pillar to allow for customization. .sp The root state, in particular, and most states in general, should strive to do no more than the basic expected thing and advanced configuration should be put in child states build on top of the basic states. .sp For example, the root Apache should only install the Apache httpd server and make sure the httpd service is running. It can then be used by more advanced states: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C # apache/init.sls httpd: pkg: \- installed service: \- running # apache/mod_wsgi.sls include: \- apache mod_wsgi: pkg: \- installed \- require: \- pkg: apache # apache/debian/vhost_setup.sls {% if grains[\(aqos_family\(aq] == \(aqDebian\(aq %} a2dissite 000\-default: cmd.run: \- onlyif: test \-L /etc/apache2/sites\-enabled/000\-default \- require: \- pkg: apache {% endif %} .ft P .fi .UNINDENT .UNINDENT .SS Platform agnostic .sp Each Salt Formula must be able to be run without error on any platform. If the formula is not applicable to a platform it should do nothing. See the \fBepel\-formula\fP for an example. .sp Any platform\-specific states must be wrapped in conditional statements: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C {% if grains[\(aqos_family\(aq] == \(aqDebian\(aq %} \&... {% endif %} .ft P .fi .UNINDENT .UNINDENT .sp A handy method for using platform\-specific values is to create a lookup table using the \fBfilter_by()\fP function: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C {% set apache = salt[\(aqgrains.filter_by\(aq]({ \(aqDebian\(aq: {\(aqconf\(aq: \(aq/etc/apache2/conf.d\(aq}, \(aqRedHat\(aq: {\(aqconf\(aq: \(aq/etc/httpd/conf.d\(aq}, }) %} myconf: file: \- managed \- name: {{ apache.conf }}/myconf.conf .ft P .fi .UNINDENT .UNINDENT .SS Configuration and parameterization .sp Each Formula should strive for sane defaults that can then be customized using Pillar. Pillar lookups must use the safe \fBget()\fP and must provide a default value: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C {% if salt[\(aqpillar.get\(aq](\(aqhorizon:use_ssl\(aq, False) %} ssl_crt: {{ salt[\(aqpillar.get\(aq](\(aqhorizon:ssl_crt\(aq, \(aq/etc/ssl/certs/horizon.crt\(aq) }} ssl_key: {{ salt[\(aqpillar.get\(aq](\(aqhorizon:ssl_key\(aq, \(aq/etc/ssl/certs/horizon.key\(aq) }} {% endif %} .ft P .fi .UNINDENT .UNINDENT .sp Any default values used in the Formula must also be documented in the \fBpillar.example\fP file in the root of the repository. Comments should be used liberally to explain the intent of each configuration value. In addition, users should be able copy\-and\-paste the contents of this file into their own Pillar to make any desired changes. .SS Scripting .sp Remember that both State files and Pillar files can easily call out to Salt \fIexecution modules\fP and have access to all the system grains as well. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C {% if \(aq/storage\(aq in salt[\(aqmount.active\(aq]() %} /usr/local/etc/myfile.conf: file: \- symlink \- target: /storage/myfile.conf {% endif %} .ft P .fi .UNINDENT .UNINDENT .sp Jinja macros are generally discouraged in favor of adding functions to existing Salt modules or adding new modules. An example of this is the \fBfilter_by()\fP function. .SS Versioning .sp Formula are versioned according to Semantic Versioning, \fI\%http://semver.org/\fP\&. .INDENT 0.0 .INDENT 3.5 Given a version number MAJOR.MINOR.PATCH, increment the: .INDENT 0.0 .IP 1. 3 MAJOR version when you make incompatible API changes, .IP 2. 3 MINOR version when you add functionality in a backwards\-compatible manner, and .IP 3. 3 PATCH version when you make backwards\-compatible bug fixes. .UNINDENT .sp Additional labels for pre\-release and build metadata are available as extensions to the MAJOR.MINOR.PATCH format. .UNINDENT .UNINDENT .sp Formula versions are tracked using Git tags as well as the \fBVERSION\fP file in the formula repository. The \fBVERSION\fP file should contain the currently released version of the particular formula. .SS Testing Formulas .sp Salt Formulas are tested by running each \fB\&.sls\fP file via \fBstate.sls\fP and checking the output for success or failure. This is done for each supported platform. .SH SALT CONVENTIONS .SS Salt Formulas .sp Formulas are pre\-written Salt States. They are as open\-ended as Salt States themselves and can be used for tasks such as installing a package, configuring and starting a service, setting up users or permissions, and many other common tasks. .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 Formulas require Salt 0.17 or later. .sp More accurately, Formulas are not tested on earlier versions of Salt so your mileage may vary. .sp All Formulas require the grains execution module that shipped with Salt 0.16.4. Earlier Salt versions may copy \fI\%https://github.com/saltstack/salt/blob/develop/salt/modules/grains.py\fP into the \fB/srv/salt/_modules\fP directory and it will be automatically distributed to all minions. .sp Some Formula utilize features added in Salt 0.17 and will not work on earlier Salt versions. .UNINDENT .UNINDENT .sp All official Salt Formulas are found as separate Git repositories in the "saltstack\-formulas" organization on GitHub: .sp \fI\%https://github.com/saltstack\-formulas\fP .sp As an example, quickly install and configure the popular memcached server using sane defaults simply by including the \fBmemcached\-formula\fP repository into an existing Salt States tree. .SS Installation .sp Each Salt Formula is an individual Git repository designed as a drop\-in addition to an existing Salt State tree. Formulas can be installed in the following ways. .SS Adding a Formula as a GitFS remote .sp One design goal of Salt\(aqs GitFS fileserver backend was to facilitate reusable States so this is a quick and natural way to use Formulas. .sp \fBSEE ALSO:\fP .INDENT 0.0 .INDENT 3.5 \fISetting up GitFS\fP .UNINDENT .UNINDENT .INDENT 0.0 .IP 1. 3 Add one or more Formula repository URLs as remotes in the \fBgitfs_remotes\fP list in the Salt Master configuration file. .IP 2. 3 Restart the Salt master. .UNINDENT .SS Adding a Formula directory manually .sp Since Formulas are simply directories they can be copied onto the local file system by using Git to clone the repository or by downloading and expanding a tarball or zip file of the directory. .INDENT 0.0 .IP \(bu 2 Clone the repository manually and add a new entry to \fBfile_roots\fP pointing to the clone\(aqs directory. .IP \(bu 2 Clone the repository manually and then copy or link the Formula directory into \fBfile_roots\fP\&. .UNINDENT .SS Usage .sp Each Formula is intended to be immediately usable with sane defaults without any additional configuration. Many formulas are also configurable by including data in Pillar; see the \fBpillar.example\fP file in each Formula repository for available options. .SS Including a Formula in an existing State tree .sp Formula may be included in an existing \fBsls\fP file. This is often useful when a state you are writing needs to \fBrequire\fP or \fBextend\fP a state defined in the formula. .sp Here is an example of a state that uses the \fBepel\-formula\fP in a \fBrequire\fP declaration which directs Salt to not install the \fBpython26\fP package until after the EPEL repository has also been installed: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C include: \- epel python26: pkg: \- installed \- require: \- pkg: epel .ft P .fi .UNINDENT .UNINDENT .SS Including a Formula from a Top File .sp Some Formula perform completely standalone installations that are not referenced from other state files. It is usually cleanest to include these Formula directly from a Top File. .sp For example the easiest way to set up an OpenStack deployment on a single machine is to include the \fBopenstack\-standalone\-formula\fP directly from a \fBtop.sls\fP file: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C base: \(aqmyopenstackmaster\(aq: \- openstack .ft P .fi .UNINDENT .UNINDENT .sp Quickly deploying OpenStack across several dedicated machines could also be done directly from a Top File and may look something like this: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C base: \(aqcontroller\(aq: \- openstack.horizon \- openstack.keystone \(aqhyper\-*\(aq: \- openstack.nova \- openstack.glance \(aqstorage\-*\(aq: \- openstack.swift .ft P .fi .UNINDENT .UNINDENT .SS Configuring Formula using Pillar .sp Salt Formulas are designed to work out of the box with no additional configuration. However, many Formula support additional configuration and customization through \fIPillar\fP\&. Examples of available options can be found in a file named \fBpillar.example\fP in the root directory of each Formula repository. .SS Modifying default Formula behavior .sp Remember that Formula are regular Salt States and can be used with all Salt\(aqs normal mechanisms for determining execution order. Formula can be required from other States with \fBrequire\fP declarations, they can be modified using \fBextend\fP, they can made to watch other states with \fBwatch_in\fP, they can be used as templates for other States with \fBuse\fP\&. Don\(aqt be shy to read through the source for each Formula! .SS Reporting problems & making additions .sp Each Formula is a separate repository on GitHub. If you encounter a bug with a Formula please file an issue in the respective repository! Send fixes and additions as a pull request. Add tips and tricks to the repository wiki. .SS Writing Formulas .sp Each Formula is a separate repository in the \fI\%saltstack\-formulas\fP organization on GitHub. .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 Get involved creating new Formulas .sp The best way to create new Formula repositories for now is to create a repository in your own account on GitHub and notify a SaltStack employee when it is ready. We will add you as a collaborator on the \fI\%saltstack\-formulas\fP organization and help you transfer the repository over. Ping a SaltStack employee on IRC (\fB#salt\fP on Freenode) or send an email to the Salt mailing list. .UNINDENT .UNINDENT .SS Repository structure .sp A basic Formula repository should have the following layout: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C foo\-formula |\-\- foo/ | |\-\- map.jinja | |\-\- init.sls | \(ga\-\- bar.sls |\-\- CHANGELOG.rst |\-\- LICENSE |\-\- pillar.example |\-\- README.rst \(ga\-\- VERSION .ft P .fi .UNINDENT .UNINDENT .sp \fBSEE ALSO:\fP .INDENT 0.0 .INDENT 3.5 \fBtemplate\-formula\fP .sp The \fBtemplate\-formula\fP repository has a pre\-built layout that serves as the basic structure for a new formula repository. Just copy the files from there and edit them. .UNINDENT .UNINDENT .SS \fBREADME.rst\fP .sp The README should detail each available \fB\&.sls\fP file by explaining what it does, whether it has any dependencies on other formulas, whether it has a target platform, and any other installation or usage instructions or tips. .sp A sample skeleton for the \fBREADME.rst\fP file: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C foo === Install and configure the FOO service. \&.. note:: See the full \(gaSalt Formulas installation and usage instructions \(ga_. Available states \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- \(ga\(gafoo\(ga\(ga Install the \(ga\(gafoo\(ga\(ga package and enable the service. \(ga\(gafoo.bar\(ga\(ga Install the \(ga\(gabar\(ga\(ga package. .ft P .fi .UNINDENT .UNINDENT .SS \fBCHANGELOG.rst\fP .sp The \fBCHANGELOG.rst\fP file should detail the individual versions, their release date and a set of bullet points for each version highlighting the overall changes in a given version of the formula. .sp A sample skeleton for the \fICHANGELOG.rst\fP file: .sp \fBCHANGELOG.rst\fP: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C foo formula =========== 0.0.2 (2013\-01\-01) \- Re\-organized formula file layout \- Fixed filename used for upstart logger template \- Allow for pillar message to have default if none specified .ft P .fi .UNINDENT .UNINDENT .SS \fBmap.jinja\fP .sp It is useful to have a single source for platform\-specific or other parameterized information that can be reused throughout a Formula. See "\fIconventions\-formula\-parameterization\fP" below for more information. Such a file should be named \fBmap.jinja\fP and live alongside the state files. .sp The following is an example from the MySQL Formula that has been slightly modified to be more readable and less terse. .sp In essence, it is a simple dictionary that serves as a lookup table. The \fBgrains.filter_by\fP function then does a lookup on that table using the \fBos_family\fP grain (by default) and sets the result to a variable that can be used throughout the formula. .sp \fBSEE ALSO:\fP .INDENT 0.0 .INDENT 3.5 \fBgrains.filter_by\fP .UNINDENT .UNINDENT .sp \fBmap.jinja\fP: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C {% set mysql_lookup_table = { \(aqDebian\(aq: { \(aqserver\(aq: \(aqmysql\-server\(aq, \(aqclient\(aq: \(aqmysql\-client\(aq, \(aqservice\(aq: \(aqmysql\(aq, \(aqconfig\(aq: \(aq/etc/mysql/my.cnf\(aq, }, \(aqRedHat\(aq: { \(aqserver\(aq: \(aqmysql\-server\(aq, \(aqclient\(aq: \(aqmysql\(aq, \(aqservice\(aq: \(aqmysqld\(aq, \(aqconfig\(aq: \(aq/etc/my.cnf\(aq, }, \(aqGentoo\(aq: { \(aqserver\(aq: \(aqdev\-db/mysql\(aq, \(aqmysql\-client\(aq: \(aqdev\-db/mysql\(aq, \(aqservice\(aq: \(aqmysql\(aq, \(aqconfig\(aq: \(aq/etc/mysql/my.cnf\(aq, }, } %} {% set mysql = salt[\(aqgrains.filter_by\(aq](mysql_lookup_table, merge=salt[\(aqpillar.get\(aq](\(aqmysql:lookup\(aq)) .ft P .fi .UNINDENT .UNINDENT .sp The above example is used to help explain how the mapping works. In most map files you will see the following structure: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C {% set mysql = salt[\(aqgrains.filter_by\(aq]({ \(aqDebian\(aq: { \(aqserver\(aq: \(aqmysql\-server\(aq, \(aqclient\(aq: \(aqmysql\-client\(aq, \(aqservice\(aq: \(aqmysql\(aq, \(aqconfig\(aq: \(aq/etc/mysql/my.cnf\(aq, \(aqpython\(aq: \(aqpython\-mysqldb\(aq, }, \(aqRedHat\(aq: { \(aqserver\(aq: \(aqmysql\-server\(aq, \(aqclient\(aq: \(aqmysql\(aq, \(aqservice\(aq: \(aqmysqld\(aq, \(aqconfig\(aq: \(aq/etc/my.cnf\(aq, \(aqpython\(aq: \(aqMySQL\-python\(aq, }, \(aqGentoo\(aq: { \(aqserver\(aq: \(aqdev\-db/mysql\(aq, \(aqmysql\-client\(aq: \(aqdev\-db/mysql\(aq, \(aqservice\(aq: \(aqmysql\(aq, \(aqconfig\(aq: \(aq/etc/mysql/my.cnf\(aq, \(aqpython\(aq: \(aqdev\-python/mysql\-python\(aq, }, }, merge=salt[\(aqpillar.get\(aq](\(aqmysql:lookup\(aq)) %} .ft P .fi .UNINDENT .UNINDENT .sp The \fBmerge\fP keyword specifies the location of a dictionary in Pillar that can be used to override values returned from the lookup table. If the value exists in Pillar it will take precedence, otherwise \fBmerge\fP will be ignored. This is useful when software or configuration files is installed to non\-standard locations. For example, the following Pillar would replace the \fBconfig\fP value from the call above. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C mysql: lookup: config: /usr/local/etc/mysql/my.cnf .ft P .fi .UNINDENT .UNINDENT .sp Any of the values defined above can be fetched for the current platform in any state file using the following syntax: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C {% from "mysql/map.jinja" import mysql with context %} mysql\-server: pkg: \- installed \- name: {{ mysql.server }} service: \- running \- name: {{ mysql.service }} \- require: \- pkg: mysql\-server mysql\-config: file: \- managed \- name: {{ mysql.config }} \- source: salt://mysql/conf/my.cnf \- watch: \- service: mysql\-server .ft P .fi .UNINDENT .UNINDENT .SS SLS files .sp Each state in a Formula should use sane defaults (as much as is possible) and use Pillar to allow for customization. .sp The root state, in particular, and most states in general, should strive to do no more than the basic expected thing and advanced configuration should be put in child states build on top of the basic states. .sp For example, the root Apache should only install the Apache httpd server and make sure the httpd service is running. It can then be used by more advanced states: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C # apache/init.sls httpd: pkg: \- installed service: \- running # apache/mod_wsgi.sls include: \- apache mod_wsgi: pkg: \- installed \- require: \- pkg: apache # apache/debian/vhost_setup.sls {% if grains[\(aqos_family\(aq] == \(aqDebian\(aq %} a2dissite 000\-default: cmd.run: \- onlyif: test \-L /etc/apache2/sites\-enabled/000\-default \- require: \- pkg: apache {% endif %} .ft P .fi .UNINDENT .UNINDENT .SS Platform agnostic .sp Each Salt Formula must be able to be run without error on any platform. If the formula is not applicable to a platform it should do nothing. See the \fBepel\-formula\fP for an example. .sp Any platform\-specific states must be wrapped in conditional statements: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C {% if grains[\(aqos_family\(aq] == \(aqDebian\(aq %} \&... {% endif %} .ft P .fi .UNINDENT .UNINDENT .sp A handy method for using platform\-specific values is to create a lookup table using the \fBfilter_by()\fP function: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C {% set apache = salt[\(aqgrains.filter_by\(aq]({ \(aqDebian\(aq: {\(aqconf\(aq: \(aq/etc/apache2/conf.d\(aq}, \(aqRedHat\(aq: {\(aqconf\(aq: \(aq/etc/httpd/conf.d\(aq}, }) %} myconf: file: \- managed \- name: {{ apache.conf }}/myconf.conf .ft P .fi .UNINDENT .UNINDENT .SS Configuration and parameterization .sp Each Formula should strive for sane defaults that can then be customized using Pillar. Pillar lookups must use the safe \fBget()\fP and must provide a default value: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C {% if salt[\(aqpillar.get\(aq](\(aqhorizon:use_ssl\(aq, False) %} ssl_crt: {{ salt[\(aqpillar.get\(aq](\(aqhorizon:ssl_crt\(aq, \(aq/etc/ssl/certs/horizon.crt\(aq) }} ssl_key: {{ salt[\(aqpillar.get\(aq](\(aqhorizon:ssl_key\(aq, \(aq/etc/ssl/certs/horizon.key\(aq) }} {% endif %} .ft P .fi .UNINDENT .UNINDENT .sp Any default values used in the Formula must also be documented in the \fBpillar.example\fP file in the root of the repository. Comments should be used liberally to explain the intent of each configuration value. In addition, users should be able copy\-and\-paste the contents of this file into their own Pillar to make any desired changes. .SS Scripting .sp Remember that both State files and Pillar files can easily call out to Salt \fIexecution modules\fP and have access to all the system grains as well. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C {% if \(aq/storage\(aq in salt[\(aqmount.active\(aq]() %} /usr/local/etc/myfile.conf: file: \- symlink \- target: /storage/myfile.conf {% endif %} .ft P .fi .UNINDENT .UNINDENT .sp Jinja macros are generally discouraged in favor of adding functions to existing Salt modules or adding new modules. An example of this is the \fBfilter_by()\fP function. .SS Versioning .sp Formula are versioned according to Semantic Versioning, \fI\%http://semver.org/\fP\&. .INDENT 0.0 .INDENT 3.5 Given a version number MAJOR.MINOR.PATCH, increment the: .INDENT 0.0 .IP 1. 3 MAJOR version when you make incompatible API changes, .IP 2. 3 MINOR version when you add functionality in a backwards\-compatible manner, and .IP 3. 3 PATCH version when you make backwards\-compatible bug fixes. .UNINDENT .sp Additional labels for pre\-release and build metadata are available as extensions to the MAJOR.MINOR.PATCH format. .UNINDENT .UNINDENT .sp Formula versions are tracked using Git tags as well as the \fBVERSION\fP file in the formula repository. The \fBVERSION\fP file should contain the currently released version of the particular formula. .SS Testing Formulas .sp Salt Formulas are tested by running each \fB\&.sls\fP file via \fBstate.sls\fP and checking the output for success or failure. This is done for each supported platform. .SS SaltStack Packaging Guide .sp Since Salt provides a powerful toolkit for system management and automation, the package can be spit into a number of sub\-tools. While packaging Salt as a single package containing all components is perfectly acceptable, the split packages should follow this convention. .SS Source Files .sp Release packages should always be built from the source tarball distributed via pypi. Release packages should \fINEVER\fP use a git checkout as the source for distribution. .SS Single Package .sp Shipping Salt as a single package, where the minion, master and all tools are together is perfectly acceptable and practiced by distributions such as FreeBSD. .SS Split Package .sp Salt Should always be split in a standard way, with standard dependencies, this lowers cross distribution confusion about what components are going to be shipped with specific packages. These packages can be defined from the Salt Source as of Salt 0.17.0: .SS Salt Common .sp The \fIsalt\-common\fP or \fIsalt\fP package should contain the files provided by the salt python package, or all files distributed from the \fBsalt/\fP directory in the source distribution packages. The documentation contained under the \fBdoc/\fP directory can be a part of this package but splitting out a doc package is preferred. Since salt\-call is the entry point to utilize the libs and is useful for all salt packages it is included in the salt\-common package. .SS Name .INDENT 0.0 .IP \(bu 2 \fIsalt\fP OR \fIsalt\-common\fP .UNINDENT .SS Files .INDENT 0.0 .IP \(bu 2 \fIsalt/*\fP .IP \(bu 2 \fIman/salt.7\fP .IP \(bu 2 \fIscripts/salt\-call\fP .IP \(bu 2 \fItests/*\fP .IP \(bu 2 \fIman/salt\-call.1\fP .UNINDENT .SS Depends .INDENT 0.0 .IP \(bu 2 \fIPython 2.6\-2.7\fP .IP \(bu 2 \fIPyYAML\fP .IP \(bu 2 \fIJinja2\fP .UNINDENT .SS Salt Master .sp The \fIsalt\-master\fP package contains the applicable scripts, related man pages and init information for the given platform. .SS Name .INDENT 0.0 .IP \(bu 2 \fIsalt\-master\fP .UNINDENT .SS Files .INDENT 0.0 .IP \(bu 2 \fIscripts/salt\-master\fP .IP \(bu 2 \fIscripts/salt\fP .IP \(bu 2 \fIscripts/salt\-run\fP .IP \(bu 2 \fIscripts/salt\-key\fP .IP \(bu 2 \fIscripts/salt\-cp\fP .IP \(bu 2 \fIpkg/\fP .IP \(bu 2 \fIman/salt.1\fP .IP \(bu 2 \fIman/salt\-master.1\fP .IP \(bu 2 \fIman/salt\-run.1\fP .IP \(bu 2 \fIman/salt\-key.1\fP .IP \(bu 2 \fIman/salt\-cp.1\fP .IP \(bu 2 \fIconf/master\fP .UNINDENT .SS Depends .INDENT 0.0 .IP \(bu 2 \fISalt Common\fP .IP \(bu 2 \fIZeroMQ\fP >= 3.2 .IP \(bu 2 \fIPyZMQ\fP >= 2.10 .IP \(bu 2 \fIPyCrypto\fP .IP \(bu 2 \fIM2Crypto\fP .IP \(bu 2 \fIPython MessagePack\fP (Messagepack C lib, or msgpack\-pure) .UNINDENT .SS Salt Syndic .sp The Salt Syndic package can be rolled completely into the Salt Master package. Platforms which start services as part of the package deployment need to maintain a separate \fIsalt\-syndic\fP package (primarily Debian based platforms). .sp The Syndic may optionally not depend on the anything more than the Salt Master since the master will bring in all needed dependencies, but fall back to the platform specific packaging guidelines. .SS Name .INDENT 0.0 .IP \(bu 2 \fIsalt\-syndic\fP .UNINDENT .SS Files .INDENT 0.0 .IP \(bu 2 \fIscripts/salt\-syndic\fP .IP \(bu 2 \fIpkg/\fP .IP \(bu 2 \fIman/salt\-syndic.1\fP .UNINDENT .SS Depends .INDENT 0.0 .IP \(bu 2 \fISalt Common\fP .IP \(bu 2 \fISalt Master\fP .IP \(bu 2 \fIZeroMQ\fP >= 3.2 .IP \(bu 2 \fIPyZMQ\fP >= 2.10 .IP \(bu 2 \fIPyCrypto\fP .IP \(bu 2 \fIM2Crypto\fP .IP \(bu 2 \fIPython MessagePack\fP (Messagepack C lib, or msgpack\-pure) .UNINDENT .SS Salt Minion .sp The Minion is a standalone package and should not be split beyond the \fIsalt\-minion\fP and \fIsalt\-common\fP packages. .SS Name .INDENT 0.0 .IP \(bu 2 \fIsalt\-minion\fP .UNINDENT .SS Files .INDENT 0.0 .IP \(bu 2 \fIscripts/salt\-minion\fP .IP \(bu 2 \fIpkg/\fP .IP \(bu 2 \fIman/salt\-minion.1\fP .IP \(bu 2 \fIconf/minion\fP .UNINDENT .SS Depends .INDENT 0.0 .IP \(bu 2 \fISalt Common\fP .IP \(bu 2 \fIZeroMQ\fP >= 3.2 .IP \(bu 2 \fIPyZMQ\fP >= 2.10 .IP \(bu 2 \fIPyCrypto\fP .IP \(bu 2 \fIM2Crypto\fP .IP \(bu 2 \fIPython MessagePack\fP (Messagepack C lib, or msgpack\-pure) .UNINDENT .SS Salt SSH .sp Since Salt SSH does not require the same dependencies as the minion and master, it should be split out. .SS Name .INDENT 0.0 .IP \(bu 2 \fIsalt\-ssh\fP .UNINDENT .SS Files .INDENT 0.0 .IP \(bu 2 \fIscripts/salt\-ssh\fP .IP \(bu 2 \fIman/salt\-ssh.1\fP .UNINDENT .SS Depends .INDENT 0.0 .IP \(bu 2 \fISalt Common\fP .IP \(bu 2 \fIsshpass\fP .IP \(bu 2 \fIPython MessagePack\fP (Messagepack C lib, or msgpack\-pure) .UNINDENT .SS Salt Doc .sp The documentation package is very distribution optional. A completely split package will split out the documentation, but some platform conventions do not prefer this. If the documentation is not split out, it should be included with the \fISalt Common\fP package. .SS Name .INDENT 0.0 .IP \(bu 2 \fIsalt\-doc\fP .UNINDENT .SS Files .INDENT 0.0 .IP \(bu 2 \fIdoc/*\fP .UNINDENT .SS Optional Depends .INDENT 0.0 .IP \(bu 2 \fISalt Common\fP .IP \(bu 2 \fIPython Sphinx\fP .IP \(bu 2 \fIMake\fP .UNINDENT .SS Salt Release Process .sp The goal for Salt projects is to cut a new feature release every four to six weeks. This document outlines the process for these releases, and the subsequent bug fix releases which follow. .SS Feature Release Process .sp When a new release is ready to be cut, the person responsible for cutting the release will follow the following steps (written using the 0.16 release as an example): .INDENT 0.0 .IP 1. 3 All open issues on the release milestone should be moved to the next release milestone. (e.g. from the \fB0.16\fP milestone to the \fB0.17\fP milestone) .IP 2. 3 Release notes should be created documenting the major new features and bugfixes in the release. .IP 3. 3 Create an annotated tag with only the major and minor version numbers, preceded by the letter \fBv\fP\&. (e.g. \fBv0.16\fP) This tag will reside on the \fBdevelop\fP branch. .IP 4. 3 Create a branch for the new release, using only the major and minor version numbers. (e.g. \fB0.16\fP) .IP 5. 3 On this new branch, create an annotated tag for the first revision release, which is generally a release candidate. It should be preceded by the letter \fBv\fP\&. (e.g. \fBv0.16.0RC\fP) .IP 6. 3 The release should be packaged from this annotated tag and uploaded to PyPI. .IP 7. 3 The packagers should be notified on the \fBsalt\-packagers\fP mailing list so they can create packages for all the major operating systems. (note that release candidates should go in the testing repositories) .IP 8. 3 After the packagers have been given a few days to compile the packages, the release is announced on the \fBsalt\-users\fP mailing list. .IP 9. 3 Log into RTD and add the new release there. (Have to do it manually) .UNINDENT .SS Maintenance and Bugfix Releases .sp Once a release has been cut, regular cherry\-picking sessions should begin to cherry\-pick any bugfixes from the \fBdevelop\fP branch to the release branch (e.g. \fB0.16\fP). Once major bugs have been fixes and cherry\-picked, a bugfix release can be cut: .INDENT 0.0 .IP 1. 3 On the release branch (i.e. \fB0.16\fP), create an annotated tag for the revision release. It should be preceded by the letter \fBv\fP\&. (e.g. \fBv0.16.2\fP) Release candidates are unnecessary for bugfix releases. .IP 2. 3 The release should be packaged from this annotated tag and uploaded to PyPI. .IP 3. 3 The packagers should be notified on the \fBsalt\-packagers\fP mailing list so they can create packages for all the major operating systems. .IP 4. 3 After the packagers have been given a few days to compile the packages, the release is announced on the \fBsalt\-users\fP mailing list. .UNINDENT .SS Salt Coding Style .sp Salt is developed with a certain coding style, while the style is dominantly PEP 8 it is not completely PEP 8. 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 Linting .sp Most Salt style conventions are codified in Salt\(aqs \fI\&.pylintrc\fP file. This file is found in the root of the Salt project and can be passed as an argument to the \fI\%pylint\fP program as follows: .sp \fIpylint \-\-rcfile=/path/to/salt/.pylintrc salt/dir/to/lint\fP .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.: .INDENT 0.0 .INDENT 3.5 .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 .UNINDENT .UNINDENT .SS Formatting Strings .sp All strings which require formatting should use the \fI\&.format\fP string method: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C data = \(aqsome text\(aq more = \(aq{0} and then some\(aq.format(data) .ft P .fi .UNINDENT .UNINDENT .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: .INDENT 0.0 .INDENT 3.5 .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 .UNINDENT .UNINDENT .sp \fIBAD\fP: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C def baz(): \(aq\(aq\(aqThis is not ok!\(aq\(aq\(aq return .ft P .fi .UNINDENT .UNINDENT .sp When adding a new function or state, where possible try to use a \fBversionadded\fP directive to denote when the function or state was added. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C def new_func(msg=\(aq\(aq): \(aq\(aq\(aq .. versionadded:: 0.16.0 Prints what was passed to the function. msg : None The string to be printed. \(aq\(aq\(aq print msg .ft P .fi .UNINDENT .UNINDENT .sp If you are uncertain what version should be used, either \fBconsult a core developer in IRC\fP or bring this up when opening your \fBpull request\fP and a core developer will add the proper version once your pull request has been merged. Bugfixes will be available in a bugfix release (i.e. 0.17.1, the first bugfix release for 0.17.0), while new features are held for feature releases, and this will affect what version number should be used in the \fBversionadded\fP directive. .sp Similar to the above, when an existing function or state is modified (for example, when an argument is added), then under the explanation of that new argument a \fBversionadded\fP directive should be used to note the version in which the new argument was added. If an argument\(aqs function changes significantly, the \fBversionchanged\fP directive can be used to clarify this: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C def new_func(msg=\(aq\(aq, signature=\(aq\(aq): \(aq\(aq\(aq .. versionadded:: 0.16.0 Prints what was passed to the function. msg : None The string to be printed. Will be prepended with \(aqGreetings! \(aq. .. versionchanged:: 0.17.1 signature : None An optional signature. .. versionadded 0.17.0 \(aq\(aq\(aq print \(aqGreetings! {0}\en\en{1}\(aq.format(msg, signature) .ft P .fi .UNINDENT .UNINDENT .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: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C import os def minion_path(): path = os.path.join(self.opts[\(aqcachedir\(aq], \(aqminions\(aq) return path .ft P .fi .UNINDENT .UNINDENT .sp This on the other hand is \fIDISCOURAGED\fP: .INDENT 0.0 .INDENT 3.5 .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 .UNINDENT .UNINDENT .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: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C from salt.exceptions import CommandExecutionError .ft P .fi .UNINDENT .UNINDENT .SS Absolute Imports .sp Although \fI\%absolute imports\fP seems like an awesome idea, please do not use it. Extra care would be necessary all over salt\(aqs code in order for absolute imports to work as supposed. Believe it, it has been tried before and, as a tried example, by renaming \fBsalt.modules.sysmod\fP to \fBsalt.modules.sys\fP, all other salt modules which needed to import \fI\%sys\fP would have to also import \fI\%absolute_import\fP, which should be avoided. .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 8 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: .INDENT 0.0 .INDENT 3.5 .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 .UNINDENT .UNINDENT .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: .INDENT 0.0 .INDENT 3.5 .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 .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 Making function and class definitions vertical is only required if the arguments are longer then 80 characters. Otherwise, the formatting is optional and both are acceptable. .UNINDENT .UNINDENT .SS Indenting .sp Some confusion exists in the python world about indenting things like function calls, the above examples use 8 spaces when indenting comma\-delimited constructs. .sp The confusion arises because the pep8 program INCORRECTLY flags this as wrong, where PEP 8, the document, cites only using 4 spaces here as wrong, as it doesn\(aqt differentiate from a new indent level. .sp Right: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C def managed(name, source=None, source_hash=\(aq\(aq, user=None) .ft P .fi .UNINDENT .UNINDENT .sp WRONG: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C def managed(name, source=None, source_hash=\(aq\(aq, user=None) .ft P .fi .UNINDENT .UNINDENT .sp Lining up the indent is also correct: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C def managed(name, source=None, source_hash=\(aq\(aq, user=None) .ft P .fi .UNINDENT .UNINDENT .sp This also applies to function calls and other hanging indents. .sp pep8 and Flake8 (and, by extension, the vim plugin Syntastic) will complain about the double indent for hanging indents. This is a \fI\%known conflict\fP between pep8 (the script) and the actual PEP 8 standard. It is recommended that this particular warning be ignored with the following lines in \fB~/.config/flake8\fP: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C [flake8] ignore = E226,E241,E242,E126 .ft P .fi .UNINDENT .UNINDENT .sp Make sure your Flake8/pep8 are up to date. The first three errors are ignored by default and are present here to keep the behavior the same. This will also work for pep8 without the Flake8 wrapper \-\- just replace all instances of \(aqflake8\(aq with \(aqpep8\(aq, including the filename. .SS Code Churn .sp Many pull requests have been submitted that only churn code in the name of PEP 8. 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 8 (\fI\%http://www.python.org/dev/peps/pep\-0008/\fP) document before changing code. Many claims that a change is PEP 8 have been invalid, please double check before committing fixes. .SH SALTSTACK PACKAGING GUIDE .sp Since Salt provides a powerful toolkit for system management and automation, the package can be spit into a number of sub\-tools. While packaging Salt as a single package containing all components is perfectly acceptable, the split packages should follow this convention. .SS Source Files .sp Release packages should always be built from the source tarball distributed via pypi. Release packages should \fINEVER\fP use a git checkout as the source for distribution. .SS Single Package .sp Shipping Salt as a single package, where the minion, master and all tools are together is perfectly acceptable and practiced by distributions such as FreeBSD. .SS Split Package .sp Salt Should always be split in a standard way, with standard dependencies, this lowers cross distribution confusion about what components are going to be shipped with specific packages. These packages can be defined from the Salt Source as of Salt 0.17.0: .SS Salt Common .sp The \fIsalt\-common\fP or \fIsalt\fP package should contain the files provided by the salt python package, or all files distributed from the \fBsalt/\fP directory in the source distribution packages. The documentation contained under the \fBdoc/\fP directory can be a part of this package but splitting out a doc package is preferred. Since salt\-call is the entry point to utilize the libs and is useful for all salt packages it is included in the salt\-common package. .SS Name .INDENT 0.0 .IP \(bu 2 \fIsalt\fP OR \fIsalt\-common\fP .UNINDENT .SS Files .INDENT 0.0 .IP \(bu 2 \fIsalt/*\fP .IP \(bu 2 \fIman/salt.7\fP .IP \(bu 2 \fIscripts/salt\-call\fP .IP \(bu 2 \fItests/*\fP .IP \(bu 2 \fIman/salt\-call.1\fP .UNINDENT .SS Depends .INDENT 0.0 .IP \(bu 2 \fIPython 2.6\-2.7\fP .IP \(bu 2 \fIPyYAML\fP .IP \(bu 2 \fIJinja2\fP .UNINDENT .SS Salt Master .sp The \fIsalt\-master\fP package contains the applicable scripts, related man pages and init information for the given platform. .SS Name .INDENT 0.0 .IP \(bu 2 \fIsalt\-master\fP .UNINDENT .SS Files .INDENT 0.0 .IP \(bu 2 \fIscripts/salt\-master\fP .IP \(bu 2 \fIscripts/salt\fP .IP \(bu 2 \fIscripts/salt\-run\fP .IP \(bu 2 \fIscripts/salt\-key\fP .IP \(bu 2 \fIscripts/salt\-cp\fP .IP \(bu 2 \fIpkg/\fP .IP \(bu 2 \fIman/salt.1\fP .IP \(bu 2 \fIman/salt\-master.1\fP .IP \(bu 2 \fIman/salt\-run.1\fP .IP \(bu 2 \fIman/salt\-key.1\fP .IP \(bu 2 \fIman/salt\-cp.1\fP .IP \(bu 2 \fIconf/master\fP .UNINDENT .SS Depends .INDENT 0.0 .IP \(bu 2 \fISalt Common\fP .IP \(bu 2 \fIZeroMQ\fP >= 3.2 .IP \(bu 2 \fIPyZMQ\fP >= 2.10 .IP \(bu 2 \fIPyCrypto\fP .IP \(bu 2 \fIM2Crypto\fP .IP \(bu 2 \fIPython MessagePack\fP (Messagepack C lib, or msgpack\-pure) .UNINDENT .SS Salt Syndic .sp The Salt Syndic package can be rolled completely into the Salt Master package. Platforms which start services as part of the package deployment need to maintain a separate \fIsalt\-syndic\fP package (primarily Debian based platforms). .sp The Syndic may optionally not depend on the anything more than the Salt Master since the master will bring in all needed dependencies, but fall back to the platform specific packaging guidelines. .SS Name .INDENT 0.0 .IP \(bu 2 \fIsalt\-syndic\fP .UNINDENT .SS Files .INDENT 0.0 .IP \(bu 2 \fIscripts/salt\-syndic\fP .IP \(bu 2 \fIpkg/\fP .IP \(bu 2 \fIman/salt\-syndic.1\fP .UNINDENT .SS Depends .INDENT 0.0 .IP \(bu 2 \fISalt Common\fP .IP \(bu 2 \fISalt Master\fP .IP \(bu 2 \fIZeroMQ\fP >= 3.2 .IP \(bu 2 \fIPyZMQ\fP >= 2.10 .IP \(bu 2 \fIPyCrypto\fP .IP \(bu 2 \fIM2Crypto\fP .IP \(bu 2 \fIPython MessagePack\fP (Messagepack C lib, or msgpack\-pure) .UNINDENT .SS Salt Minion .sp The Minion is a standalone package and should not be split beyond the \fIsalt\-minion\fP and \fIsalt\-common\fP packages. .SS Name .INDENT 0.0 .IP \(bu 2 \fIsalt\-minion\fP .UNINDENT .SS Files .INDENT 0.0 .IP \(bu 2 \fIscripts/salt\-minion\fP .IP \(bu 2 \fIpkg/\fP .IP \(bu 2 \fIman/salt\-minion.1\fP .IP \(bu 2 \fIconf/minion\fP .UNINDENT .SS Depends .INDENT 0.0 .IP \(bu 2 \fISalt Common\fP .IP \(bu 2 \fIZeroMQ\fP >= 3.2 .IP \(bu 2 \fIPyZMQ\fP >= 2.10 .IP \(bu 2 \fIPyCrypto\fP .IP \(bu 2 \fIM2Crypto\fP .IP \(bu 2 \fIPython MessagePack\fP (Messagepack C lib, or msgpack\-pure) .UNINDENT .SS Salt SSH .sp Since Salt SSH does not require the same dependencies as the minion and master, it should be split out. .SS Name .INDENT 0.0 .IP \(bu 2 \fIsalt\-ssh\fP .UNINDENT .SS Files .INDENT 0.0 .IP \(bu 2 \fIscripts/salt\-ssh\fP .IP \(bu 2 \fIman/salt\-ssh.1\fP .UNINDENT .SS Depends .INDENT 0.0 .IP \(bu 2 \fISalt Common\fP .IP \(bu 2 \fIsshpass\fP .IP \(bu 2 \fIPython MessagePack\fP (Messagepack C lib, or msgpack\-pure) .UNINDENT .SS Salt Doc .sp The documentation package is very distribution optional. A completely split package will split out the documentation, but some platform conventions do not prefer this. If the documentation is not split out, it should be included with the \fISalt Common\fP package. .SS Name .INDENT 0.0 .IP \(bu 2 \fIsalt\-doc\fP .UNINDENT .SS Files .INDENT 0.0 .IP \(bu 2 \fIdoc/*\fP .UNINDENT .SS Optional Depends .INDENT 0.0 .IP \(bu 2 \fISalt Common\fP .IP \(bu 2 \fIPython Sphinx\fP .IP \(bu 2 \fIMake\fP .UNINDENT .SH SALT RELEASE PROCESS .sp The goal for Salt projects is to cut a new feature release every four to six weeks. This document outlines the process for these releases, and the subsequent bug fix releases which follow. .SS Feature Release Process .sp When a new release is ready to be cut, the person responsible for cutting the release will follow the following steps (written using the 0.16 release as an example): .INDENT 0.0 .IP 1. 3 All open issues on the release milestone should be moved to the next release milestone. (e.g. from the \fB0.16\fP milestone to the \fB0.17\fP milestone) .IP 2. 3 Release notes should be created documenting the major new features and bugfixes in the release. .IP 3. 3 Create an annotated tag with only the major and minor version numbers, preceded by the letter \fBv\fP\&. (e.g. \fBv0.16\fP) This tag will reside on the \fBdevelop\fP branch. .IP 4. 3 Create a branch for the new release, using only the major and minor version numbers. (e.g. \fB0.16\fP) .IP 5. 3 On this new branch, create an annotated tag for the first revision release, which is generally a release candidate. It should be preceded by the letter \fBv\fP\&. (e.g. \fBv0.16.0RC\fP) .IP 6. 3 The release should be packaged from this annotated tag and uploaded to PyPI. .IP 7. 3 The packagers should be notified on the \fBsalt\-packagers\fP mailing list so they can create packages for all the major operating systems. (note that release candidates should go in the testing repositories) .IP 8. 3 After the packagers have been given a few days to compile the packages, the release is announced on the \fBsalt\-users\fP mailing list. .IP 9. 3 Log into RTD and add the new release there. (Have to do it manually) .UNINDENT .SS Maintenance and Bugfix Releases .sp Once a release has been cut, regular cherry\-picking sessions should begin to cherry\-pick any bugfixes from the \fBdevelop\fP branch to the release branch (e.g. \fB0.16\fP). Once major bugs have been fixes and cherry\-picked, a bugfix release can be cut: .INDENT 0.0 .IP 1. 3 On the release branch (i.e. \fB0.16\fP), create an annotated tag for the revision release. It should be preceded by the letter \fBv\fP\&. (e.g. \fBv0.16.2\fP) Release candidates are unnecessary for bugfix releases. .IP 2. 3 The release should be packaged from this annotated tag and uploaded to PyPI. .IP 3. 3 The packagers should be notified on the \fBsalt\-packagers\fP mailing list so they can create packages for all the major operating systems. .IP 4. 3 After the packagers have been given a few days to compile the packages, the release is announced on the \fBsalt\-users\fP mailing list. .UNINDENT .SH SALT CODING STYLE .sp Salt is developed with a certain coding style, while the style is dominantly PEP 8 it is not completely PEP 8. 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 Linting .sp Most Salt style conventions are codified in Salt\(aqs \fI\&.pylintrc\fP file. This file is found in the root of the Salt project and can be passed as an argument to the \fI\%pylint\fP program as follows: .sp \fIpylint \-\-rcfile=/path/to/salt/.pylintrc salt/dir/to/lint\fP .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.: .INDENT 0.0 .INDENT 3.5 .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 .UNINDENT .UNINDENT .SS Formatting Strings .sp All strings which require formatting should use the \fI\&.format\fP string method: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C data = \(aqsome text\(aq more = \(aq{0} and then some\(aq.format(data) .ft P .fi .UNINDENT .UNINDENT .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: .INDENT 0.0 .INDENT 3.5 .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 .UNINDENT .UNINDENT .sp \fIBAD\fP: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C def baz(): \(aq\(aq\(aqThis is not ok!\(aq\(aq\(aq return .ft P .fi .UNINDENT .UNINDENT .sp When adding a new function or state, where possible try to use a \fBversionadded\fP directive to denote when the function or state was added. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C def new_func(msg=\(aq\(aq): \(aq\(aq\(aq .. versionadded:: 0.16.0 Prints what was passed to the function. msg : None The string to be printed. \(aq\(aq\(aq print msg .ft P .fi .UNINDENT .UNINDENT .sp If you are uncertain what version should be used, either \fBconsult a core developer in IRC\fP or bring this up when opening your \fBpull request\fP and a core developer will add the proper version once your pull request has been merged. Bugfixes will be available in a bugfix release (i.e. 0.17.1, the first bugfix release for 0.17.0), while new features are held for feature releases, and this will affect what version number should be used in the \fBversionadded\fP directive. .sp Similar to the above, when an existing function or state is modified (for example, when an argument is added), then under the explanation of that new argument a \fBversionadded\fP directive should be used to note the version in which the new argument was added. If an argument\(aqs function changes significantly, the \fBversionchanged\fP directive can be used to clarify this: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C def new_func(msg=\(aq\(aq, signature=\(aq\(aq): \(aq\(aq\(aq .. versionadded:: 0.16.0 Prints what was passed to the function. msg : None The string to be printed. Will be prepended with \(aqGreetings! \(aq. .. versionchanged:: 0.17.1 signature : None An optional signature. .. versionadded 0.17.0 \(aq\(aq\(aq print \(aqGreetings! {0}\en\en{1}\(aq.format(msg, signature) .ft P .fi .UNINDENT .UNINDENT .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: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C import os def minion_path(): path = os.path.join(self.opts[\(aqcachedir\(aq], \(aqminions\(aq) return path .ft P .fi .UNINDENT .UNINDENT .sp This on the other hand is \fIDISCOURAGED\fP: .INDENT 0.0 .INDENT 3.5 .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 .UNINDENT .UNINDENT .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: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C from salt.exceptions import CommandExecutionError .ft P .fi .UNINDENT .UNINDENT .SS Absolute Imports .sp Although \fI\%absolute imports\fP seems like an awesome idea, please do not use it. Extra care would be necessary all over salt\(aqs code in order for absolute imports to work as supposed. Believe it, it has been tried before and, as a tried example, by renaming \fBsalt.modules.sysmod\fP to \fBsalt.modules.sys\fP, all other salt modules which needed to import \fI\%sys\fP would have to also import \fI\%absolute_import\fP, which should be avoided. .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 8 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: .INDENT 0.0 .INDENT 3.5 .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 .UNINDENT .UNINDENT .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: .INDENT 0.0 .INDENT 3.5 .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 .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 Making function and class definitions vertical is only required if the arguments are longer then 80 characters. Otherwise, the formatting is optional and both are acceptable. .UNINDENT .UNINDENT .SS Indenting .sp Some confusion exists in the python world about indenting things like function calls, the above examples use 8 spaces when indenting comma\-delimited constructs. .sp The confusion arises because the pep8 program INCORRECTLY flags this as wrong, where PEP 8, the document, cites only using 4 spaces here as wrong, as it doesn\(aqt differentiate from a new indent level. .sp Right: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C def managed(name, source=None, source_hash=\(aq\(aq, user=None) .ft P .fi .UNINDENT .UNINDENT .sp WRONG: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C def managed(name, source=None, source_hash=\(aq\(aq, user=None) .ft P .fi .UNINDENT .UNINDENT .sp Lining up the indent is also correct: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C def managed(name, source=None, source_hash=\(aq\(aq, user=None) .ft P .fi .UNINDENT .UNINDENT .sp This also applies to function calls and other hanging indents. .sp pep8 and Flake8 (and, by extension, the vim plugin Syntastic) will complain about the double indent for hanging indents. This is a \fI\%known conflict\fP between pep8 (the script) and the actual PEP 8 standard. It is recommended that this particular warning be ignored with the following lines in \fB~/.config/flake8\fP: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C [flake8] ignore = E226,E241,E242,E126 .ft P .fi .UNINDENT .UNINDENT .sp Make sure your Flake8/pep8 are up to date. The first three errors are ignored by default and are present here to keep the behavior the same. This will also work for pep8 without the Flake8 wrapper \-\- just replace all instances of \(aqflake8\(aq with \(aqpep8\(aq, including the filename. .SS Code Churn .sp Many pull requests have been submitted that only churn code in the name of PEP 8. 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 8 (\fI\%http://www.python.org/dev/peps/pep\-0008/\fP) document before changing code. Many claims that a change is PEP 8 have been invalid, please double check before committing fixes. .SH SALTSTACK GIT POLICY .sp The SaltStack 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 SaltStack projects DO NOT NEED TO READ THIS DOCUMENT, because all contributions come into SaltStack 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 SaltStack 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 SaltStack 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 SaltStack 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: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C # git checkout \-b 0.11 # From the develop branch # git push origin 0.11 .ft P .fi .UNINDENT .UNINDENT .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 Deprecating Code .sp Salt should remain backwards compatible, though sometimes, this backwards compatibility needs to be broken because a specific feature and/or solution is no longer necessary or required. At first one might think, let me change this code, it seems that it\(aqs not used anywhere else so it should be safe to remove. Then, once there\(aqs a new release, users complain about functionality which was removed and they where using it, etc. This should, at all costs, be avoided, and, in these cases, \fIthat\fP specific code should be deprecated. .sp Depending on the complexity and usage of a specific piece of code, the deprecation time frame should be properly evaluated. As an example, a deprecation warning which is shown for 2 major releases, for example \fI0.17.0\fP and \fI2014.1.0\fP, gives users enough time to stop using the deprecated code and adapt to the new one. .sp For example, if you\(aqre deprecating the usage of a keyword argument to a function, that specific keyword argument should remain in place for the full deprecation time frame and if that keyword argument is used, a deprecation warning should be shown to the user. .sp To help in this deprecation task, salt provides \fBsalt.utils.warn_until\fP\&. The idea behind this helper function is to show the deprecation warning until salt reaches the provided version. Once that provided version is equaled \fBsalt.utils.warn_until\fP will raise a \fBRuntimeError\fP making salt stop its execution. This stoppage is unpleasant and will remind the developer that the deprecation limit has been reached and that the code can then be safely removed. .sp Consider the following example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C def some_function(bar=False, foo=None): if foo is not None: salt.utils.warn_until( (0, 18), \(aqThe \e\(aqfoo\e\(aq argument has been deprecated and its \(aq \(aqfunctionality removed, as such, its usage is no longer \(aq \(aqrequired.\(aq ) .ft P .fi .UNINDENT .UNINDENT .sp Consider that the current salt release is \fB0.16.0\fP\&. Whenever \fBfoo\fP is passed a value different from \fBNone\fP that warning will be shown to the user. This will happen in versions \fB0.16.2\fP to \fB2014.1.0\fP, after which a \fBRuntimeError\fP will be raised making us aware that the deprecated code should now be removed. .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 __opts__ .SS Available in .INDENT 0.0 .IP \(bu 2 All loader modules .UNINDENT .sp The \fB__opts__\fP dictionary contains all of the options passed in the configuration file for the master or minion. .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 In many places in salt, instead of pulling raw data from the __opts__ dict, configuration data should be pulled from the salt \fIget\fP frunctions such as config.get, aka \- __salt__[\(aqconfig.get\(aq](\(aqfoo:bar\(aq) The \fIget\fP functions also allow for dict traversal via the \fI:\fP delimiter. Consider using get functions whenever using __opts__ or __pillar__ and __grains__ (when using grains for configuration data) .UNINDENT .UNINDENT .sp The configuration file data made available in the \fB__opts__\fP dictionary is the configuration data relative to the running daemon. If the modules are loaded and executed by the master, then the master configuration data is available, if the modules are executed by the minion, then the minion configuration is available. Any additional information passed into the respective configuration files is made available .SS __salt__ .SS Available in .INDENT 0.0 .IP \(bu 2 Execution Modules .IP \(bu 2 State Modules .IP \(bu 2 Returners .UNINDENT .sp \fB__salt__\fP contains the execution module functions. This allows for all functions to be called as they have been set up by the salt loader. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C __salt__[\(aqcmd.run\(aq](\(aqfdisk \-l\(aq) __salt__[\(aqnetwork.ip_addrs\(aq]() .ft P .fi .UNINDENT .UNINDENT .SS __grains__ .SS Available in .INDENT 0.0 .IP \(bu 2 Execution Modules .IP \(bu 2 State Modules .IP \(bu 2 Returners .IP \(bu 2 External Pillar .UNINDENT .sp The \fB__grains__\fP dictionary contains the grains data generated by the minion that is currently being worked with. In execution modules, state modules and returners this is the grains of the minion running the calls, when generating the external pillar the \fB__grains__\fP is the grains data from the minion that the pillar is being generated for. .SS __pillar__ .SS Available in .INDENT 0.0 .IP \(bu 2 Execution Modules .IP \(bu 2 State Modules .IP \(bu 2 Returners .UNINDENT .sp The \fB__pillar__\fP dictionary contains the pillar for the respective minion. .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: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C if not \(aqcp.fileclient\(aq in __context__: __context__[\(aqcp.fileclient\(aq] = salt.fileclient.get_file_client(__opts__) .ft P .fi .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 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. .UNINDENT .UNINDENT .SS External Pillars .sp Salt provides a mechanism for generating pillar data by calling external pillar interfaces. This document will describe an outline of an ext_pillar module. .SS Location .sp Salt expects to find your \fBext_pillar\fP module in the same location where it looks for other python modules. If the \fBextension_modules\fP option in your Salt master configuration is set, Salt will look for a \fBpillar\fP directory under there and load all the modules it finds. Otherwise, it will look in your Python site\-packages \fBsalt/pillar\fP directory. .SS Configuration .sp The external pillars that are called when a minion refreshes its pillars is controlled by the \fBext_pillar\fP option in the Salt master configuration. You can pass a single argument, a list of arguments or a dictionary of arguments to your pillar: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C ext_pillar: \- example_a: some argument \- example_b: \- argumentA \- argumentB \- example_c: keyA: valueA keyB: valueB .ft P .fi .UNINDENT .UNINDENT .SS The Module .SS Imports and Logging .sp Import modules your external pillar module needs. You should first include generic modules that come with stock Python: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C import logging .ft P .fi .UNINDENT .UNINDENT .sp And then start logging. This is an idiomatic way of setting up logging in Salt: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C log = logging.getLogger(__name__) .ft P .fi .UNINDENT .UNINDENT .sp Finally, load modules that are specific to what you are doing. You should catch import errors and set a flag that the the \fB__virtual__\fP function can use later. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C try: import weird_thing example_a_loaded = True except ImportError: example_a_loaded = False .ft P .fi .UNINDENT .UNINDENT .SS Options .sp If you define an \fB__opts__\fP dictionary, it will be merged into the \fB__opts__\fP dictionary handed to the \fBext_pillar\fP function later. This is a good place to put default configuration items. The convention is to name things \fBmodulename.option\fP\&. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C __opts__ = { \(aqexample_a.someconfig\(aq: 137 } .ft P .fi .UNINDENT .UNINDENT .SS Initialization .sp If you define an \fB__init__\fP function, it will be called with the following signature: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C def __init__( __opts__ ): # Do init work here .ft P .fi .UNINDENT .UNINDENT .sp \fBNote\fP: The \fB__init__\fP function is ran every time a particular minion causes the external pillar to be called, so don\(aqt put heavy initialization code here. The \fB__init__\fP functionality is a side\-effect of the Salt loader, so it may not be as useful in pillars as it is in other Salt items. .SS __virtual__ .sp If you define a \fB__virtual__\fP function, you can control whether or not this module is visible. If it returns \fBFalse\fP then Salt ignores this module. If it returns a string, then that string will be how Salt identifies this external pillar in its \fBext_pillar\fP configuration. If this function does not exist, then the name Salt\(aqs \fBext_pillar\fP will use to identify this module is its conventional name in Python. .sp This is useful to write modules that can be installed on all Salt masters, but will only be visible if a particular piece of software your module requires is installed. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C # This external pillar will be known as \(gaexample_a\(ga def __virtual__(): if example_a_loaded: return \(aqexample_a\(aq else: return False .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C # This external pillar will be known as \(gasomething_else\(ga def __virtual__(): if example_a_loaded: return \(aqsomething_else\(aq else: return False .ft P .fi .UNINDENT .UNINDENT .SS ext_pillar .sp This is where the real work of an external pillar is done. If this module is active and has a function called \fBext_pillar\fP, whenever a minion updates its pillar this function is called. .sp How it is called depends on how it is configured in the Salt master configuration. The first argument is always the current pillar dictionary, this contains pillar items that have already been added, starting with the data from \fBpillar_roots\fP, and then from any already\-ran external pillars. .sp Using our example above: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C ext_pillar( id, pillar, \(aqsome argument\(aq ) # example_a ext_pillar( id, pillar, \(aqargumentA\(aq, \(aqargumentB\(aq ) # example_b ext_pillar( id, pillar, keyA=\(aqvalueA\(aq, keyB=\(aqvalueB\(aq } ) # example_c .ft P .fi .UNINDENT .UNINDENT .sp In the \fBexample_a\fP case, \fBpillar\fP will contain the items from the \fBpillar_roots\fP, in \fBexample_b\fP \fBpillar\fP will contain that plus the items added by \fBexample_a\fP, and in \fBexample_c\fP \fBpillar\fP will contain that plus the items added by \fBexample_b\fP\&. In all three cases, \fBid\fP will contain the ID of the minion making the pillar request. .sp This function should return a dictionary, the contents of which are merged in with all of the other pillars and returned to the minion. \fBNote\fP: this function is called once for each minion that fetches its pillar data. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C def ext_pillar( minion_id, pillar, *args, **kwargs ): my_pillar = {} # Do stuff return my_pillar .ft P .fi .UNINDENT .UNINDENT .sp You shouldn\(aqt just add items to \fBpillar\fP and return that, since that will cause Salt to merge data that already exists. Rather, just return the items you are adding or changing. You could, however, use \fBpillar\fP in your module to make some decision based on pillar data that already exists. .sp This function has access to some useful globals: .INDENT 0.0 .TP .B __opts__ A dictionary of mostly Salt configuration options. If you had an \fB__opts__\fP dictionary defined in your module, those values will be included. .TP .B __salt__ A dictionary of Salt module functions, useful so you don\(aqt have to duplicate functions that already exist. E.g. \fB__salt__[\(aqcmd.run\(aq]( \(aqls \-l\(aq )\fP \fBNote\fP, runs on the \fImaster\fP .TP .B __grains__ A dictionary of the grains of the minion making this pillar call. .UNINDENT .SS Example configuration .sp As an example, if you wanted to add external pillar via the \fBcmd_json\fP external pillar, add something like this to your master config: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C ext_pillar: \- cmd_json: "echo {\(aqarg\(aq:\(aqvalue\(aq}" .ft P .fi .UNINDENT .UNINDENT .SS Logging Internals .sp TODO .SS Modular Systems .sp When first working with Salt, it is not always clear where all of the modular components are and what they do. Salt comes loaded with more modular systems than many users are aware of, making Salt very easy to extend in many places. .sp The most commonly used modular systems are execution modules and states. But the modular systems extend well beyond the more easily exposed components and are often added to Salt to make the complete system more flexible. .SS Execution Modules .sp Execution modules make up the core of the functionality used by Salt to interact with client systems. The execution modules create the core system management library used by all Salt systems, including states, which interact with minion systems. .sp Execution modules are completely open ended in their execution. They can be used to do anything required on a minion, from installing packages to detecting information about the system. The only restraint in execution modules is that the defined functions always return a JSON serializable object. .sp For a list of all built in execution modules, click \fBhere\fP .sp For information on writing execution modules, see \fBthis page\fP\&. .SS State Modules .sp State modules are used to define the state interfaces used by Salt States. These modules are restrictive in that they must follow a number of rules to function properly. .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 State modules define the available routines in sls files. If calling an execution module directly is desired, take a look at the \fImodule\fP state. .UNINDENT .UNINDENT .SS Auth .sp The auth module system allows for external authentication routines to be easily added into Salt. The \fIauth\fP function needs to be implemented to satisfy the requirements of an auth module. Use the \fBpam\fP module as an example. .SS Fileserver .sp The fileserver module system is used to create fileserver backends used by the Salt Master. These modules need to implement the functions used in the fileserver subsystem. Use the \fBgitfs\fP module as an example. .SS Grains .sp Grain modules define extra routines to populate grains data. All defined public functions will be executed and MUST return a Python dict object. The dict keys will be added to the grains made available to the minion. .SS Output .sp The output modules supply the outputter system with routines to display data in the terminal. These modules are very simple and only require the \fIoutput\fP function to execute. The default system outputter is the \fBnested\fP module. .SS Pillar .sp Used to define optional external pillar systems. The pillar generated via the filesystem pillar is passed into external pillars. This is commonly used as a bridge to database data for pillar, but is also the backend to the libvirt state used to generate and sign libvirt certificates on the fly. .SS Renderers .sp Renderers are the system used to render sls files into salt highdata for the state compiler. They can be as simple as the \fBpy\fP renderer and as complex as \fBstateconf\fP and \fBpydsl\fP\&. .SS Returners .sp Returners are used to send data from minions to external sources, commonly databases. A full returner will implement all routines to be supported as an external job cache. Use the \fBredis\fP returner as an example. .SS Runners .sp Runners are purely master\-side execution sequences. These range from simple reporting to orchestration engines like the overstate. .SS Tops .sp Tops modules are used to convert external data sources into top file data for the state system. .SS Wheel .sp The wheel system is used to manage master side management routines. These routines are primarily intended for the API to enable master configuration. .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: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C __salt__[\(aqpkg_resource.add_pkg\(aq](ret, name, version) .ft P .fi .UNINDENT .UNINDENT .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. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C __salt__[\(aqpkg_resource.sort_pkglist\(aq](ret) .ft P .fi .UNINDENT .UNINDENT .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: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C {\(aqfoo\(aq: \(aq1.2.3\-4\(aq, \(aqbar\(aq: \(aq5.6.7\-8\(aq} .ft P .fi .UNINDENT .UNINDENT .SS latest_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. .sp This function must also accept \fB**kwargs\fP, in order to receive the \fBfromrepo\fP and \fBrepo\fP keyword arguments from pkg states. Where supported, these arguments should be used to find the install/upgrade candidate in the specified repository. The \fBfromrepo\fP kwarg takes precedence over \fBrepo\fP, so if both of those kwargs are present, the repository specified in \fBfromrepo\fP should be used. However, if \fBrepo\fP is used instead of \fBfromrepo\fP, it should still work, to preserve backwards compatibility with older versions of Salt. .SS version .sp Like \fBlatest_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: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C return __salt__[\(aqpkg.latest_version\(aq](name) != \(aq\(aq .ft P .fi .UNINDENT .UNINDENT .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. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C pkg_params, pkg_type = __salt__[\(aqpkg_resource.parse_targets\(aq](name, pkgs, sources) .ft P .fi .UNINDENT .UNINDENT .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 possible 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 \fBsalt.utils.compare_dicts()\fP .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C return salt.utils.compare_dicts(old, new) .ft P .fi .UNINDENT .UNINDENT .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. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C basedir = \(aq/etc/yum.repos.d\(aq __salt__[\(aqpkg.list_repos\(aq](basedir) .ft P .fi .UNINDENT .UNINDENT .SS list_repos .sp Lists the repositories that are currently configured on this system. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C __salt__[\(aqpkg.list_repos\(aq]() .ft P .fi .UNINDENT .UNINDENT .sp Returns a dictionary, in the following format: .INDENT 0.0 .INDENT 3.5 .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 .UNINDENT .UNINDENT .SS get_repo .sp Displays all local configuration for a specific repository. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C __salt__[\(aqpkg.get_repo\(aq](repo=\(aqmyrepo\(aq) .ft P .fi .UNINDENT .UNINDENT .sp The information is formatted in much the same way as list_repos, but is specific to only one repo. .INDENT 0.0 .INDENT 3.5 .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 .UNINDENT .UNINDENT .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. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C __salt__[\(aqpkg.del_repo\(aq](repo=\(aqmyrepo\(aq) .ft P .fi .UNINDENT .UNINDENT .SS mod_repo .sp Modify the local configuration for one or more option for a configured 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. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C __salt__[\(aqpkg.mod_repo\(aq](repo=\(aqmyrepo\(aq, url=\(aqhttp://myurl.com/repo\(aq) .ft P .fi .UNINDENT .UNINDENT .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 specified, then all installed packages will be listed. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C installed = __salt__[\(aqlowpkg.list_pkgs\(aq](\(aqfoo\(aq, \(aqbar\(aq) .ft P .fi .UNINDENT .UNINDENT .sp Example output: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C {\(aqfoo\(aq: \(aq1.2.3\-4\(aq, \(aqbar\(aq: \(aq5.6.7\-8\(aq} .ft P .fi .UNINDENT .UNINDENT .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. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C installed = __salt__[\(aqlowpkg.verify\(aq](\(aqhttpd\(aq) .ft P .fi .UNINDENT .UNINDENT .sp Example output: .INDENT 0.0 .INDENT 3.5 .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 .UNINDENT .UNINDENT .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. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C installed = __salt__[\(aqlowpkg.file_list\(aq](\(aqhttpd\(aq, \(aqapache\(aq) .ft P .fi .UNINDENT .UNINDENT .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. .INDENT 0.0 .INDENT 3.5 .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 .UNINDENT .UNINDENT .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. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C installed = __salt__[\(aqlowpkg.file_dict\(aq](\(aqhttpd\(aq, \(aqapache\(aq, \(aqkernel\(aq) .ft P .fi .UNINDENT .UNINDENT .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\&. .INDENT 0.0 .INDENT 3.5 .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 .UNINDENT .UNINDENT .SH TRANSLATING DOCUMENTATION .sp If you wish to help translate the Salt documentation to your language, please head over to the \fI\%Transifex\fP website and \fI\%signup\fP for an account. .sp Once registered, head over to the \fI\%Salt Translation Project\fP, and either click on \fBRequest Language\fP if you can\(aqt find yours, or, select the language for which you wish to contribute and click \fBJoin Team\fP\&. .sp \fI\%Transifex\fP provides some useful reading resources on their \fI\%support domain\fP, namely, some useful articles \fI\%directed to translators\fP\&. .SS Building A Localized Version of the Documentation .sp While you\(aqre working on your translation on \fI\%Transifex\fP, you might want to have a look at how it\(aqs rendering. .SS Install The Transifex Client .sp To interact with the \fI\%Transifex\fP web service you will need to install the \fI\%transifex\-client\fP: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C pip install transifex\-client .ft P .fi .UNINDENT .UNINDENT .SS Configure The Transifex Client .sp Once installed, you will need to set it up on your computer. We created a script to help you with that: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C \&.scripts/setup\-transifex\-config .ft P .fi .UNINDENT .UNINDENT .SS Download Remote Translations .sp There\(aqs a little script which simplifies the download process of the translations(which isn\(aqt that complicated in the first place). So, let\(aqs assume you\(aqre translating \fBpt_PT\fP, Portuguese(Portugal). To download the translations, execute from the \fBdoc/\fP directory of your Salt checkout: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C make download\-translations SPHINXLANG=pt_PT .ft P .fi .UNINDENT .UNINDENT .sp To download \fBpt_PT\fP, Portuguese(Portugal) and \fBnl\fP, Dutch, you can use the helper script directly: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C \&.scripts/download\-translation\-catalog pt_PT nl .ft P .fi .UNINDENT .UNINDENT .SS Build Localized Documentation .sp After the download process finishes, which might take a while, the next step is to build a localized version of the documentation. Following the \fBpt_PT\fP example above: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C make html SPHINXLANG=pt_PT .ft P .fi .UNINDENT .UNINDENT .SS View Localized Documentation .sp Open your browser, point it to the local documentation path and check the localized output you\(aqve just build. .SH COMMUNITY PROJECTS THAT USE SALT .sp Below is a list of repositories that show real world Salt applications that you can use to get started. Please note that these projects do not adhere to any standards and express a wide variety of ideas and opinions on how an action can be completed with Salt. .sp \fI\%https://github.com/terminalmage/djangocon2013\-sls\fP .sp \fI\%https://github.com/jesusaurus/hpcs\-salt\-state\fP .sp \fI\%https://github.com/gravyboat/hungryadmin\-sls\fP .SH SALT PROXY MINION DOCUMENTATION .sp Proxy minions are a developing Salt feature that enables controlling devices that, for whatever reason, cannot run a standard salt\-minion. Examples include network gear that has an API but runs a proprietary OS, devices with limited CPU or memory, or devices that could run a minion, but for security reasons, will not. .sp \fIProxy minions are not an "out of the box" feature\fP\&. Because there are an infinite number of controllable devices, you will most likely have to write the interface yourself. Fortunately, this is only as difficult as the actual interface to the proxied device. Devices that have an existing Python module (PyUSB for example) would be relatively simple to interface. Code to control a device that has an HTML REST\-based interface should be easy. Code to control your typical housecat would be excellent source material for a PhD thesis. .sp Salt proxy\-minions provide the \(aqplumbing\(aq that allows device enumeration and discovery, control, status, remote execution, and state management. .SS Getting Started .sp The following diagram may be helpful in understanding the structure of a Salt installation that includes proxy\-minions: [image] .sp The key thing to remember is the left\-most section of the diagram. Salt\(aqs nature is to have a minion connect to a master, then the master may control the minion. However, for proxy minions, the target device cannot run a minion, and thus must rely on a separate minion to fire up the proxy\-minion and make the initial and persistent connection. .sp After the proxy minion is started and initiates its connection to the \(aqdumb\(aq device, it connects back to the salt\-master and ceases to be affiliated in any way with the minion that started it. .sp To create support for a proxied device one needs to create four things: .INDENT 0.0 .IP 1. 3 The \fI\%proxytype connection class\fP (located in salt/proxy). .IP 2. 3 The \fI\%grains support code\fP (located in salt/grains). .IP 3. 3 .nf \(gaSalt modules\(ga_ .fi specific to the controlled device. .IP 4. 3 specific to the controlled device. .UNINDENT .SS Configuration parameters on the master .sp Proxy minions require no configuration parameters in /etc/salt/master. .sp Salt\(aqs Pillar system is ideally suited for configuring proxy\-minions. Proxies can either be designated via a pillar file in pillar_roots, or through an external pillar. External pillars afford the opportunity for interfacing with a configuration management system, database, or other knowledgeable system that that may already contain all the details of proxy targets. To use static files in pillar_roots, pattern your files after the following examples, which are based on the diagram above: .sp \fB/srv/salt/pillar/top.sls\fP .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C base: minioncontroller1: \- networkswitches minioncontroller2: \- reallydumbdevices minioncontroller3: \- smsgateway .ft P .fi .UNINDENT .UNINDENT .sp \fB/srv/salt/pillar/networkswitches.sls\fP .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C proxy: dumbdevice1: proxytype: networkswitch host: 172.23.23.5 username: root passwd: letmein dumbdevice2: proxytype: networkswitch host: 172.23.23.6 username: root passwd: letmein dumbdevice3: proxytype: networkswitch host: 172.23.23.7 username: root passwd: letmein .ft P .fi .UNINDENT .UNINDENT .sp \fB/srv/salt/pillar/reallydumbdevices.sls\fP .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C proxy: dumbdevice4: proxytype: i2c_lightshow i2c_address: 1 dumbdevice5: proxytype: i2c_lightshow i2c_address: 2 dumbdevice6: proxytype: 433mhz_wireless .ft P .fi .UNINDENT .UNINDENT .sp \fB/srv/salt/pillar/smsgateway.sls\fP .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C proxy: minioncontroller3: dumbdevice7: proxytype: sms_serial deventry: /dev/tty04 .ft P .fi .UNINDENT .UNINDENT .sp Note the contents of each minioncontroller key may differ widely based on the type of device that the proxy\-minion is managing. .sp In the above example .INDENT 0.0 .IP \(bu 2 dumbdevices 1, 2, and 3 are network switches that have a management interface available at a particular IP address. .IP \(bu 2 dumbdevices 4 and 5 are very low\-level devices controlled over an i2c bus. In this case the devices are physically connected to machine \(aqminioncontroller2\(aq, and are addressable on the i2c bus at their respective i2c addresses. .IP \(bu 2 dumbdevice6 is a 433 MHz wireless transmitter, also physically connected to minioncontroller2 .IP \(bu 2 dumbdevice7 is an SMS gateway connected to machine minioncontroller3 via a serial port. .UNINDENT .sp Because of the way pillar works, each of the salt\-minions that fork off the proxy minions will only see the keys specific to the proxies it will be handling. In other words, from the above example, only minioncontroller1 will see the connection information for dumbdevices 1, 2, and 3. Minioncontroller2 will see configuration data for dumbdevices 4, 5, and 6, and minioncontroller3 will be privy to dumbdevice7. .sp Also, in general, proxy\-minions are lightweight, so the machines that run them could conceivably control a large number of devices. The example above is just to illustrate that it is possible for the proxy services to be spread across many machines if necessary, or intentionally run on machines that need to control devices because of some physical interface (e.g. i2c and serial above). Another reason to divide proxy services might be security. In more secure environments only certain machines may have a network path to certain devices. .sp Now our salt\-minions know if they are supposed to spawn a proxy\-minion process to control a particular device. That proxy\-minion process will initiate a connection back to the master to enable control. .SS Proxytypes .sp A proxytype is a Python class called \(aqProxyconn\(aq that encapsulates all the code necessary to interface with a device. Proxytypes are located inside the salt.proxy module. At a minimum a proxytype object must implement the following methods: .sp \fBproxytype(self)\fP: Returns a string with the name of the proxy type. .sp \fBproxyconn(self, **kwargs)\fP: Provides the primary way to connect and communicate with the device. Some proxyconns instantiate a particular object that opens a network connection to a device and leaves the connection open for communication. Others simply abstract a serial connection or even implement endpoints to communicate via REST over HTTP. .sp \fBid(self, opts)\fP: Returns a unique, unchanging id for the controlled device. This is the "name" of the device, and is used by the salt\-master for targeting and key authentication. .sp Optionally, the class may define a \fBshutdown(self, opts)\fP method if the controlled device should be informed when the minion goes away cleanly. .sp It is highly recommended that the \fBtest.ping\fP execution module also be defined for a proxytype. The code for \fBping\fP should contact the controlled device and make sure it is really available. .sp Here is an example proxytype used to interface to Juniper Networks devices that run the Junos operating system. Note the additional library requirements\-\-most of the "hard part" of talking to these devices is handled by the jnpr.junos, jnpr.junos.utils and jnpr.junos.cfg modules. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C # Import python libs import logging import os import jnpr.junos import jnpr.junos.utils import jnpr.junos.cfg HAS_JUNOS = True class Proxyconn(object): def __init__(self, details): self.conn = jnpr.junos.Device(user=details[\(aqusername\(aq], host=details[\(aqhost\(aq], password=details[\(aqpasswd\(aq]) self.conn.open() self.conn.bind(cu=jnpr.junos.cfg.Resource) def proxytype(self): return \(aqjunos\(aq def id(self, opts): return self.conn.facts[\(aqhostname\(aq] def ping(self): return self.conn.connected def shutdown(self, opts): print(\(aqProxy module {} shutting down!!\(aq.format(opts[\(aqid\(aq])) try: self.conn.close() except Exception: pass .ft P .fi .UNINDENT .UNINDENT .sp Grains are data about minions. Most proxied devices will have a paltry amount of data as compared to a typical Linux server. Because proxy\-minions are started by a regular minion, they inherit a sizeable number of grain settings which can be useful, especially when targeting (PYTHONPATH, for example). .sp All proxy minions set a grain called \(aqproxy\(aq. If it is present, you know the minion is controlling another device. To add more grains to your proxy minion for a particular device, create a file in salt/grains named [proxytype].py and place inside it the different functions that need to be run to collect the data you are interested in. Here\(aqs an example: .SS The __proxyenabled__ directive .sp Salt states and execution modules, by and large, cannot "automatically" work with proxied devices. Execution modules like \fBpkg\fP or \fBsqlite3\fP have no meaning on a network switch or a housecat. For a state/execution module to be available to a proxy\-minion, the \fB__proxyenabled__\fP variable must be defined in the module as an array containing the names of all the proxytypes that this module can support. The array can contain the special value \fB*\fP to indicate that the module supports all proxies. .sp If no \fB__proxyenabled__\fP variable is defined, then by default, the state/execution module is unavailable to any proxy. .sp Here is an excerpt from a module that was modified to support proxy\-minions: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C def ping(): if \(aqproxyobject\(aq in __opts__: if \(aqping\(aq in __opts__[\(aqproxyobject\(aq].__attr__(): return __opts[\(aqproxyobject\(aq].ping() else: return False else: return True .ft P .fi .UNINDENT .UNINDENT .sp And then in salt.proxy.junos we find .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C def ping(self): return self.connected .ft P .fi .UNINDENT .UNINDENT .sp The Junos API layer lacks the ability to do a traditional \(aqping\(aq, so the example simply checks the connection object field that indicates if the ssh connection was successfully made to the device. .SH LOGGING .sp The salt project tries to get the logging to work for you and help us solve any issues you might find along the way. .sp If you want to get some more information on the nitty\-gritty of salt\(aqs logging system, please head over to the \fBlogging development document\fP, if all you\(aqre after is salt\(aqs logging configurations, please continue reading. .SS Available Configuration Settings .SS \fBlog_file\fP .sp The log records can be sent to a regular file, local path name, or network location. Remote logging works best when configured to use rsyslogd(8) (e.g.: \fBfile:///dev/log\fP), with rsyslogd(8) configured for network logging. The format for remote addresses is: \fB://:/\fP\&. .sp Default: Dependent of the binary being executed, for example, for \fBsalt\-master\fP, \fB/var/log/salt/master\fP\&. .sp Examples: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C log_file: /var/log/salt/master .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C log_file: /var/log/salt/minion .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C log_file: file:///dev/log .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C log_file: udp://loghost:10514 .ft P .fi .UNINDENT .UNINDENT .SS \fBlog_level\fP .sp Default: \fBwarning\fP .sp The level of log record messages to send to the console. One of \fBall\fP, \fBgarbage\fP, \fBtrace\fP, \fBdebug\fP, \fBinfo\fP, \fBwarning\fP, \fBerror\fP, \fBcritical\fP, \fBquiet\fP\&. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C log_level: warning .ft P .fi .UNINDENT .UNINDENT .SS \fBlog_level_logfile\fP .sp Default: \fBwarning\fP .sp The level of messages to send to the log file. One of \fBall\fP, \fBgarbage\fP, \fBtrace\fP, \fBdebug\fP, \fBinfo\fP, \fBwarning\fP, \fBerror\fP, \fBcritical\fP, \fBquiet\fP\&. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C log_level_logfile: warning .ft P .fi .UNINDENT .UNINDENT .SS \fBlog_datefmt\fP .sp Default: \fB%H:%M:%S\fP .sp The date and time format used in console log messages. Allowed date/time formatting can be seen on \fI\%time.strftime\fP\&. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C log_datefmt: \(aq%H:%M:%S\(aq .ft P .fi .UNINDENT .UNINDENT .SS \fBlog_datefmt_logfile\fP .sp Default: \fB%Y\-%m\-%d %H:%M:%S\fP .sp The date and time format used in log file messages. Allowed date/time formatting can be seen on \fI\%time.strftime\fP\&. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C log_datefmt_logfile: \(aq%Y\-%m\-%d %H:%M:%S\(aq .ft P .fi .UNINDENT .UNINDENT .SS \fBlog_fmt_console\fP .sp Default: \fB[%(levelname)\-8s] %(message)s\fP .sp The format of the console logging messages. Allowed formatting options can be seen on the \fI\%LogRecord attributes\fP\&. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C log_fmt_console: \(aq[%(levelname)\-8s] %(message)s\(aq .ft P .fi .UNINDENT .UNINDENT .SS \fBlog_fmt_logfile\fP .sp Default: \fB%(asctime)s,%(msecs)03.0f [%(name)\-17s][%(levelname)\-8s] %(message)s\fP .sp The format of the log file logging messages. Allowed formatting options can be seen on the \fI\%LogRecord attributes\fP\&. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C log_fmt_logfile: \(aq%(asctime)s,%(msecs)03.0f [%(name)\-17s][%(levelname)\-8s] %(message)s\(aq .ft P .fi .UNINDENT .UNINDENT .SS \fBlog_granular_levels\fP .sp Default: \fB{}\fP .sp This can be used to control logging levels more specifically. The example sets the main salt library at the \(aqwarning\(aq level, but sets \fBsalt.modules\fP to log at the \fBdebug\fP level: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C log_granular_levels: \(aqsalt\(aq: \(aqwarning\(aq, \(aqsalt.modules\(aq: \(aqdebug\(aq .ft P .fi .UNINDENT .UNINDENT .SS External Logging Handlers .sp Besides the internal logging handlers used by salt, there are some external which can be used, see the \fBexternal logging handlers\fP document. .SH EXTERNAL LOGGING HANDLERS .TS center; |l|l|. _ T{ \fBlogstash_mod\fP T} T{ T} _ T{ \fBsentry_mod\fP T} T{ T} _ .TE .SS Logstash Logging Handler .sp New in version 0.17.0. .sp This module provides some \fI\%Logstash\fP logging handlers. .SS UDP Logging Handler .sp In order to setup the datagram handler for \fI\%Logstash\fP, please define on the salt configuration file: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C logstash_udp_handler: host: 127.0.0.1 port: 9999 .ft P .fi .UNINDENT .UNINDENT .sp On the \fI\%Logstash\fP configuration file you need something like: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C input { udp { type => "udp\-type" format => "json_event" } } .ft P .fi .UNINDENT .UNINDENT .sp Please read the \fI\%UDP input\fP configuration page for additional information. .SS ZeroMQ Logging Handler .sp In order to setup the ZMQ handler for \fI\%Logstash\fP, please define on the salt configuration file: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C logstash_zmq_handler: address: tcp://127.0.0.1:2021 .ft P .fi .UNINDENT .UNINDENT .sp On the \fI\%Logstash\fP configuration file you need something like: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C input { zeromq { type => "zeromq\-type" mode => "server" topology => "pubsub" address => "tcp://0.0.0.0:2021" charset => "UTF\-8" format => "json_event" } } .ft P .fi .UNINDENT .UNINDENT .sp Please read the \fI\%ZeroMQ input\fP configuration page for additional information. .INDENT 0.0 .INDENT 3.5 .IP "Important Logstash Setting" .sp One of the most important settings that you should not forget on your \fI\%Logstash\fP configuration file regarding these logging handlers is \fBformat\fP\&. Both the \fIUDP\fP and \fIZeroMQ\fP inputs need to have \fBformat\fP as \fBjson_event\fP which is what we send over the wire. .UNINDENT .UNINDENT .SS Log Level .sp Both the \fBlogstash_udp_handler\fP and the \fBlogstash_zmq_handler\fP configuration sections accept an additional setting \fBlog_level\fP\&. If not set, the logging level used will be the one defined for \fBlog_level\fP in the global configuration file section. .SS HWM .sp The \fI\%high water mark\fP for the ZMQ socket setting. Only applicable for the \fBlogstash_zmq_handler\fP\&. .INDENT 0.0 .INDENT 3.5 .IP "Inspiration" .sp This work was inspired in \fI\%pylogstash\fP, \fI\%python\-logstash\fP, \fI\%canary\fP and the \fI\%PyZMQ logging handler\fP\&. .UNINDENT .UNINDENT .SS Sentry Logging Handler .sp New in version 0.17.0. .sp This module provides a \fI\%Sentry\fP logging handler. .INDENT 0.0 .INDENT 3.5 .IP "Note" .sp The \fI\%Raven\fP library needs to be installed on the system for this logging handler to be available. .UNINDENT .UNINDENT .sp Configuring the python \fI\%Sentry\fP client, \fI\%Raven\fP, should be done under the \fBsentry_handler\fP configuration key. At the bare minimum, you need to define the \fI\%DSN\fP\&. As an example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C sentry_handler: dsn: https://pub\-key:secret\-key@app.getsentry.com/app\-id .ft P .fi .UNINDENT .UNINDENT .sp More complex configurations can be achieved, for example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C sentry_handler: servers: \- https://sentry.example.com \- http://192.168.1.1 project: app\-id public_key: deadbeefdeadbeefdeadbeefdeadbeef secret_key: beefdeadbeefdeadbeefdeadbeefdead .ft P .fi .UNINDENT .UNINDENT .sp All the client configuration keys are supported, please see the \fI\%Raven client documentation\fP\&. .sp The default logging level for the sentry handler is \fBERROR\fP\&. If you wish to define a different one, define \fBlog_level\fP under the \fBsentry_handler\fP configuration key: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C sentry_handler: dsn: https://pub\-key:secret\-key@app.getsentry.com/app\-id log_level: warning .ft P .fi .UNINDENT .UNINDENT .sp The available log levels are those also available for the salt \fBcli\fP tools and configuration; \fBsalt \-\-help\fP should give you the required information. .SS Threaded Transports .sp Raven\(aqs documents rightly suggest using its threaded transport for critical applications. However, don\(aqt forget that if you start having troubles with Salt after enabling the threaded transport, please try switching to a non\-threaded transport to see if that fixes your problem. .SH LOGSTASH LOGGING HANDLER .sp New in version 0.17.0. .sp This module provides some \fI\%Logstash\fP logging handlers. .SS UDP Logging Handler .sp In order to setup the datagram handler for \fI\%Logstash\fP, please define on the salt configuration file: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C logstash_udp_handler: host: 127.0.0.1 port: 9999 .ft P .fi .UNINDENT .UNINDENT .sp On the \fI\%Logstash\fP configuration file you need something like: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C input { udp { type => "udp\-type" format => "json_event" } } .ft P .fi .UNINDENT .UNINDENT .sp Please read the \fI\%UDP input\fP configuration page for additional information. .SS ZeroMQ Logging Handler .sp In order to setup the ZMQ handler for \fI\%Logstash\fP, please define on the salt configuration file: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C logstash_zmq_handler: address: tcp://127.0.0.1:2021 .ft P .fi .UNINDENT .UNINDENT .sp On the \fI\%Logstash\fP configuration file you need something like: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C input { zeromq { type => "zeromq\-type" mode => "server" topology => "pubsub" address => "tcp://0.0.0.0:2021" charset => "UTF\-8" format => "json_event" } } .ft P .fi .UNINDENT .UNINDENT .sp Please read the \fI\%ZeroMQ input\fP configuration page for additional information. .INDENT 0.0 .INDENT 3.5 .IP "Important Logstash Setting" .sp One of the most important settings that you should not forget on your \fI\%Logstash\fP configuration file regarding these logging handlers is \fBformat\fP\&. Both the \fIUDP\fP and \fIZeroMQ\fP inputs need to have \fBformat\fP as \fBjson_event\fP which is what we send over the wire. .UNINDENT .UNINDENT .SS Log Level .sp Both the \fBlogstash_udp_handler\fP and the \fBlogstash_zmq_handler\fP configuration sections accept an additional setting \fBlog_level\fP\&. If not set, the logging level used will be the one defined for \fBlog_level\fP in the global configuration file section. .SS HWM .sp The \fI\%high water mark\fP for the ZMQ socket setting. Only applicable for the \fBlogstash_zmq_handler\fP\&. .INDENT 0.0 .INDENT 3.5 .IP "Inspiration" .sp This work was inspired in \fI\%pylogstash\fP, \fI\%python\-logstash\fP, \fI\%canary\fP and the \fI\%PyZMQ logging handler\fP\&. .UNINDENT .UNINDENT .SH SENTRY LOGGING HANDLER .sp New in version 0.17.0. .sp This module provides a \fI\%Sentry\fP logging handler. .INDENT 0.0 .INDENT 3.5 .IP "Note" .sp The \fI\%Raven\fP library needs to be installed on the system for this logging handler to be available. .UNINDENT .UNINDENT .sp Configuring the python \fI\%Sentry\fP client, \fI\%Raven\fP, should be done under the \fBsentry_handler\fP configuration key. At the bare minimum, you need to define the \fI\%DSN\fP\&. As an example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C sentry_handler: dsn: https://pub\-key:secret\-key@app.getsentry.com/app\-id .ft P .fi .UNINDENT .UNINDENT .sp More complex configurations can be achieved, for example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C sentry_handler: servers: \- https://sentry.example.com \- http://192.168.1.1 project: app\-id public_key: deadbeefdeadbeefdeadbeefdeadbeef secret_key: beefdeadbeefdeadbeefdeadbeefdead .ft P .fi .UNINDENT .UNINDENT .sp All the client configuration keys are supported, please see the \fI\%Raven client documentation\fP\&. .sp The default logging level for the sentry handler is \fBERROR\fP\&. If you wish to define a different one, define \fBlog_level\fP under the \fBsentry_handler\fP configuration key: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C sentry_handler: dsn: https://pub\-key:secret\-key@app.getsentry.com/app\-id log_level: warning .ft P .fi .UNINDENT .UNINDENT .sp The available log levels are those also available for the salt \fBcli\fP tools and configuration; \fBsalt \-\-help\fP should give you the required information. .SS Threaded Transports .sp Raven\(aqs documents rightly suggest using its threaded transport for critical applications. However, don\(aqt forget that if you start having troubles with Salt after enabling the threaded transport, please try switching to a non\-threaded transport to see if that fixes your problem. .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 without assuming 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. .sp \fBSEE ALSO:\fP .INDENT 0.0 .INDENT 3.5 \fIclient\-apis\fP .UNINDENT .UNINDENT .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 EXECUTION MODULES .sp Salt execution modules are the functions called by the \fBsalt\fP command. .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 Salt execution modules are different from state modules and cannot be called directly within state files. You must use the \fImodule\fP state module to execute execution modules within state runs. .UNINDENT .UNINDENT .sp \fBSEE ALSO:\fP .INDENT 0.0 .INDENT 3.5 \fIFull list of builtin modules\fP .sp Salt ships with many modules that cover a wide variety of tasks. .UNINDENT .UNINDENT .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 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 Any custom modules which have been synced to a minion, that are named the same as one of Salt\(aqs default set of modules, will take the place of the default module with the same name. Note that a module\(aqs default name is its filename (i.e. \fBfoo.py\fP becomes module \fBfoo\fP), but that its name can be overridden by using a \fI__virtual__ function\fP\&. .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: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C def foo(bar): return __salt__[\(aqcmd.run\(aq](bar) .ft P .fi .UNINDENT .UNINDENT .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: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt \(aqhostname\(aq grains.items .ft P .fi .UNINDENT .UNINDENT .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. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C __outputter__ = { \(aqrun\(aq: \(aqtxt\(aq } .ft P .fi .UNINDENT .UNINDENT .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. Some examples: .INDENT 0.0 .IP \(bu 2 \fI\%pacman.py\fP .IP \(bu 2 \fI\%yumpkg.py\fP .IP \(bu 2 \fI\%apt.py\fP .UNINDENT .SS Documentation .sp Salt modules are self documenting, the \fBsys.doc()\fP function will return the documentation for all available modules: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq sys.doc .ft P .fi .UNINDENT .UNINDENT .sp This function simply prints out the docstrings found in the modules; when writing Salt modules, please follow the formatting 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. .INDENT 0.0 .INDENT 3.5 .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 .UNINDENT .UNINDENT .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: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C :maintainer: Thomas Hatch :maturity: new :depends: python\-mysqldb :platform: all .ft P .fi .UNINDENT .UNINDENT .sp The maintainer 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 module 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 .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C def foo(bar): return bar class baz: def __init__(self, quo): pass .ft P .fi .UNINDENT .UNINDENT .SS Objects NOT Loaded into the Salt Minion .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C def _foobar(baz): # Preceded with an _ return baz cheese = {} # Not a callable Python object .ft P .fi .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 Some callable names also end with an underscore \fB_\fP, to avoid keyword clashes with Python keywords. When using Salt modules, or state modules, with these in them the trailing underscore should be omitted. .UNINDENT .UNINDENT .SS Useful Decorators for Modules .sp Sometimes when writing modules for large scale deployments you run into some small things that end up severely complicating the code. To alleviate some of this pain Salt has some useful decorators for use within modules! .SS Depends Decorator .sp When writing custom modules there are many times where some of the module will work on all hosts, but some functions require (for example) a service to be installed. Instead of trying to wrap much of the code in large try/except blocks you can use a simple decorator to do this. If the dependencies passed to the decorator don\(aqt exist, then the salt minion will remove those functions from the module on that host. If a "fallback_function" is defined, it will replace the function instead of removing it .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C from salt.utils.decorators import depends try: import dependency_that_sometimes_exists except ImportError: pass @depends(\(aqdependency_that_sometimes_exists\(aq) def foo(): \(aq\(aq\(aq Function with a dependency on the "dependency_that_sometimes_exists" module, if the "dependency_that_sometimes_exists" is missing this function will not exist \(aq\(aq\(aq return True def _fallback(): \(aq\(aq\(aq Fallback function for the depends decorator to replace a function with \(aq\(aq\(aq return \(aq"dependency_that_sometimes_exists" needs to be installed for this function to exist\(aq @depends(\(aqdependency_that_sometimes_exists\(aq, fallback_function=_fallback) def foo(): \(aq\(aq\(aq Function with a dependency on the "dependency_that_sometimes_exists" module. If the "dependency_that_sometimes_exists" is missing this function will be replaced with "_fallback" \(aq\(aq\(aq return True .ft P .fi .UNINDENT .UNINDENT .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: .INDENT 0.0 .INDENT 3.5 .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 .UNINDENT .UNINDENT .SH FULL LIST OF BUILTIN EXECUTION MODULES .INDENT 0.0 .INDENT 3.5 .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.brew\fP .IP \(bu 2 \fBsalt.modules.ebuild\fP .IP \(bu 2 \fBsalt.modules.freebsdpkg\fP .IP \(bu 2 \fBsalt.modules.openbsdpkg\fP .IP \(bu 2 \fBsalt.modules.pacman\fP .IP \(bu 2 \fBsalt.modules.pkgin\fP .IP \(bu 2 \fBsalt.modules.pkgng\fP .IP \(bu 2 \fBsalt.modules.pkgutil\fP .IP \(bu 2 \fBsalt.modules.solarispkg\fP .IP \(bu 2 \fBsalt.modules.win_pkg\fP .IP \(bu 2 \fBsalt.modules.yumpkg\fP .IP \(bu 2 \fBsalt.modules.yumpkg5\fP .IP \(bu 2 \fBsalt.modules.zypper\fP .UNINDENT .UNINDENT .UNINDENT .TS center; |l|l|. _ T{ \fBaliases\fP T} T{ T} _ T{ \fBalternatives\fP T} T{ T} _ T{ \fBapache\fP T} T{ T} _ T{ \fBaptpkg\fP T} T{ T} _ T{ \fBarchive\fP T} T{ T} _ T{ \fBat\fP T} T{ T} _ T{ \fBaugeas_cfg\fP T} T{ T} _ T{ \fBaws_sqs\fP T} T{ T} _ T{ \fBbluez\fP T} T{ T} _ T{ \fBbrew\fP T} T{ T} _ T{ \fBbridge\fP T} T{ T} _ T{ \fBbsd_shadow\fP T} T{ T} _ T{ \fBcassandra\fP T} T{ T} _ T{ \fBchocolatey\fP T} T{ T} _ T{ \fBcloud\fP T} T{ T} _ T{ \fBcmdmod\fP T} T{ T} _ T{ \fBcomposer\fP T} T{ T} _ T{ \fBconfig\fP T} T{ T} _ T{ \fBcp\fP T} T{ T} _ T{ \fBcron\fP T} T{ T} _ T{ \fBdaemontools\fP T} T{ T} _ T{ \fBdarwin_sysctl\fP T} T{ T} _ T{ \fBdata\fP T} T{ T} _ T{ \fBddns\fP T} T{ T} _ T{ \fBdebconfmod\fP T} T{ T} _ T{ \fBdebian_ip\fP T} T{ T} _ T{ \fBdebian_service\fP T} T{ T} _ T{ \fBdig\fP T} T{ T} _ T{ \fBdisk\fP T} T{ T} _ T{ \fBdjangomod\fP T} T{ T} _ T{ \fBdnsmasq\fP T} T{ T} _ T{ \fBdnsutil\fP T} T{ T} _ T{ \fBdockerio\fP T} T{ T} _ T{ \fBdpkg\fP T} T{ T} _ T{ \fBebuild\fP T} T{ T} _ T{ \fBeix\fP T} T{ T} _ T{ \fBeselect\fP T} T{ T} _ T{ \fBevent\fP T} T{ T} _ T{ \fBextfs\fP T} T{ T} _ T{ \fBfile\fP T} T{ T} _ T{ \fBfreebsd_sysctl\fP T} T{ T} _ T{ \fBfreebsdjail\fP T} T{ T} _ T{ \fBfreebsdkmod\fP T} T{ T} _ T{ \fBfreebsdpkg\fP T} T{ T} _ T{ \fBfreebsdports\fP T} T{ T} _ T{ \fBfreebsdservice\fP T} T{ T} _ T{ \fBgem\fP T} T{ T} _ T{ \fBgentoo_service\fP T} T{ T} _ T{ \fBgentoolkitmod\fP T} T{ T} _ T{ \fBgit\fP T} T{ T} _ T{ \fBglance\fP T} T{ T} _ T{ \fBgnomedesktop\fP T} T{ T} _ T{ \fBgrains\fP T} T{ T} _ T{ \fBgroupadd\fP T} T{ T} _ T{ \fBgrub_legacy\fP T} T{ T} _ T{ \fBguestfs\fP T} T{ T} _ T{ \fBhg\fP T} T{ T} _ T{ \fBhosts\fP T} T{ T} _ T{ \fBhtpasswd\fP T} T{ T} _ T{ \fBimg\fP T} T{ T} _ T{ \fBiptables\fP T} T{ T} _ T{ \fBkey\fP T} T{ T} _ T{ \fBkeyboard\fP T} T{ T} _ T{ \fBkeystone\fP T} T{ T} _ T{ \fBkmod\fP T} T{ T} _ T{ \fBlaunchctl\fP T} T{ T} _ T{ \fBlayman\fP T} T{ T} _ T{ \fBldapmod\fP T} T{ T} _ T{ \fBlinux_acl\fP T} T{ T} _ T{ \fBlinux_lvm\fP T} T{ T} _ T{ \fBlinux_sysctl\fP T} T{ T} _ T{ \fBlocalemod\fP T} T{ T} _ T{ \fBlocate\fP T} T{ T} _ T{ \fBlogrotate\fP T} T{ T} _ T{ \fBlvs\fP T} T{ T} _ T{ \fBlxc\fP T} T{ T} _ T{ \fBmac_group\fP T} T{ T} _ T{ \fBmac_user\fP T} T{ T} _ T{ \fBmakeconf\fP T} T{ T} _ T{ \fBmatch\fP T} T{ T} _ T{ \fBmdadm\fP T} T{ T} _ T{ \fBmemcached\fP T} T{ T} _ T{ \fBmine\fP T} T{ T} _ T{ \fBmodjk\fP T} T{ T} _ T{ \fBmongodb\fP T} T{ T} _ T{ \fBmonit\fP T} T{ T} _ T{ \fBmoosefs\fP T} T{ T} _ T{ \fBmount\fP T} T{ T} _ T{ \fBmunin\fP T} T{ T} _ T{ \fBmysql\fP T} T{ T} _ T{ \fBnetbsd_sysctl\fP T} T{ T} _ T{ \fBnetbsdservice\fP T} T{ T} _ T{ \fBnetwork\fP T} T{ T} _ T{ \fBnfs3\fP T} T{ T} _ T{ \fBnginx\fP T} T{ T} _ T{ \fBnova\fP T} T{ T} _ T{ \fBnpm\fP T} T{ T} _ T{ \fBomapi\fP T} T{ T} _ T{ \fBopenbsdpkg\fP T} T{ T} _ T{ \fBopenbsdservice\fP T} T{ T} _ T{ \fBopenstack_config\fP T} T{ T} _ T{ \fBosxdesktop\fP T} T{ T} _ T{ \fBpacman\fP T} T{ T} _ T{ \fBpagerduty\fP T} T{ T} _ T{ \fBpam\fP T} T{ T} _ T{ \fBparted\fP T} T{ T} _ T{ \fBpecl\fP T} T{ T} _ T{ \fBpillar\fP T} T{ T} _ T{ \fBpip\fP T} T{ T} _ T{ \fBpkg_resource\fP T} T{ T} _ T{ \fBpkgin\fP T} T{ T} _ T{ \fBpkgng\fP T} T{ T} _ T{ \fBpkgutil\fP T} T{ Utilities to support packages. T} _ T{ \fBportage_config\fP T} T{ T} _ T{ \fBpostgres\fP T} T{ T} _ T{ \fBpoudriere\fP T} T{ T} _ T{ \fBpowerpath\fP T} T{ T} _ T{ \fBps\fP T} T{ T} _ T{ \fBpublish\fP T} T{ T} _ T{ \fBpuppet\fP T} T{ T} _ T{ \fBpw_group\fP T} T{ T} _ T{ \fBpw_user\fP T} T{ T} _ T{ \fBqemu_img\fP T} T{ T} _ T{ \fBqemu_nbd\fP T} T{ T} _ T{ \fBquota\fP T} T{ T} _ T{ \fBrabbitmq\fP T} T{ T} _ T{ \fBrbenv\fP T} T{ T} _ T{ \fBrdp\fP T} T{ T} _ T{ \fBreg\fP T} T{ T} _ T{ \fBret\fP T} T{ T} _ T{ \fBrh_ip\fP T} T{ T} _ T{ \fBrh_service\fP T} T{ T} _ T{ \fBriak\fP T} T{ T} _ T{ \fBrpm\fP T} T{ Mock out specified imports T} _ T{ \fBrvm\fP T} T{ T} _ T{ \fBs3\fP T} T{ T} _ T{ \fBsaltcloudmod\fP T} T{ T} _ T{ \fBsaltutil\fP T} T{ T} _ T{ \fBseed\fP T} T{ T} _ T{ \fBselinux\fP T} T{ T} _ T{ \fBservice\fP T} T{ T} _ T{ \fBshadow\fP T} T{ T} _ T{ \fBsmartos_imgadm\fP T} T{ T} _ T{ \fBsmartos_vmadm\fP T} T{ T} _ T{ \fBsmf\fP T} T{ T} _ T{ \fBsolaris_group\fP T} T{ T} _ T{ \fBsolaris_shadow\fP T} T{ T} _ T{ \fBsolaris_user\fP T} T{ T} _ T{ \fBsolarispkg\fP T} T{ T} _ T{ \fBsolr\fP T} T{ T} _ T{ \fBsqlite3\fP T} T{ T} _ T{ \fBssh\fP T} T{ T} _ T{ \fBstate\fP T} T{ T} _ T{ \fBstatus\fP T} T{ T} _ T{ \fBsupervisord\fP T} T{ T} _ T{ \fBsvn\fP T} T{ T} _ T{ \fBsysbench\fP T} T{ T} _ T{ \fBsysmod\fP T} T{ T} _ T{ \fBsystem\fP T} T{ T} _ T{ \fBsystemd\fP T} T{ T} _ T{ \fBtest\fP T} T{ T} _ T{ \fBtimezone\fP T} T{ T} _ T{ \fBtls\fP T} T{ T} _ T{ \fBtomcat\fP T} T{ T} _ T{ \fBupstart\fP T} T{ T} _ T{ \fBuseradd\fP T} T{ T} _ T{ \fBvirt\fP T} T{ T} _ T{ \fBvirtualenv_mod\fP T} T{ T} _ T{ \fBwin_autoruns\fP T} T{ T} _ T{ \fBwin_disk\fP T} T{ T} _ T{ \fBwin_dns_client\fP T} T{ T} _ T{ \fBwin_file\fP T} T{ T} _ T{ \fBwin_firewall\fP T} T{ T} _ T{ \fBwin_groupadd\fP T} T{ T} _ T{ \fBwin_ip\fP T} T{ T} _ T{ \fBwin_network\fP T} T{ T} _ T{ \fBwin_ntp\fP T} T{ T} _ T{ \fBwin_path\fP T} T{ T} _ T{ \fBwin_pkg\fP T} T{ T} _ T{ \fBwin_repo\fP T} T{ T} _ T{ \fBwin_servermanager\fP T} T{ T} _ T{ \fBwin_service\fP T} T{ T} _ T{ \fBwin_shadow\fP T} T{ T} _ T{ \fBwin_status\fP T} T{ T} _ T{ \fBwin_system\fP T} T{ T} _ T{ \fBwin_timezone\fP T} T{ T} _ T{ \fBwin_useradd\fP T} T{ T} _ T{ \fBxapi\fP T} T{ T} _ T{ \fBxmpp\fP T} T{ T} _ T{ \fByumpkg\fP T} T{ T} _ T{ \fBzcbuildout\fP T} T{ T} _ T{ \fBzfs\fP T} T{ Mock out specified imports T} _ T{ \fBzpool\fP T} T{ T} _ T{ \fBzypper\fP T} T{ 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: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq aliases.get_target alias .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.aliases.has_target(alias, target) Return true if the alias/target is set .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq aliases.has_target alias target .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.aliases.list_aliases() Return the aliases found in the aliases file in this format: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C {\(aqalias\(aq: \(aqtarget\(aq} .ft P .fi .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq aliases.list_aliases .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.aliases.rm_alias(alias) Remove an entry from the aliases file .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq aliases.rm_alias alias .ft P .fi .UNINDENT .UNINDENT .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: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq aliases.set_target alias target .ft P .fi .UNINDENT .UNINDENT .UNINDENT .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.auto(name) Trigger alternatives to set the path for as specified by priority. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq alternatives.auto name .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.alternatives.check_installed(name, path) Check if the current highest\-priority match for a given alternatives link is set to the desired path .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq alternatives.check_installed name path .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.alternatives.display(name) Display alternatives settings for defined command name .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq alternatives.display editor .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.alternatives.install(name, link, path, priority) Install symbolic links determining default commands .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq alternatives.install editor /usr/bin/editor /usr/bin/emacs23 50 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.alternatives.remove(name, path) Remove symbolic links determining the default commands. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq alternatives.remove name path .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.alternatives.set_(name, path) Manually set the alternative for . .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq alternatives.set name path .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.alternatives.show_current(name) Display the current highest\-priority alternative for a given alternatives link .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq alternatives.show_current editor .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.apache .sp Support for Apache .INDENT 0.0 .TP .B salt.modules.apache.a2dissite(site) Runs a2dissite for the given site. .sp This will only be functional on Debian\-based operating systems (Ubuntu, Mint, etc). .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq apache.a2dissite example.com .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.apache.a2ensite(site) Runs a2ensite for the given site. .sp This will only be functional on Debian\-based operating systems (Ubuntu, Mint, etc). .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq apache.a2ensite example.com .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.apache.check_site_enabled(site) Checks to see if the specific Site symlink is in /etc/apache2/sites\-enabled. .sp This will only be functional on Debian\-based operating systems (Ubuntu, Mint, etc). .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq apache.check_site_enabled example.com .ft P .fi .UNINDENT .UNINDENT .UNINDENT .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: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq apache.directives .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.apache.fullversion() Return server version from apachectl \-V .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq apache.fullversion .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.apache.modules() Return list of static and shared modules from apachectl \-M .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq apache.modules .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.apache.server_status(profile=\(aqdefault\(aq) Get Information from the Apache server\-status handler .sp NOTE: the server\-status handler is disabled by default. in order for this function to work it needs to be enabled. \fI\%http://httpd.apache.org/docs/2.2/mod/mod_status.html\fP .sp The following configuration needs to exists in pillar/grains each entry nested in apache.server\-status is a profile of a vhost/server this would give support for multiple apache servers/vhosts .INDENT 7.0 .TP .B apache.server\-status: .INDENT 7.0 .TP .B \(aqdefault\(aq: \(aqurl\(aq: \fI\%http://localhost/server\-status\fP \(aquser\(aq: someuser \(aqpass\(aq: password \(aqrealm\(aq: \(aqauthentication realm for digest passwords\(aq \(aqtimeout\(aq: 5 .UNINDENT .UNINDENT .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq apache.server_status salt \(aq*\(aq apache.server_status other\-profile .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.apache.servermods() Return list of modules compiled into the server (apachectl \-l) .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq apache.servermods .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.apache.signal(signal=None) Signals httpd to start, restart, or stop. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq apache.signal restart .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.apache.useradd(pwfile, user, password, opts=\(aq\(aq) Add an HTTP user using the htpasswd command. If the htpasswd file does not exist, it will be created. Valid options that can be passed are: .INDENT 7.0 .INDENT 3.5 n Don\(aqt update file; display results on stdout. m Force MD5 encryption of the password (default). d Force CRYPT encryption of the password. p Do not encrypt the password (plaintext). s Force SHA encryption of the password. .UNINDENT .UNINDENT .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq apache.useradd /etc/httpd/htpasswd larry badpassword salt \(aq*\(aq apache.useradd /etc/httpd/htpasswd larry badpass opts=ns .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.apache.userdel(pwfile, user) Delete an HTTP user from the specified htpasswd file. .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq apache.userdel /etc/httpd/htpasswd larry .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.apache.version() Return server version from apachectl \-v .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq apache.version .ft P .fi .UNINDENT .UNINDENT .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: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \-t 10 \(aq*\(aq apache.vhosts .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.aptpkg .sp Support for APT (Advanced Packaging Tool) .INDENT 0.0 .TP .B salt.modules.aptpkg.del_repo(repo, **kwargs) 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: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.del_repo "myrepo definition" .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.aptpkg.expand_repo_def(repokwargs) Take a repository definition and expand it to the full pkg repository dict that can be used for comparison. This is a helper function to make the Debian/Ubuntu apt sources sane for comparison in the pkgrepo states. .sp There is no use to calling this function via the CLI. .UNINDENT .INDENT 0.0 .TP .B salt.modules.aptpkg.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: .INDENT 7.0 .INDENT 3.5 .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 .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.aptpkg.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: .INDENT 7.0 .INDENT 3.5 .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 .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.aptpkg.get_repo(repo, **kwargs) Display a repo from the sources.list / sources.list.d .sp The repo passed in needs to be a complete repo entry. .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.get_repo "myrepo definition" .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.aptpkg.get_selections(pattern=None, state=None) View package state from the dpkg database. .sp Returns a dict of dicts containing the state, and package names: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C {\(aq\(aq: {\(aq\(aq: [\(aqpkg1\(aq, ... ] }, ... } .ft P .fi .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.get_selections salt \(aq*\(aq pkg.get_selections \(aqpython\-*\(aq salt \(aq*\(aq pkg.get_selections state=hold salt \(aq*\(aq pkg.get_selections \(aqopenssh*\(aq state=hold .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.aptpkg.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. .sp 32\-bit packages can be installed on 64\-bit systems by appending the architecture designation (\fB:i386\fP, etc.) to the end of the package name. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.install .ft P .fi .UNINDENT .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. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.install pkgs=\(aq["foo", "bar"]\(aq salt \(aq*\(aq pkg.install pkgs=\(aq["foo", {"bar": "1.2.3\-0ubuntu0"}]\(aq .ft P .fi .UNINDENT .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. Dependencies are automatically resolved and marked as auto\-installed. .sp 32\-bit packages can be installed on 64\-bit systems by appending the architecture designation (\fB:i386\fP, etc.) to the end of the package name. .sp Changed in version Helium. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.install sources=\(aq[{"foo": "salt://foo.deb"},{"bar": "salt://bar.deb"}]\(aq .ft P .fi .UNINDENT .UNINDENT .TP .B force_yes Passes \fB\-\-force\-yes\fP to the apt\-get command. Don\(aqt use this unless you know what you\(aqre doing. .sp New in version 0.17.4. .UNINDENT .sp Returns a dict containing the new package names and versions: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C {\(aq\(aq: {\(aqold\(aq: \(aq\(aq, \(aqnew\(aq: \(aq\(aq}} .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.aptpkg.latest_version(*names, **kwargs) 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 A specific repo can be requested using the \fBfromrepo\fP keyword argument. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.latest_version salt \(aq*\(aq pkg.latest_version fromrepo=unstable salt \(aq*\(aq pkg.latest_version ... .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.aptpkg.list_pkgs(versions_as_list=False, removed=False, purge_desired=False, **kwargs) List the packages currently installed in a dict: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C {\(aq\(aq: \(aq\(aq} .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .TP .B removed If \fBTrue\fP, then only packages which have been removed (but not purged) will be returned. .TP .B purge_desired If \fBTrue\fP, then only packages which have been marked to be purged, but can\(aqt be purged due to their status as dependencies for other installed packages, will be returned. Note that these packages will appear in installed .sp Changed in version 2014.1.1: Packages in this state now correctly show up in the output of this function. .UNINDENT .sp External dependencies: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C Virtual package resolution requires dctrl\-tools. Without dctrl\-tools virtual packages will be reported as not installed. .ft P .fi .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.list_pkgs salt \(aq*\(aq pkg.list_pkgs versions_as_list=True .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.aptpkg.list_repos() Lists all repos in the sources.list (and sources.lists.d) files .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.list_repos salt \(aq*\(aq pkg.list_repos disabled=True .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.aptpkg.list_upgrades(refresh=True) List all available package upgrades. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.list_upgrades .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.aptpkg.mod_repo(repo, saltenv=\(aqbase\(aq, **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: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C comps (a comma separated list of components for the repo, e.g. "main") file (a file name to be used) 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) * Note: Due to the way keys are stored for apt, there is a known issue where the key wont be updated unless another change is made at the same time. Keys should be properly added on initial configuration. .ft P .fi .UNINDENT .UNINDENT .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .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 .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.aptpkg.purge(name=None, pkgs=None, **kwargs) Remove packages via \fBapt\-get purge\fP along with all configuration files and unused dependencies. .INDENT 7.0 .TP .B name The name of the package to be deleted. .UNINDENT .sp Multiple Package Options: .INDENT 7.0 .TP .B pkgs A list of packages to delete. Must be passed as a python list. The \fBname\fP parameter will be ignored if this option is passed. .UNINDENT .sp New in version 0.16.0. .sp Returns a dict containing the changes. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.purge salt \(aq*\(aq pkg.purge ,, salt \(aq*\(aq pkg.purge pkgs=\(aq["foo", "bar"]\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.aptpkg.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 .IP \(bu 2 \fBTrue\fP: Database updated successfully .IP \(bu 2 \fBFalse\fP: Problem updating database .IP \(bu 2 \fBNone\fP: Database already up\-to\-date .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.refresh_db .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.aptpkg.remove(name=None, pkgs=None, **kwargs) Remove packages using \fBapt\-get remove\fP\&. .INDENT 7.0 .TP .B name The name of the package to be deleted. .UNINDENT .sp Multiple Package Options: .INDENT 7.0 .TP .B pkgs A list of packages to delete. Must be passed as a python list. The \fBname\fP parameter will be ignored if this option is passed. .UNINDENT .sp New in version 0.16.0. .sp Returns a dict containing the changes. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.remove salt \(aq*\(aq pkg.remove ,, salt \(aq*\(aq pkg.remove pkgs=\(aq["foo", "bar"]\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.aptpkg.set_selections(path=None, selection=None, clear=False, saltenv=\(aqbase\(aq) Change package state in the dpkg database. .sp The state can be any one of, documented in \fBdpkg(1)\fP: .INDENT 7.0 .INDENT 3.5 .INDENT 0.0 .IP \(bu 2 install .IP \(bu 2 hold .IP \(bu 2 deinstall .IP \(bu 2 purge .UNINDENT .UNINDENT .UNINDENT .sp This command is commonly used to mark specific packages to be held from being upgraded, that is, to be kept at a certain version. When a state is changed to anything but being held, then it is typically followed by \fBapt\-get \-u dselect\-upgrade\fP\&. .sp Note: Be careful with the \fBclear\fP argument, since it will start with setting all packages to deinstall state. .sp Returns a dict of dicts containing the package names, and the new and old versions: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C {\(aq\(aq: {\(aq\(aq: {\(aqnew\(aq: \(aq\(aq, \(aqold\(aq: \(aq\(aq} }, ... } .ft P .fi .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.set_selections selection=\(aq{"install": ["netcat"]}\(aq salt \(aq*\(aq pkg.set_selections selection=\(aq{"hold": ["openssh\-server", "openssh\-client"]}\(aq salt \(aq*\(aq pkg.set_selections salt://path/to/file salt \(aq*\(aq pkg.set_selections salt://path/to/file clear=True .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.aptpkg.upgrade(refresh=True, **kwargs) Upgrades all packages via \fBapt\-get dist\-upgrade\fP .sp Returns a dict containing the changes. .INDENT 7.0 .INDENT 3.5 .INDENT 0.0 .TP .B {\(aq\(aq: {\(aqold\(aq: \(aq\(aq, \(aqnew\(aq: \(aq\(aq}} .UNINDENT .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.upgrade .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.aptpkg.upgrade_available(name) Check whether or not an upgrade is available for a given package .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.upgrade_available .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.aptpkg.version(*names, **kwargs) 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: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.version salt \(aq*\(aq pkg.version ... .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.aptpkg.version_cmp(pkg1, pkg2) 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: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.version_cmp \(aq0.2.4\-0ubuntu1\(aq \(aq0.2.4.1\-0ubuntu1\(aq .ft P .fi .UNINDENT .UNINDENT .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: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq archive.gunzip /tmp/sourcefile.txt.gz .ft P .fi .UNINDENT .UNINDENT .sp The template arg can be set to \(aqjinja\(aq or another supported template engine to render the command arguments before execution. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq archive.gunzip template=jinja /tmp/{{grains.id}}.txt.gz .ft P .fi .UNINDENT .UNINDENT .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: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq archive.gzip /tmp/sourcefile.txt .ft P .fi .UNINDENT .UNINDENT .sp The template arg can be set to \(aqjinja\(aq or another supported template engine to render the command arguments before execution. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq archive.gzip template=jinja /tmp/{{grains.id}}.txt .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.archive.rar(rarfile, sources, template=None) Uses the rar command to create rar files Uses rar for Linux from \fI\%http://www.rarlab.com/\fP .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq archive.rar /tmp/rarfile.rar /tmp/sourcefile1,/tmp/sourcefile2 .ft P .fi .UNINDENT .UNINDENT .sp The template arg can be set to \(aqjinja\(aq or another supported template engine to render the command arguments before execution. .sp For example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq archive.rar template=jinja /tmp/rarfile.rar /tmp/sourcefile1,/tmp/{{grains.id}}.txt .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.archive.tar(options, tarfile, sources=None, dest=None, cwd=None, template=None) .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 This function has changed for version 0.17.0. In prior versions, the \fBcwd\fP and \fBtemplate\fP arguments must be specified, with the source directories/files coming as a space\-separated list at the end of the command. Beginning with 0.17.0, \fBsources\fP must be a comma\-separated list, and the \fBcwd\fP and \fBtemplate\fP arguments are optional. .UNINDENT .UNINDENT .sp Uses the tar command to pack, unpack, etc tar files .INDENT 7.0 .TP .B options: Options to pass to the \fBtar\fP binary. .TP .B tarfile: The tar filename to pack/unpack. .TP .B sources: Comma delimited list of files to \fBpack\fP into the tarfile. .TP .B dest: The destination directory to \fBunpack\fP the tarfile to. .TP .B cwd: The directory in which the tar command should be executed. .TP .B template: Template engine name to render the command arguments before execution. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq archive.tar cjvf /tmp/tarfile.tar.bz2 /tmp/file_1,/tmp/file_2 .ft P .fi .UNINDENT .UNINDENT .sp The template arg can be set to \fBjinja\fP or another supported template engine to render the command arguments before execution. For example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq archive.tar template=jinja cjvf /tmp/salt.tar.bz2 {{grains.saltpath}} .ft P .fi .UNINDENT .UNINDENT .sp To unpack a tarfile, for example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq archive.tar foo.tar xf dest=/target/directory .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.archive.unrar(rarfile, dest, excludes=None, template=None) Uses the unrar command to unpack rar files Uses rar for Linux from \fI\%http://www.rarlab.com/\fP .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq archive.unrar /tmp/rarfile.rar /home/strongbad/ excludes=file_1,file_2 .ft P .fi .UNINDENT .UNINDENT .sp The template arg can be set to \(aqjinja\(aq or another supported template engine to render the command arguments before execution. .sp For example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq archive.unrar template=jinja /tmp/rarfile.rar /tmp/{{grains.id}}/ excludes=file_1,file_2 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.archive.unzip(zipfile, dest, excludes=None, template=None, options=None) Uses the unzip command to unpack zip files .INDENT 7.0 .TP .B options: Options to pass to the \fBunzip\fP binary. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq archive.unzip /tmp/zipfile.zip /home/strongbad/ excludes=file_1,file_2 .ft P .fi .UNINDENT .UNINDENT .sp The template arg can be set to \(aqjinja\(aq or another supported template engine to render the command arguments before execution. .sp For example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq archive.unzip template=jinja /tmp/zipfile.zip /tmp/{{grains.id}}/ excludes=file_1,file_2 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.archive.zip_(zipfile, sources, template=None) Uses the zip command to create zip files .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq archive.zip /tmp/zipfile.zip /tmp/sourcefile1,/tmp/sourcefile2 .ft P .fi .UNINDENT .UNINDENT .sp The template arg can be set to \(aqjinja\(aq or another supported template engine to render the command arguments before execution. .sp For example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq archive.zip template=jinja /tmp/zipfile.zip /tmp/sourcefile1,/tmp/{{grains.id}}.txt .ft P .fi .UNINDENT .UNINDENT .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: .INDENT 7.0 .INDENT 3.5 .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 .UNINDENT .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: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq at.atc .ft P .fi .UNINDENT .UNINDENT .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: .INDENT 7.0 .INDENT 3.5 .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 .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.at.atrm(*args) Remove jobs from the queue. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .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 .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.at.jobcheck(**kwargs) Check the job from queue. The kwargs dict include \(aqhour minute day month year tag runas\(aq Other parameters will be ignored. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq at.jobcheck runas=jam day=13 salt \(aq*\(aq at.jobcheck day=13 month=12 year=13 tag=rose .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.augeas_cfg .sp Manages configuration files via augeas .sp This module requires the \fBaugeas\fP Python module. .sp \fBWARNING:\fP .INDENT 0.0 .INDENT 3.5 Minimal installations of Debian and Ubuntu have been seen to have packaging bugs with python\-augeas, causing the augeas module to fail to import. If the minion has the augeas module installed, but the functions in this execution module fail to run due to being unavailable, first restart the salt\-minion service. If the problem persists past that, the following command can be run from the master to determine what is causing the import to fail: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt minion\-id cmd.run \(aqpython \-c "from augeas import Augeas"\(aq .ft P .fi .UNINDENT .UNINDENT .sp For affected Debian/Ubuntu hosts, installing \fBlibpython2.7\fP has been known to resolve the issue. .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: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq augeas.get /files/etc/hosts/1/ ipaddr .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.augeas_cfg.ls(path) List the direct children of a node .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq augeas.ls /files/etc/passwd .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.augeas_cfg.match(path, value=\(aq\(aq) Get matches for path expression .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq augeas.match /files/etc/services/service\-name ssh .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.augeas_cfg.remove(path) Get matches for path expression .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq augeas.remove /files/etc/sysctl.conf/net.ipv4.conf.all.log_martians .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.augeas_cfg.setvalue(*args) Set a value for a specific augeas path .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq augeas.setvalue /files/etc/hosts/1/canonical localhost .ft P .fi .UNINDENT .UNINDENT .sp This will set the first entry in /etc/hosts to localhost .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .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 .UNINDENT .UNINDENT .sp Adds a new host to /etc/hosts the ip address 192.168.1.1 and hostname test .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .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 .UNINDENT .UNINDENT .sp Ensures that the following line is present in /etc/sudoers: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C %wheel ALL = PASSWD : ALL , NOPASSWD : /usr/bin/apt\-get , /usr/bin/aptitude .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.augeas_cfg.tree(path) Returns recursively the complete tree of a node .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq augeas.tree /files/etc/ .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.aws_sqs .sp Support for the Amazon Simple Queue Service. .INDENT 0.0 .TP .B salt.modules.aws_sqs.create_queue(name, region, opts=None, user=None) Creates a queue with the correct name. .INDENT 7.0 .TP .B name Name of the SQS queue to create .TP .B region Region to create the SQS queue in .TP .B opts None Any additional options to add to the command line .TP .B user None Run hg as a user other than what the minion runs as .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.aws_sqs.delete_queue(name, region, opts=None, user=None) Deletes a queue in the region. .INDENT 7.0 .TP .B name Name of the SQS queue to deletes .TP .B region Name of the region to delete the queue from .TP .B opts None Any additional options to add to the command line .TP .B user None Run hg as a user other than what the minion runs as .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.aws_sqs.list_queues(region, opts=None, user=None) List the queues in the selected region. .INDENT 7.0 .TP .B region Region to list SQS queues for .TP .B opts None Any additional options to add to the command line .TP .B user None Run hg as a user other than what the minion runs as .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.aws_sqs.queue_exists(name, region, opts=None, user=None) Returns True or False on whether the queue exists in the region .INDENT 7.0 .TP .B name Name of the SQS queue to search for .TP .B region Name of the region to search for the queue in .TP .B opts None Any additional options to add to the command line .TP .B user None Run hg as a user other than what the minion runs as .UNINDENT .UNINDENT .SS salt.modules.bluez .sp Support for Bluetooth (using BlueZ in Linux). .sp The following packages are required packages for this module: .INDENT 0.0 .INDENT 3.5 bluez >= 5.7 bluez\-libs >= 5.7 bluez\-utils >= 5.7 pybluez >= 0.18 .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.bluez.address_() Get the many addresses of the Bluetooth adapter .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq bluetooth.address .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.bluez.block(bdaddr) Block a specific bluetooth device by BD Address .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq bluetooth.block DE:AD:BE:EF:CA:FE .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.bluez.discoverable(dev) Enable this bluetooth device to be discoverable. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq bluetooth.discoverable hci0 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.bluez.noscan(dev) Turn off scanning modes on this device. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq bluetooth.noscan hci0 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.bluez.pair(address, key) Pair the bluetooth adapter with a device .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq bluetooth.pair DE:AD:BE:EF:CA:FE 1234 .ft P .fi .UNINDENT .UNINDENT .sp Where DE:AD:BE:EF:CA:FE is the address of the device to pair with, and 1234 is the passphrase. .sp TODO: This function is currently broken, as the bluez\-simple\-agent program no longer ships with BlueZ >= 5.0. It needs to be refactored. .UNINDENT .INDENT 0.0 .TP .B salt.modules.bluez.power(dev, mode) Power a bluetooth device on or off .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq bluetooth.power hci0 on salt \(aq*\(aq bluetooth.power hci0 off .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.bluez.scan() Scan for bluetooth devices in the area .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq bluetooth.scan .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.bluez.start() Start the bluetooth service. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq bluetooth.start .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.bluez.stop() Stop the bluetooth service. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq bluetooth.stop .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.bluez.unblock(bdaddr) Unblock a specific bluetooth device by BD Address .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq bluetooth.unblock DE:AD:BE:EF:CA:FE .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.bluez.unpair(address) Unpair the bluetooth adapter from a device .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq bluetooth.unpair DE:AD:BE:EF:CA:FE .ft P .fi .UNINDENT .UNINDENT .sp Where DE:AD:BE:EF:CA:FE is the address of the device to unpair. .sp TODO: This function is currently broken, as the bluez\-simple\-agent program no longer ships with BlueZ >= 5.0. It needs to be refactored. .UNINDENT .INDENT 0.0 .TP .B salt.modules.bluez.version() Return Bluez version from bluetoothd \-v .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq bluetoothd.version .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.brew .sp Homebrew for Mac OS X .INDENT 0.0 .TP .B salt.modules.brew.install(name=None, pkgs=None, taps=None, options=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. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.install .ft P .fi .UNINDENT .UNINDENT .TP .B taps Unofficial Github repos to use when updating and installing formulas. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.install tap=\(aq\(aq salt \(aq*\(aq pkg.install zlib taps=\(aqhomebrew/dupes\(aq salt \(aq*\(aq pkg.install php54 taps=\(aq["josegonzalez/php", "homebrew/dupes"]\(aq .ft P .fi .UNINDENT .UNINDENT .TP .B options Options to pass to brew. Only applies to inital install. Due to how brew works, modifying chosen options requires a full uninstall followed by a fresh install. Note that if "pkgs" is used, all options will be passed to all packages. Unreconized options for a package will be silently ignored by brew. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.install tap=\(aq\(aq salt \(aq*\(aq pkg.install php54 taps=\(aq["josegonzalez/php", "homebrew/dupes"]\(aq options=\(aq["\-\-with\-fpm"]\(aq .ft P .fi .UNINDENT .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. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.install pkgs=\(aq["foo","bar"]\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .sp Returns a dict containing the new package names and versions: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C {\(aq\(aq: {\(aqold\(aq: \(aq\(aq, \(aqnew\(aq: \(aq\(aq}} .ft P .fi .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.install \(aqpackage package package\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.brew.latest_version(*names, **kwargs) 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: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.latest_version salt \(aq*\(aq pkg.latest_version .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.brew.list_pkgs(versions_as_list=False, **kwargs) List the packages currently installed in a dict: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C {\(aq\(aq: \(aq\(aq} .ft P .fi .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.list_pkgs .ft P .fi .UNINDENT .UNINDENT .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: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.list_upgrades .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.brew.refresh_db() Update the homebrew package repository. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.refresh_db .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.brew.remove(name=None, pkgs=None, **kwargs) Removes packages with \fBbrew uninstall\fP\&. .INDENT 7.0 .TP .B name The name of the package to be deleted. .UNINDENT .sp Multiple Package Options: .INDENT 7.0 .TP .B pkgs A list of packages to delete. Must be passed as a python list. The \fBname\fP parameter will be ignored if this option is passed. .UNINDENT .sp New in version 0.16.0. .sp Returns a dict containing the changes. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.remove salt \(aq*\(aq pkg.remove ,, salt \(aq*\(aq pkg.remove pkgs=\(aq["foo", "bar"]\(aq .ft P .fi .UNINDENT .UNINDENT .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: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.upgrade_available .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.brew.version(*names, **kwargs) 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: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.version salt \(aq*\(aq pkg.version .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.bridge .sp Module for gathering and managing bridging information .INDENT 0.0 .TP .B salt.modules.bridge.add(br=None) Creates a bridge .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq bridge.add br0 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.bridge.addif(br=None, iface=None) Adds an interface to a bridge .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq bridge.addif br0 eth0 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.bridge.delete(br=None) Deletes a bridge .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq bridge.delete br0 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.bridge.delif(br=None, iface=None) Removes an interface from a bridge .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq bridge.delif br0 eth0 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.bridge.find_interfaces(*args) Returns the bridge to which the interfaces are bond to .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq bridge.find_interfaces eth0 [eth1...] .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.bridge.interfaces(br=None) Returns interfaces attached to a bridge .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq bridge.interfaces br0 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.bridge.list_() Returns the machine\(aqs bridges list .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq bridge.list .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.bridge.show(br=None) Returns bridges interfaces along with enslaved physical interfaces. If no interface is given, all bridges are shown, else only the specified bridge values are returned. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq bridge.show salt \(aq*\(aq bridge.show br0 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.bridge.stp(br=None, state=\(aqdisable\(aq, iface=None) Sets Spanning Tree Protocol state for a bridge .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq bridge.stp br0 enable salt \(aq*\(aq bridge.stp br0 disable .ft P .fi .UNINDENT .UNINDENT .sp For the NetBSD operating system, it is required to add the interface on which to enable the STP. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq bridge.stp bridge0 enable fxp0 salt \(aq*\(aq bridge.stp bridge0 disable fxp0 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.bsd_shadow .sp Manage the password database on BSD systems .INDENT 0.0 .TP .B salt.modules.bsd_shadow.default_hash() Returns the default hash used for unset passwords .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq shadow.default_hash .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.bsd_shadow.info(name) Return information for the specified user .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq shadow.info someuser .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.bsd_shadow.set_password(name, password) Set the password for a named user. The password must be a properly defined hash. The password hash can be generated with this command: .sp \fBpython \-c "import crypt; print crypt.crypt(\(aqpassword\(aq, ciphersalt)"\fP .sp \fBNOTE:\fP When constructing the \fBciphersalt\fP string, you must escape any dollar signs, to avoid them being interpolated by the shell. .sp \fB\(aqpassword\(aq\fP is, of course, the password for which you want to generate a hash. .sp \fBciphersalt\fP is a combination of a cipher identifier, an optional number of rounds, and the cryptographic salt. The arrangement and format of these fields depends on the cipher and which flavor of BSD you are using. For more information on this, see the manpage for \fBcrpyt(3)\fP\&. On NetBSD, additional information is available in \fBpasswd.conf(5)\fP\&. .sp It is important to make sure that a supported cipher is used. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq shadow.set_password someuser \(aq$1$UYCIxa628.9qXjpQCjM4a..\(aq .ft P .fi .UNINDENT .UNINDENT .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: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C cassandra.nodetool: /usr/local/bin/nodetool cassandra.host: localhost cassandra.thrift_port: 9160 .ft P .fi .UNINDENT .UNINDENT .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: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq cassandra.column_families salt \(aq*\(aq cassandra.column_families .ft P .fi .UNINDENT .UNINDENT .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: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq cassandra.column_family_definition .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.cassandra.compactionstats() Return compactionstats info .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq cassandra.compactionstats .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.cassandra.info() Return cassandra node info .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq cassandra.info .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.cassandra.keyspaces() Return existing keyspaces .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq cassandra.keyspaces .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.cassandra.netstats() Return netstats info .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq cassandra.netstats .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.cassandra.ring() Return cassandra ring info .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq cassandra.ring .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.cassandra.tpstats() Return tpstats info .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq cassandra.tpstats .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.cassandra.version() Return the cassandra version .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq cassandra.version .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.chocolatey .sp A dead simple module wrapping calls to the Chocolatey package manager (\fI\%http://chocolatey.org\fP) .sp New in version 2014.1.0: (Hydrogen) .INDENT 0.0 .TP .B salt.modules.chocolatey.bootstrap(force=False) Download and install the latest version of the Chocolatey package manager via the official bootstrap. .sp Chocolatey requires Windows PowerShell and the .NET v4.0 runtime. Depending on the host\(aqs version of Windows, chocolatey.bootstrap will attempt to ensure these prerequisites are met by downloading and executing the appropriate installers from Microsoft. .sp Note that if PowerShell is installed, you may have to restart the host machine for Chocolatey to work. .INDENT 7.0 .TP .B force Run the bootstrap process even if Chocolatey is found in the path. .UNINDENT .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq chocolatey.bootstrap salt \(aq*\(aq chocolatey.bootstrap force=True .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.chocolatey.install(name, version=None, source=None, force=False) Instructs Chocolatey to install a package. .INDENT 7.0 .TP .B name The name of the package to be installed. Only accepts a single argument. .TP .B version Install a specific version of the package. Defaults to latest version. .TP .B source Chocolatey repository (directory, share or remote URL feed) the package comes from. Defaults to the official Chocolatey feed. .TP .B force Reinstall the current version of an existing package. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq chocolatey.install salt \(aq*\(aq chocolatey.install version= .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.chocolatey.install_cygwin(name) Instructs Chocolatey to install a package via Cygwin. .INDENT 7.0 .TP .B name The name of the package to be installed. Only accepts a single argument. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq chocolatey.install_cygwin .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.chocolatey.install_gem(name, version=None) Instructs Chocolatey to install a package via Ruby\(aqs Gems. .INDENT 7.0 .TP .B name The name of the package to be installed. Only accepts a single argument. .TP .B version Install a specific version of the package. Defaults to latest version available. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq chocolatey.install_gem salt \(aq*\(aq chocolatey.install_gem version= .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.chocolatey.install_missing(name, version=None, source=None) Instructs Chocolatey to install a package if it doesn\(aqt already exist. .INDENT 7.0 .TP .B name The name of the package to be installed. Only accepts a single argument. .TP .B version Install a specific version of the package. Defaults to latest version available. .TP .B source Chocolatey repository (directory, share or remote URL feed) the package comes from. Defaults to the official Chocolatey feed. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq chocolatey.install_missing salt \(aq*\(aq chocolatey.install_missing version= .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.chocolatey.install_python(name, version=None) Instructs Chocolatey to install a package via Python\(aqs easy_install. .INDENT 7.0 .TP .B name The name of the package to be installed. Only accepts a single argument. .TP .B version Install a specific version of the package. Defaults to latest version available. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq chocolatey.install_python salt \(aq*\(aq chocolatey.install_python version= .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.chocolatey.install_webpi(name) Instructs Chocolatey to install a package via the Microsoft Web PI service. .INDENT 7.0 .TP .B name The name of the package to be installed. Only accepts a single argument. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq chocolatey.install_webpi .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.chocolatey.install_windowsfeatures(name) Instructs Chocolatey to install a Windows Feature via the Deployment Image Servicing and Management tool. .INDENT 7.0 .TP .B name The name of the feature to be installed. Only accepts a single argument. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq chocolatey.install_windowsfeatures .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.chocolatey.list_(filter, all_versions=False, pre_versions=False, source=None) Instructs Chocolatey to pull a vague package list from the repository. .INDENT 7.0 .TP .B filter Term used to filter down results. Searches against name/description/tag. .TP .B all_versions Display all available package versions in results. Defaults to False. .TP .B pre_versions Display pre\-release packages in results. Defaults to False. .TP .B source Chocolatey repository (directory, share or remote URL feed) the package comes from. Defaults to the official Chocolatey feed. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq chocolatey.list salt \(aq*\(aq chocolatey.list all_versions=True .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.chocolatey.list_webpi() Instructs Chocolatey to pull a full package list from the Microsoft Web PI repository. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq chocolatey.list_webpi .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.chocolatey.list_windowsfeatures() Instructs Chocolatey to pull a full package list from the Windows Features list, via the Deployment Image Servicing and Management tool. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq chocolatey.list_windowsfeatures .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.chocolatey.uninstall(name, version=None) Instructs Chocolatey to uninstall a package. .INDENT 7.0 .TP .B name The name of the package to be uninstalled. Only accepts a single argument. .TP .B version Uninstalls a specific version of the package. Defaults to latest version installed. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq chocolatey.uninstall salt \(aq*\(aq chocolatey.uninstall version= .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.chocolatey.update(name, source=None, pre_versions=False) Instructs Chocolatey to update packages on the system. .INDENT 7.0 .TP .B name The name of the package to update, or "all" to update everything installed on the system. .TP .B source Chocolatey repository (directory, share or remote URL feed) the package comes from. Defaults to the official Chocolatey feed. .TP .B pre_versions Include pre\-release packages in comparison. Defaults to False. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt "*" chocolatey.update all salt "*" chocolatey.update pre_versions=True .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.chocolatey.version(name, check_remote=False, source=None, pre_versions=False) Instructs Chocolatey to check an installed package version, and optionally compare it to one available from a remote feed. .INDENT 7.0 .TP .B name The name of the package to check. .TP .B check_remote Get the version number of the latest package from the remote feed. Defaults to False. .TP .B source Chocolatey repository (directory, share or remote URL feed) the package comes from. Defaults to the official Chocolatey feed. .TP .B pre_versions Include pre\-release packages in comparison. Defaults to False. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt "*" chocolatey.version salt "*" chocolatey.version check_remote=True .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.cloud .sp Salt\-specific interface for calling Salt Cloud directly .INDENT 0.0 .TP .B salt.modules.cloud.action(fun=None, cloudmap=None, names=None, provider=None, instance=None, **kwargs) Execute a single action on the given provider/instance .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq cloud.action start instance=myinstance salt \(aq*\(aq cloud.action stop instance=myinstance salt \(aq*\(aq cloud.action show_image provider=my\-ec2\-config image=ami\-1624987f .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.cloud.create(provider, names, **kwargs) Create an instance using Salt Cloud .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt minionname cloud.create my\-ec2\-config myinstance image=ami\-1624987f size=\(aqMicro Instance\(aq ssh_username=ec2\-user securitygroup=default delvol_on_destroy=True .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.cloud.destroy(names) Destroy the named VM(s) .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq cloud.destroy myinstance .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.cloud.full_query(query_type=\(aqlist_nodes_full\(aq) List all available cloud provider data .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq cloud.full_query .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.cloud.list_images(provider=\(aqall\(aq) List cloud provider images for the given providers .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq cloud.list_images my\-gce\-config .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.cloud.list_locations(provider=\(aqall\(aq) List cloud provider locations for the given providers .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq cloud.list_locations my\-gce\-config .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.cloud.list_sizes(provider=\(aqall\(aq) List cloud provider sizes for the given providers .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq cloud.list_sizes my\-gce\-config .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.cloud.profile_(profile, names, **kwargs) Spin up an instance using Salt Cloud .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq cloud.profile my\-gce\-config myinstance .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.cloud.query(query_type=\(aqlist_nodes\(aq) List cloud provider data for all providers .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq cloud.query salt \(aq*\(aq cloud.query list_nodes_full salt \(aq*\(aq cloud.query list_nodes_select .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.cloud.select_query(query_type=\(aqlist_nodes_select\(aq) List selected nodes .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq cloud.select_query .ft P .fi .UNINDENT .UNINDENT .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: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq cmd.exec_code ruby \(aqputs "cheese"\(aq .ft P .fi .UNINDENT .UNINDENT .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: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq cmd.has_exec cat .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.cmdmod.retcode(cmd, cwd=None, stdin=None, runas=None, shell=\(aq/bin/sh\(aq, python_shell=True, env=None, clean_env=False, template=None, umask=None, output_loglevel=\(aqinfo\(aq, quiet=False, timeout=None, reset_system_locale=True, ignore_retcode=False, saltenv=\(aqbase\(aq, **kwargs) Execute a shell command and return the command\(aqs return code. .sp Note that \fBenv\fP represents the environment variables for the command, and should be formatted as a dict, or a YAML string which resolves to a dict. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq cmd.retcode "file /bin/bash" .ft P .fi .UNINDENT .UNINDENT .sp The template arg can be set to \(aqjinja\(aq or another supported template engine to render the command arguments before execution. For example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq cmd.retcode template=jinja "file {{grains.pythonpath[0]}}/python" .ft P .fi .UNINDENT .UNINDENT .sp A string of standard input can be specified for the command to be run using the \fBstdin\fP parameter. This can be useful in cases where sensitive information must be read from standard input.: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq cmd.retcode "grep f" stdin=\(aqone\entwo\enthree\enfour\enfive\en\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.cmdmod.run(cmd, cwd=None, stdin=None, runas=None, shell=\(aq/bin/sh\(aq, python_shell=True, env=None, clean_env=False, template=None, rstrip=True, umask=None, output_loglevel=\(aqinfo\(aq, quiet=False, timeout=None, reset_system_locale=True, ignore_retcode=False, saltenv=\(aqbase\(aq, **kwargs) Execute the passed command and return the output as a string .sp Note that \fBenv\fP represents the environment variables for the command, and should be formatted as a dict, or a YAML string which resolves to a dict. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq cmd.run "ls \-l | awk \(aq/foo/{print \e$2}\(aq" .ft P .fi .UNINDENT .UNINDENT .sp The template arg can be set to \(aqjinja\(aq or another supported template engine to render the command arguments before execution. For example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq cmd.run template=jinja "ls \-l /tmp/{{grains.id}} | awk \(aq/foo/{print \e$2}\(aq" .ft P .fi .UNINDENT .UNINDENT .sp Specify an alternate shell with the shell parameter: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq cmd.run "Get\-ChildItem C:\e " shell=\(aqpowershell\(aq .ft P .fi .UNINDENT .UNINDENT .sp A string of standard input can be specified for the command to be run using the \fBstdin\fP parameter. This can be useful in cases where sensitive information must be read from standard input.: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq cmd.run "grep f" stdin=\(aqone\entwo\enthree\enfour\enfive\en\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.cmdmod.run_all(cmd, cwd=None, stdin=None, runas=None, shell=\(aq/bin/sh\(aq, python_shell=True, env=None, clean_env=False, template=None, rstrip=True, umask=None, output_loglevel=\(aqinfo\(aq, quiet=False, timeout=None, reset_system_locale=True, ignore_retcode=False, saltenv=\(aqbase\(aq, **kwargs) Execute the passed command and return a dict of return data .sp Note that \fBenv\fP represents the environment variables for the command, and should be formatted as a dict, or a YAML string which resolves to a dict. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq cmd.run_all "ls \-l | awk \(aq/foo/{print \e$2}\(aq" .ft P .fi .UNINDENT .UNINDENT .sp The template arg can be set to \(aqjinja\(aq or another supported template engine to render the command arguments before execution. For example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq cmd.run_all template=jinja "ls \-l /tmp/{{grains.id}} | awk \(aq/foo/{print \e$2}\(aq" .ft P .fi .UNINDENT .UNINDENT .sp A string of standard input can be specified for the command to be run using the \fBstdin\fP parameter. This can be useful in cases where sensitive information must be read from standard input.: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq cmd.run_all "grep f" stdin=\(aqone\entwo\enthree\enfour\enfive\en\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.cmdmod.run_stderr(cmd, cwd=None, stdin=None, runas=None, shell=\(aq/bin/sh\(aq, python_shell=True, env=None, clean_env=False, template=None, rstrip=True, umask=None, output_loglevel=\(aqinfo\(aq, quiet=False, timeout=None, reset_system_locale=True, ignore_retcode=False, saltenv=\(aqbase\(aq, **kwargs) Execute a command and only return the standard error .sp Note that \fBenv\fP represents the environment variables for the command, and should be formatted as a dict, or a YAML string which resolves to a dict. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq cmd.run_stderr "ls \-l | awk \(aq/foo/{print \e$2}\(aq" .ft P .fi .UNINDENT .UNINDENT .sp The template arg can be set to \(aqjinja\(aq or another supported template engine to render the command arguments before execution. For example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq cmd.run_stderr template=jinja "ls \-l /tmp/{{grains.id}} | awk \(aq/foo/{print \e$2}\(aq" .ft P .fi .UNINDENT .UNINDENT .sp A string of standard input can be specified for the command to be run using the \fBstdin\fP parameter. This can be useful in cases where sensitive information must be read from standard input.: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq cmd.run_stderr "grep f" stdin=\(aqone\entwo\enthree\enfour\enfive\en\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.cmdmod.run_stdout(cmd, cwd=None, stdin=None, runas=None, shell=\(aq/bin/sh\(aq, python_shell=True, env=None, clean_env=False, template=None, rstrip=True, umask=None, output_loglevel=\(aqinfo\(aq, quiet=False, timeout=None, reset_system_locale=True, ignore_retcode=False, saltenv=\(aqbase\(aq, **kwargs) Execute a command, and only return the standard out .sp Note that \fBenv\fP represents the environment variables for the command, and should be formatted as a dict, or a YAML string which resolves to a dict. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq cmd.run_stdout "ls \-l | awk \(aq/foo/{print \e$2}\(aq" .ft P .fi .UNINDENT .UNINDENT .sp The template arg can be set to \(aqjinja\(aq or another supported template engine to render the command arguments before execution. For example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq cmd.run_stdout template=jinja "ls \-l /tmp/{{grains.id}} | awk \(aq/foo/{print \e$2}\(aq" .ft P .fi .UNINDENT .UNINDENT .sp A string of standard input can be specified for the command to be run using the \fBstdin\fP parameter. This can be useful in cases where sensitive information must be read from standard input.: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq cmd.run_stdout "grep f" stdin=\(aqone\entwo\enthree\enfour\enfive\en\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.cmdmod.script(source, args=None, cwd=None, stdin=None, runas=None, shell=\(aq/bin/sh\(aq, python_shell=True, env=None, template=\(aqjinja\(aq, umask=None, output_loglevel=\(aqinfo\(aq, quiet=False, timeout=None, reset_system_locale=True, __env__=None, saltenv=\(aqbase\(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: .INDENT 7.0 .INDENT 3.5 .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 salt \(aq*\(aq cmd.script salt://scripts/windows_task.ps1 args=\(aq \-Input c:\etmp\einfile.txt\(aq shell=\(aqpowershell\(aq .ft P .fi .UNINDENT .UNINDENT .sp A string of standard input can be specified for the command to be run using the \fBstdin\fP parameter. This can be useful in cases where sensitive information must be read from standard input.: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq cmd.script salt://scripts/runme.sh stdin=\(aqone\entwo\enthree\enfour\enfive\en\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.cmdmod.script_retcode(source, cwd=None, stdin=None, runas=None, shell=\(aq/bin/sh\(aq, python_shell=True, env=None, template=\(aqjinja\(aq, umask=None, timeout=None, reset_system_locale=True, __env__=None, saltenv=\(aqbase\(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: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq cmd.script_retcode salt://scripts/runme.sh .ft P .fi .UNINDENT .UNINDENT .sp A string of standard input can be specified for the command to be run using the \fBstdin\fP parameter. This can be useful in cases where sensitive information must be read from standard input.: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq cmd.script_retcode salt://scripts/runme.sh stdin=\(aqone\entwo\enthree\enfour\enfive\en\(aq .ft P .fi .UNINDENT .UNINDENT .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: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq cmd.which cat .ft P .fi .UNINDENT .UNINDENT .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: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq cmd.which_bin \(aq[pip2, pip, pip\-python]\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.composer .sp Use composer to install PHP dependencies for a directory .INDENT 0.0 .TP .B salt.modules.composer.install(dir, composer=None, php=None, runas=None, prefer_source=None, prefer_dist=None, no_scripts=None, no_plugins=None, optimize=None, no_dev=None, quiet=False, composer_home=\(aq/root\(aq) Install composer dependencies for a directory. .sp If composer has not been installed globally making it avaliable in the system PATH & making it executible, the \fBcomposer\fP and \fBphp\fP parameters will need to be set to the location of the executables. .INDENT 7.0 .TP .B dir Directory location of the composer.json file. .TP .B composer Location of the composer.phar file. If not set composer will just execute "composer" as if it is installed globally. (i.e. /path/to/composer.phar) .TP .B php Location of the php executible to use with composer. (i.e. /usr/bin/php) .TP .B runas Which system user to run composer as. .TP .B prefer_source \-\-prefer\-source option of composer. .TP .B prefer_dist \-\-prefer\-dist option of composer. .TP .B no_scripts \-\-no\-scripts option of composer. .TP .B no_plugins \-\-no\-plugins option of composer. .TP .B optimize \-\-optimize\-autoloader option of composer. Recommended for production. .TP .B no_dev \-\-no\-dev option for composer. Recommended for production. .TP .B quiet \-\-quiet option for composer. Whether or not to return output from composer. .TP .B composer_home $COMPOSER_HOME environment variable .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq composer.install /var/www/application salt \(aq*\(aq composer.install /var/www/application no_dev=True optimize=True .ft P .fi .UNINDENT .UNINDENT .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: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq config.backup_mode .ft P .fi .UNINDENT .UNINDENT .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: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq config.dot_vals host .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.config.get(key, default=\(aq\(aq) Attempt to retrieve the named value from opts, pillar, grains of the master config, if the named value is not available return the passed default. The default return is an empty string. .sp The value can also represent a value in a nested dict using a ":" delimiter for the dict. This means that if a dict looks like this: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C {\(aqpkg\(aq: {\(aqapache\(aq: \(aqhttpd\(aq}} .ft P .fi .UNINDENT .UNINDENT .sp To retrieve the value associated with the apache key in the pkg dict this key can be passed: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C pkg:apache .ft P .fi .UNINDENT .UNINDENT .sp This routine traverses these data stores in this order: .INDENT 7.0 .IP \(bu 2 Local minion config (opts) .IP \(bu 2 Minion\(aqs grains .IP \(bu 2 Minion\(aqs pillar .IP \(bu 2 Master config .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq config.get pkg:apache .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.config.manage_mode(mode) Return a mode value, normalized to a string .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq config.manage_mode .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.config.merge(value, default=\(aq\(aq, omit_opts=False, omit_master=False, omit_pillar=False) Retrieves an option based on key, merging all matches. .sp Same as \fBoption()\fP except that it merges all matches, rather than taking the first match. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq config.merge schedule .ft P .fi .UNINDENT .UNINDENT .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: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq config.option redis.host .ft P .fi .UNINDENT .UNINDENT .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: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq config.valid_fileproto salt://path/to/file .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.cp .sp Minion side functions for salt\-cp .INDENT 0.0 .TP .B salt.modules.cp.cache_dir(path, saltenv=\(aqbase\(aq, include_empty=False, env=None) Download and cache everything under a directory from the master .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq cp.cache_dir salt://path/to/dir .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.cp.cache_file(path, saltenv=\(aqbase\(aq, env=None) Used to cache a single file in the local salt\-master file cache. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq cp.cache_file salt://path/to/file .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.cp.cache_files(paths, saltenv=\(aqbase\(aq, env=None) 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: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq cp.cache_files salt://pathto/file1,salt://pathto/file1 .ft P .fi .UNINDENT .UNINDENT .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: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq cp.cache_local_file /etc/hosts .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.cp.cache_master(saltenv=\(aqbase\(aq, env=None) Retrieve all of the files on the master and cache them locally .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq cp.cache_master .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.cp.get_dir(path, dest, saltenv=\(aqbase\(aq, template=None, gzip=None, env=None) Used to recursively copy a directory from the salt master .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq cp.get_dir salt://path/to/dir/ /minion/dest .ft P .fi .UNINDENT .UNINDENT .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, saltenv=\(aqbase\(aq, makedirs=False, template=None, gzip=None, env=None) Used to get a single file from the salt master .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq cp.get_file salt://path/to/file /minion/dest .ft P .fi .UNINDENT .UNINDENT .sp Template rendering can be enabled on both the source and destination file names like so: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq cp.get_file "salt://{{grains.os}}/vimrc" /etc/vimrc template=jinja .ft P .fi .UNINDENT .UNINDENT .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, saltenv=\(aqbase\(aq, env=None) Return the contents of a file from a URL .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq cp.get_file_str salt://my/file .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.cp.get_template(path, dest, template=\(aqjinja\(aq, saltenv=\(aqbase\(aq, env=None, **kwargs) Render a file as a template before setting it down .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq cp.get_template salt://path/to/template /minion/dest .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.cp.get_url(path, dest, saltenv=\(aqbase\(aq, env=None) Used to get a single file from a URL. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .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 .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.cp.hash_file(path, saltenv=\(aqbase\(aq, env=None) 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: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq cp.hash_file salt://path/to/file .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.cp.is_cached(path, saltenv=\(aqbase\(aq, env=None) Return a boolean if the given path on the master has been cached on the minion .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq cp.is_cached salt://path/to/file .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.cp.list_master(saltenv=\(aqbase\(aq, prefix=\(aq\(aq, env=None) List all of the files stored on the master .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq cp.list_master .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.cp.list_master_dirs(saltenv=\(aqbase\(aq, prefix=\(aq\(aq, env=None) List all of the directories stored on the master .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq cp.list_master_dirs .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.cp.list_master_symlinks(saltenv=\(aqbase\(aq, prefix=\(aq\(aq, env=None) List all of the symlinks stored on the master .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq cp.list_master_symlinks .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.cp.list_minion(saltenv=\(aqbase\(aq, env=None) List all of the files cached on the minion .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq cp.list_minion .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.cp.list_states(saltenv=\(aqbase\(aq, env=None) List all of the available state modules in an environment .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq cp.list_states .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.cp.push(path) Push a file from the minion up to the master, the file will be saved to the salt master in the master\(aqs minion files cachedir (defaults to \fB/var/cache/salt/master/minions/minion\-id/files\fP) .sp Since this feature allows a minion to push a file up to the master server it is disabled by default for security purposes. To enable, set \fBfile_recv\fP to \fBTrue\fP in the master configuration file, and restart the master. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq cp.push /etc/fstab .ft P .fi .UNINDENT .UNINDENT .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. It does not work via the CLI. .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: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq cron.list_tab root .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.cron.ls(user) Return the contents of the specified user\(aqs crontab .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq cron.list_tab root .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.cron.raw_cron(user) Return the contents of the user\(aqs crontab .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq cron.raw_cron root .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.cron.rm(user, cmd, minute=None, hour=None, daymonth=None, month=None, dayweek=None, identifier=None) Remove a cron job for a specified user. If any of the day/time params are specified, the job will only be removed if the specified params match. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq cron.rm_job root /usr/local/weekly salt \(aq*\(aq cron.rm_job root /usr/bin/foo dayweek=1 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.cron.rm_env(user, name) Remove cron environment variable for a specified user. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq cron.rm_env root MAILTO .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.cron.rm_job(user, cmd, minute=None, hour=None, daymonth=None, month=None, dayweek=None, identifier=None) Remove a cron job for a specified user. If any of the day/time params are specified, the job will only be removed if the specified params match. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq cron.rm_job root /usr/local/weekly salt \(aq*\(aq cron.rm_job root /usr/bin/foo dayweek=1 .ft P .fi .UNINDENT .UNINDENT .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: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq cron.set_env root MAILTO user@example.com .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.cron.set_job(user, minute, hour, daymonth, month, dayweek, cmd, comment, identifier=None) Sets a cron job up for a specified user. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq cron.set_job root \(aq*\(aq \(aq*\(aq \(aq*\(aq \(aq*\(aq 1 /usr/local/weekly .ft P .fi .UNINDENT .UNINDENT .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: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq cron.set_special root @hourly \(aqecho foobar\(aq .ft P .fi .UNINDENT .UNINDENT .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: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq cron.write_cron_file root /tmp/new_cron .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.cron.write_cron_file_verbose(user, path) Writes the contents of a file to a user\(aqs crontab and return error message on error .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq cron.write_cron_file_verbose root /tmp/new_cron .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.daemontools .sp daemontools service module. This module will create daemontools type service watcher. .sp This module is compatible with the \fBservice\fP states, so it can be used to maintain services using the \fBprovider\fP argument: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C myservice: service: \- running \- provider: daemontools .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.daemontools.available(name) Returns \fBTrue\fP if the specified service is available, otherwise returns \fBFalse\fP\&. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq daemontools.available foo .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.daemontools.full_restart(name) Calls daemontools.restart() function .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq daemontools.full_restart .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.daemontools.get_all() Return a list of all available services .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq daemontools.get_all .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.daemontools.missing(name) The inverse of daemontools.available. Returns \fBTrue\fP if the specified service is not available, otherwise returns \fBFalse\fP\&. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq daemontools.missing foo .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.daemontools.reload_(name) Wrapper for term() .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq daemontools.reload .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.daemontools.restart(name) Restart service via daemontools. This will stop/start service .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq daemontools.restart .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.daemontools.start(name) Starts service via daemontools .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq daemontools.start .ft P .fi .UNINDENT .UNINDENT .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: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq daemontools.status .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.daemontools.stop(name) Stops service via daemontools .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq daemontools.stop .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.daemontools.term(name) Send a TERM to service via daemontools .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq daemontools.term .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.darwin_sysctl .sp Module for viewing and modifying sysctl parameters .INDENT 0.0 .TP .B salt.modules.darwin_sysctl.assign(name, value) Assign a single sysctl parameter for this minion .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq sysctl.assign net.inet.icmp.icmplim 50 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.darwin_sysctl.get(name) Return a single sysctl parameter for this minion .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq sysctl.get hw.physmem .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.darwin_sysctl.persist(name, value, config=\(aq/etc/sysctl.conf\(aq) Assign and persist a simple sysctl parameter for this minion .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq sysctl.persist net.inet.icmp.icmplim 50 salt \(aq*\(aq sysctl.persist coretemp_load NO config=/etc/sysctl.conf .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.darwin_sysctl.show() Return a list of sysctl parameters for this minion .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq sysctl.show .ft P .fi .UNINDENT .UNINDENT .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.cas(key, value, old_value) Check and set a value in the minion datastore .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq data.cas .ft P .fi .UNINDENT .UNINDENT .UNINDENT .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: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq data.clear .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.data.dump(new_data) Replace the entire datastore with a passed data structure .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq data.dump \(aq{\(aqeggs\(aq: \(aqspam\(aq}\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.data.getval(key) Get a value from the minion datastore .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq data.getval .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.data.getvals(*keys) Get values from the minion datastore .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq data.getvals [ ...] .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.data.load() Return all of the data in the minion datastore .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq data.load .ft P .fi .UNINDENT .UNINDENT .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: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq data.update .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.ddns .sp Support for RFC 2136 dynamic DNS updates. .INDENT 0.0 .TP .B depends .INDENT 7.0 .IP \(bu 2 dnspython Python module .UNINDENT .TP .B configuration If you want to use TSIG authentication for the server, there are a couple of optional configuration parameters made available to support this (the keyname is only needed if the keyring contains more than one key): .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C ddns.keyring: keyring file (default=None) ddns.keyname: key name in file (default=None) .ft P .fi .UNINDENT .UNINDENT .sp The keyring file needs to be in json format and the key name needs to end with an extra period in the file, similar to this: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C {\(aqkeyname.\(aq: \(aqkeycontent\(aq} .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.ddns.add_host(zone, name, ttl, ip, nameserver=\(aq127.0.0.1\(aq, replace=True, **kwargs) Add, replace, or update the A and PTR (reverse) records for a host. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt ns1 ddns.add_host example.com host1 60 10.1.1.1 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.ddns.delete(zone, name, rdtype=None, data=None, nameserver=\(aq127.0.0.1\(aq, **kwargs) Delete a DNS record. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt ns1 ddns.delete example.com host1 A .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.ddns.delete_host(zone, name, nameserver=\(aq127.0.0.1\(aq, **kwargs) Delete the forward and reverse records for a host. .sp Returns true if any records are deleted. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt ns1 ddns.delete_host example.com host1 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.ddns.update(zone, name, ttl, rdtype, data, nameserver=\(aq127.0.0.1\(aq, replace=False, **kwargs) Add, replace, or update a DNS record. nameserver must be an IP address and the minion running this module must have update privileges on that server. If replace is true, first deletes all records for this name and type. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt ns1 ddns.update example.com host1 60 A 10.0.0.1 .ft P .fi .UNINDENT .UNINDENT .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: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C {\(aqpackage\(aq: [[\(aqquestion\(aq, \(aqtype\(aq, \(aqvalue\(aq], ...]} .ft P .fi .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq debconf.get_selections .ft P .fi .UNINDENT .UNINDENT .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: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq debconf.set [ ...] .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.debconfmod.set_file(path, saltenv=\(aqbase\(aq, **kwargs) Set answers to debconf questions from a file. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq debconf.set_file salt://pathto/pkg.selections .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.debconfmod.show(name) Answers to debconf questions for a package in the following format: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C [[\(aqquestion\(aq, \(aqtype\(aq, \(aqvalue\(aq], ...] .ft P .fi .UNINDENT .UNINDENT .sp If debconf doesn\(aqt know about a package, we return None. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq debconf.show .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.debian_ip .sp The networking module for Debian based distros .INDENT 0.0 .TP .B salt.modules.debian_ip.apply_network_settings(**settings) Apply global network configuration. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq ip.apply_network_settings .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.debian_ip.build_bond(iface, **settings) Create a bond script in /etc/modprobe.d with the passed settings and load the bonding kernel module. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq ip.build_bond bond0 mode=balance\-alb .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.debian_ip.build_interface(iface, iface_type, enabled, **settings) Build an interface script for a network interface. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq ip.build_interface eth0 eth .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.debian_ip.build_network_settings(**settings) Build the global network script. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq ip.build_network_settings .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.debian_ip.build_routes(iface, **settings) Add route scripts for a network interface using up commands. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq ip.build_routes eth0 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.debian_ip.down(iface, iface_type) Shutdown a network interface .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq ip.down eth0 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.debian_ip.get_bond(iface) Return the content of a bond script .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq ip.get_bond bond0 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.debian_ip.get_interface(iface) Return the contents of an interface script .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq ip.get_interface eth0 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.debian_ip.get_network_settings() Return the contents of the global network script. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq ip.get_network_settings .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.debian_ip.get_routes(iface) Return the routes for the interface .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq ip.get_interface eth0 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.debian_ip.up(iface, iface_type) Start up a network interface .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq ip.up eth0 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.debian_service .sp Service support for Debian systems (uses update\-rc.d and /sbin/service) .INDENT 0.0 .TP .B salt.modules.debian_service.available(name) Returns \fBTrue\fP if the specified service is available, otherwise returns \fBFalse\fP\&. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq service.available sshd .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.debian_service.disable(name, **kwargs) Disable the named service to start at boot .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq service.disable .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.debian_service.disabled(name) Return True if the named service is enabled, false otherwise .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq service.disabled .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.debian_service.enable(name, **kwargs) Enable the named service to start at boot .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq service.enable .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.debian_service.enabled(name) Return True if the named service is enabled, false otherwise .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq service.enabled .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.debian_service.force_reload(name) Force\-reload the named service .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq service.force_reload .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.debian_service.get_all() Return all available boot services .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq service.get_all .ft P .fi .UNINDENT .UNINDENT .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: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq service.get_disabled .ft P .fi .UNINDENT .UNINDENT .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: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq service.get_enabled .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.debian_service.missing(name) The inverse of service.available. Returns \fBTrue\fP if the specified service is not available, otherwise returns \fBFalse\fP\&. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq service.missing sshd .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.debian_service.reload_(name) Reload the named service .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq service.reload .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.debian_service.restart(name) Restart the named service .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq service.restart .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.debian_service.start(name) Start the specified service .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq service.start .ft P .fi .UNINDENT .UNINDENT .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: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq service.status .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.debian_service.stop(name) Stop the specified service .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq service.stop .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.dig .sp Compendium of generic DNS utilities .INDENT 0.0 .TP .B salt.modules.dig.A(host, nameserver=None) Return the A record for \fBhost\fP\&. .sp Always returns a list. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt ns1 dig.A www.google.com .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.dig.AAAA(host, nameserver=None) Return the AAAA record for \fBhost\fP\&. .sp Always returns a list. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt ns1 dig.AAAA www.google.com .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.dig.MX(domain, resolve=False, nameserver=None) Return a list of lists for the MX of \fBdomain\fP\&. .sp If the \fBresolve\fP argument is True, resolve IPs for the servers. .sp It\(aqs limited to one IP, because although in practice it\(aqs very rarely a round robin, it is an acceptable configuration and pulling just one IP lets the data be similar to the non\-resolved version. If you think an MX has multiple IPs, don\(aqt use the resolver here, resolve them in a separate step. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt ns1 dig.MX google.com .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.dig.NS(domain, resolve=True, nameserver=None) Return a list of IPs of the nameservers for \fBdomain\fP .sp If \fBresolve\fP is False, don\(aqt resolve names. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt ns1 dig.NS google.com .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.dig.SPF(domain, record=\(aqSPF\(aq, nameserver=None) Return the allowed IPv4 ranges in the SPF record for \fBdomain\fP\&. .sp If record is \fBSPF\fP and the SPF record is empty, the TXT record will be searched automatically. If you know the domain uses TXT and not SPF, specifying that will save a lookup. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt ns1 dig.SPF google.com .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.dig.check_ip(addr) Check if address is a valid IP. returns True if valid, otherwise False. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt ns1 dig.check_ip 127.0.0.1 salt ns1 dig.check_ip 1111:2222:3333:4444:5555:6666:7777:8888 .ft P .fi .UNINDENT .UNINDENT .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: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq disk.inodeusage .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.disk.percent(args=None) Return partion information for volumes mounted on this minion .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq disk.percent /var .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.disk.usage(args=None) Return usage information for volumes mounted on this minion .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq disk.usage .ft P .fi .UNINDENT .UNINDENT .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, env=None) Collect static files from each of your applications into a single location that can easily be served in production. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq django.collectstatic .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.djangomod.command(settings_module, command, bin_env=None, pythonpath=None, env=None, *args, **kwargs) Run arbitrary django management command .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq django.command .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.djangomod.createsuperuser(settings_module, username, email, bin_env=None, database=None, pythonpath=None, env=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: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq django.createsuperuser user user@example.com .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.djangomod.loaddata(settings_module, fixtures, bin_env=None, database=None, pythonpath=None, env=None) Load fixture data .INDENT 7.0 .TP .B Fixtures: comma separated list of fixtures to load .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq django.loaddata .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.djangomod.syncdb(settings_module, bin_env=None, migrate=False, database=None, pythonpath=None, env=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: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq django.syncdb .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.dnsmasq .sp Module for managing dnqmasq .INDENT 0.0 .TP .B salt.modules.dnsmasq.fullversion() Shows installed version of dnsmasq, and compile options .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq dnsmasq.version .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.dnsmasq.get_config(config_file=\(aq/etc/dnsmasq.conf\(aq) Dumps all options from the config file .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq dnsmasq.get_config salt \(aq*\(aq dnsmasq.get_config file=/etc/dnsmasq.conf .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.dnsmasq.set_config(config_file=\(aq/etc/dnsmasq.conf\(aq, follow=True, **kwargs) Sets a value or a set of values in the specified file. By default, if conf\-dir is configured in this file, salt will attempt to set the option in any file inside the conf\-dir where it has already been enabled. If it does not find it inside any files, it will append it to the main config file. Setting follow to False will turn off this behavior. .sp If a config option currently appears multiple times (such as dhcp\-host, which is specified at least once per host), the new option will be added to the end of the main config file (and not to any includes). If you need an option added to a specific include file, specify it as the config_file. .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq dnsmasq.set_config domain=mydomain.com salt \(aq*\(aq dnsmasq.set_config follow=False domain=mydomain.com salt \(aq*\(aq dnsmasq.set_config file=/etc/dnsmasq.conf domain=mydomain.com .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.dnsmasq.version() Shows installed version of dnsmasq .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq dnsmasq.version .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.dnsutil .sp Compendium of generic DNS utilities .INDENT 0.0 .TP .B salt.modules.dnsutil.A(host, nameserver=None) Return the A record for \(aqhost\(aq. .sp Always returns a list. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt ns1 dig.A www.google.com .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.dnsutil.MX(domain, resolve=False, nameserver=None) Return a list of lists for the MX of \fBdomain\fP\&. .sp If the \(aqresolve\(aq argument is True, resolve IPs for the servers. .sp It\(aqs limited to one IP, because although in practice it\(aqs very rarely a round robin, it is an acceptable configuration and pulling just one IP lets the data be similar to the non\-resolved version. If you think an MX has multiple IPs, don\(aqt use the resolver here, resolve them in a separate step. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt ns1 dig.MX google.com .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.dnsutil.NS(domain, resolve=True, nameserver=None) Return a list of IPs of the nameservers for \fBdomain\fP .sp If \(aqresolve\(aq is False, don\(aqt resolve names. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt ns1 dig.NS google.com .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.dnsutil.SPF(domain, record=\(aqSPF\(aq, nameserver=None) Return the allowed IPv4 ranges in the SPF record for \fBdomain\fP\&. .sp If record is \fBSPF\fP and the SPF record is empty, the TXT record will be searched automatically. If you know the domain uses TXT and not SPF, specifying that will save a lookup. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt ns1 dig.SPF google.com .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.dnsutil.check_ip(ip_addr) Check that string ip_addr is a valid IP .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt ns1 dig.check_ip 127.0.0.1 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.dnsutil.hosts_append(hostsfile=\(aq/etc/hosts\(aq, ip_addr=None, entries=None) Append a single line to the /etc/hosts file. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq dnsutil.hosts_append /etc/hosts 127.0.0.1 ad1.yuk.co,ad2.yuk.co .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.dnsutil.hosts_remove(hostsfile=\(aq/etc/hosts\(aq, entries=None) Remove a host from the /etc/hosts file. If doing so will leave a line containing only an IP address, then the line will be deleted. This function will leave comments and blank lines intact. .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq dnsutil.hosts_remove /etc/hosts ad1.yuk.co salt \(aq*\(aq dnsutil.hosts_remove /etc/hosts ad2.yuk.co,ad1.yuk.co .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.dnsutil.parse_hosts(hostsfile=\(aq/etc/hosts\(aq, hosts=None) Parse /etc/hosts file. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq dnsutil.parse_hosts .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.dnsutil.parse_zone(zonefile=None, zone=None) Parses a zone file. Can be passed raw zone data on the API level. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt ns1 dnsutil.parse_zone /var/lib/named/example.com.zone .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.dockerio .SS Management of dockers .sp New in version 2014.1.0. .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 The DockerIO integration is still in beta; the API is subject to change .UNINDENT .UNINDENT .SS General notes .INDENT 0.0 .IP \(bu 2 As we use states, we don\(aqt want to be continuously popping dockers, so we will map each container id (or image) with a grain whenever it is relevant. .IP \(bu 2 As a corollary, we will resolve a container id either directly by the id or try to find a container id matching something stocked in grain. .UNINDENT .SS Installation prerequisites .INDENT 0.0 .IP \(bu 2 You will need the \(aqdocker\-py\(aq python package in your python installation running salt. The version of docker\-py should support \fI\%version 1.12 of docker remote API.\fP\&. .IP \(bu 2 For now, you need docker\-py 0.3.2 .INDENT 2.0 .INDENT 3.5 pip install docker\-py==0.3.2 .UNINDENT .UNINDENT .UNINDENT .SS Prerequisite pillar configuration for authentication .INDENT 0.0 .IP \(bu 2 To push or pull you will need to be authenticated as the docker\-py bindings require it .IP \(bu 2 For this to happen, you will need to configure a mapping in the pillar representing your per URL authentication bits: .INDENT 2.0 .INDENT 3.5 .sp .nf .ft C docker\-registries: registry_url: email: foo@foo.com password: s3cr3t username: foo .ft P .fi .UNINDENT .UNINDENT .IP \(bu 2 You need at least an entry to the default docker index: .INDENT 2.0 .INDENT 3.5 .sp .nf .ft C docker\-registries: https://index.docker.io/v1: email: foo@foo.com password: s3cr3t username: foo .ft P .fi .UNINDENT .UNINDENT .UNINDENT .sp you can define multiple registries blocks for them to be aggregated, their id just must finish with \-docker\-registries: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C ac\-docker\-registries: https://index.bar.io/v1: email: foo@foo.com password: s3cr3t username: foo ab\-docker\-registries: https://index.foo.io/v1: email: foo@foo.com password: s3cr3t username: foo .ft P .fi .UNINDENT .UNINDENT .sp Would be the equivalent to: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C docker\-registries: https://index.bar.io/v1: email: foo@foo.com password: s3cr3t username: foo https://index.foo.io/v1: email: foo@foo.com password: s3cr3t username: foo .ft P .fi .UNINDENT .UNINDENT .SS Registry dialog methods .INDENT 0.0 .IP \(bu 2 login .IP \(bu 2 push .IP \(bu 2 pull .UNINDENT .SS Docker management .INDENT 0.0 .IP \(bu 2 version .IP \(bu 2 info .UNINDENT .SS Image management .sp You have those methods: .INDENT 0.0 .IP \(bu 2 search .IP \(bu 2 inspect_image .IP \(bu 2 get_images .IP \(bu 2 remove_image .IP \(bu 2 import_image .IP \(bu 2 build .IP \(bu 2 tag .UNINDENT .SS Container management .sp You have those methods: .INDENT 0.0 .IP \(bu 2 start .IP \(bu 2 stop .IP \(bu 2 restart .IP \(bu 2 kill .IP \(bu 2 wait .IP \(bu 2 get_containers .IP \(bu 2 inspect_container .IP \(bu 2 remove_container .IP \(bu 2 is_running .IP \(bu 2 top .IP \(bu 2 ports .IP \(bu 2 logs .IP \(bu 2 diff .IP \(bu 2 commit .IP \(bu 2 create_container .IP \(bu 2 export .IP \(bu 2 get_container_root .UNINDENT .SS Runtime execution within a specific already existing and running container .INDENT 0.0 .IP \(bu 2 Idea is to use lxc\-attach to execute inside the container context. .IP \(bu 2 We do not use a "docker run command" but want to execute something inside a running container. .UNINDENT .sp You have those methods: .INDENT 0.0 .IP \(bu 2 retcode .IP \(bu 2 run .IP \(bu 2 run_all .IP \(bu 2 run_stderr .IP \(bu 2 run_stdout .IP \(bu 2 script .IP \(bu 2 script_retcode .UNINDENT .INDENT 0.0 .TP .B salt.modules.dockerio.build(path=None, tag=None, quiet=False, fileobj=None, nocache=False, rm=True, timeout=None) Build a docker image from a dockerfile or an URL .sp You can either: .INDENT 7.0 .INDENT 3.5 .INDENT 0.0 .IP \(bu 2 give the url/branch/docker_dir .IP \(bu 2 give a path on the file system .UNINDENT .UNINDENT .UNINDENT .INDENT 7.0 .TP .B path URL or path in the filesystem to the dockerfile .TP .B tag Tag of the image .TP .B quiet quiet mode .TP .B nocache do not use docker image cache .TP .B rm remove intermediate commits .TP .B timeout timeout is seconds before aborting .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq docker.build .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.dockerio.commit(container, repository=None, tag=None, message=None, author=None, conf=None) Commit a container (promotes it to an image) .INDENT 7.0 .TP .B container container id .TP .B repository repository/imageName to commit to .TP .B tag optional tag .TP .B message optional commit message .TP .B author optional author .TP .B conf optional conf .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq docker.commit .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.dockerio.create_container(image, command=None, hostname=None, user=None, detach=True, stdin_open=False, tty=False, mem_limit=0, ports=None, environment=None, dns=None, volumes=None, volumes_from=None, name=None) Create a new container .INDENT 7.0 .TP .B image image to create the container from .TP .B command command to execute while starting .TP .B hostname hostname of the container .TP .B user user to run docker as .TP .B detach daemon mode .TP .B environment environment variable mapping ({\(aqfoo\(aq:\(aqBAR\(aq}) .TP .B ports ports redirections ({\(aq222\(aq: {}}) .TP .B volumes list of volumes mapping: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C ([\(aq/mountpoint/in/container:/guest/foo\(aq, \(aq/same/path/mounted/point\(aq]) .ft P .fi .UNINDENT .UNINDENT .TP .B tty attach ttys .TP .B stdin_open let stdin open .TP .B name name given to container .UNINDENT .sp EG: .INDENT 7.0 .INDENT 3.5 salt\-call docker.create_container o/ubuntu volumes="[\(aq/s\(aq,\(aq/m:/f\(aq]" .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq docker.create_container .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.dockerio.diff(container) Get container diffs .INDENT 7.0 .TP .B container container id .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq docker.diff .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.dockerio.exists(container) Check if a given container exists .INDENT 7.0 .TP .B Parameters \fBcontainer\fP (\fI\%string\fP) \-\- Container id .TP .B Return type boolean: .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq docker.exists .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.dockerio.export(container, path) Export a container to a file .INDENT 7.0 .TP .B container container id .TP .B path path to the export .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq docker.export .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.dockerio.get_container_root(container) Get the container rootfs path .INDENT 7.0 .TP .B container container id or grain .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq docker.get_container_root .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.dockerio.get_containers(all=True, trunc=False, since=None, before=None, limit=\-1, host=False) Get a list of mappings representing all containers .INDENT 7.0 .TP .B all Return all containers .TP .B trunc Set it to True to have the short ID .TP .B host Include the Docker host\(aqs ipv4 and ipv6 address in return .UNINDENT .sp Returns a mapping of something which looks like container .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq docker.get_containers salt \(aq*\(aq docker.get_containers host=True .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.dockerio.get_images(name=None, quiet=False, all=True) List docker images .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBname\fP (\fI\%string\fP) \-\- A repository name to filter on .IP \(bu 2 \fBquiet\fP (\fIboolean\fP) \-\- Only show image ids .IP \(bu 2 \fBall\fP (\fIboolean\fP) \-\- Show all images .UNINDENT .TP .B Return type dict .TP .B Returns A status message with the command output .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq docker.get_images [name] [quiet=True|False] [all=True|False] .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.dockerio.import_image(src, repo, tag=None) Import content from a local tarball or a URL to a docker image .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBsrc\fP (\fI\%string\fP) \-\- The content to import (URL, absolute path to a tarball) .IP \(bu 2 \fBrepo\fP (\fI\%string\fP) \-\- The repository to import to .IP \(bu 2 \fBtag\fP (\fI\%string\fP) \-\- An optional tag to set .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq docker.import_image [tag] .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.dockerio.info() Get the version information about docker .INDENT 7.0 .TP .B Return type dict .TP .B Returns A status message with the command output .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq docker.info .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.dockerio.inspect_container(container) Get container information. This is similar to the docker inspect command. .INDENT 7.0 .TP .B Parameters \fBcontainer\fP (\fI\%string\fP) \-\- The id of the container to inspect .TP .B Return type dict .TP .B Returns A status message with the command output .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq docker.inspect_container .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.dockerio.inspect_image(image) Inspect the status of an image and return relative data .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq docker.inspect_image .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.dockerio.is_running(container) Is this container running .INDENT 7.0 .TP .B container Container id .UNINDENT .sp Return boolean .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq docker.is_running .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.dockerio.kill(container) Kill a running container .INDENT 7.0 .TP .B Parameters \fBcontainer\fP (\fI\%string\fP) \-\- The container id to kill .TP .B Return type dict .TP .B Returns A status message with the command output ex: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C {\(aqid\(aq: \(aqabcdef123456789\(aq, \(aqstatus\(aq: True} .ft P .fi .UNINDENT .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq docker.kill .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.dockerio.login(url=None, username=None, password=None, email=None) Wrapper to the docker.py login method, does not do much yet .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq docker.login .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.dockerio.logs(container) Return logs for a specified container .INDENT 7.0 .TP .B container container id .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq docker.logs .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.dockerio.port(container, private_port) Private/Public for a specific port mapping allocation information This method is broken on docker\-py side Just use the result of inspect to mangle port allocation .INDENT 7.0 .TP .B container container id .TP .B private_port private port on the container to query for .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq docker.port .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.dockerio.pull(repo, tag=None) Pulls an image from any registry. See above documentation for how to configure authenticated access. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBrepo\fP (\fI\%string\fP) \-\- .sp The repository to pull. [registryurl://]REPOSITORY_NAME_image eg: .INDENT 2.0 .INDENT 3.5 .sp .nf .ft C index.docker.io:MyRepo/image superaddress.cdn:MyRepo/image MyRepo/image .ft P .fi .UNINDENT .UNINDENT .IP \(bu 2 \fBtag\fP (\fI\%string\fP) \-\- The specific tag to pull .UNINDENT .TP .B Return type dict .TP .B Returns A status message with the command output Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C \-\-\-\-\-\-\-\-\-\- comment: Image NAME was pulled (ID id: None out: \-\-\-\-\-\-\-\-\-\- \- id: 2c80228370c9 \- status: Download complete \-\-\-\-\-\-\-\-\-\- \- id: 2c80228370c9 \- progress: [=========================> ] \- status: Downloading \-\-\-\-\-\-\-\-\-\- \- id: 2c80228370c9 \- status Pulling image (latest) from foo/ubuntubox \-\-\-\-\-\-\-\-\-\- \- status: Pulling repository foo/ubuntubox status: True .ft P .fi .UNINDENT .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq docker.pull [tag] .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.dockerio.push(repo) Pushes an image from any registry See this top level documentation to know how to configure authenticated access .INDENT 7.0 .TP .B repo [registryurl://]REPOSITORY_NAME_image eg: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C index.docker.io:MyRepo/image superaddress.cdn:MyRepo/image MyRepo/image .ft P .fi .UNINDENT .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq docker.push .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.dockerio.remove_container(container, force=False, v=False) Removes a container from a docker installation .INDENT 7.0 .TP .B container Container id to remove .TP .B force By default, do not remove a running container, set this to remove it unconditionally .TP .B v verbose mode .UNINDENT .sp Return True or False in the status mapping and also any information about docker in status[\(aqout\(aq] .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq docker.remove_container .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.dockerio.remove_image(image) Remove an image from a system. .INDENT 7.0 .TP .B Parameters \fBimage\fP (\fI\%string\fP) \-\- The image to remove .TP .B Return type string .TP .B Returns A status message. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq docker.remove_image .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.dockerio.restart(container, timeout=10) Restart a running container .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBcontainer\fP (\fI\%string\fP) \-\- The container id to restart .IP \(bu 2 \fBtimeout\fP \-\- Wait for a timeout to let the container exit gracefully before killing it .UNINDENT .TP .B Return type dict .TP .B Returns A status message with the command output ex: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C {\(aqid\(aq: \(aqabcdef123456789\(aq, \(aqstatus\(aq: True} .ft P .fi .UNINDENT .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq docker.restart .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.dockerio.retcode(container, cmd) Wrapper for cmdmod.retcode inside a container context .INDENT 7.0 .TP .B container container id (or grain) .TP .B Other params: See cmdmod documentation .UNINDENT .sp The return is a bit different as we use the docker struct, The output of the command is in \(aqout\(aq The result is false if command failed .INDENT 7.0 .TP .B WARNING: Be advised that this function allows for raw shell access to the named container! If allowing users to execute this directly it may allow more rights than intended! .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq docker.retcode \(aqls \-l /etc\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.dockerio.run(container, cmd) Wrapper for cmdmod.run inside a container context .INDENT 7.0 .TP .B container container id (or grain) .TP .B Other params: See cmdmod documentation .UNINDENT .sp The return is a bit different as we use the docker struct, The output of the command is in \(aqout\(aq The result is always True .INDENT 7.0 .TP .B WARNING: Be advised that this function allows for raw shell access to the named container! If allowing users to execute this directly it may allow more rights than intended! .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq docker.run \(aqls \-l /etc\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.dockerio.run_all(container, cmd) Wrapper for cmdmod.run_all inside a container context .INDENT 7.0 .TP .B container container id (or grain) .TP .B Other params: See cmdmod documentation .UNINDENT .sp The return is a bit different as we use the docker struct, The output of the command is in \(aqout\(aq The result if false if command failed .INDENT 7.0 .TP .B WARNING: Be advised that this function allows for raw shell access to the named container! If allowing users to execute this directly it may allow more rights than intended! .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq docker.run_all \(aqls \-l /etc\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.dockerio.run_stderr(container, cmd) Wrapper for cmdmod.run_stderr inside a container context .INDENT 7.0 .TP .B container container id (or grain) .TP .B Other params: See cmdmod documentation .UNINDENT .sp The return is a bit different as we use the docker struct, The output of the command is in \(aqout\(aq The result is always True .INDENT 7.0 .TP .B WARNING: Be advised that this function allows for raw shell access to the named container! If allowing users to execute this directly it may allow more rights than intended! .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq docker.run_stderr \(aqls \-l /etc\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.dockerio.run_stdout(container, cmd) Wrapper for cmdmod.run_stdout inside a container context .INDENT 7.0 .TP .B container container id (or grain) .TP .B Other params: See cmdmod documentation .UNINDENT .sp The return is a bit different as we use the docker struct, The output of the command is in \(aqout\(aq The result is always True .INDENT 7.0 .TP .B WARNING: Be advised that this function allows for raw shell access to the named container! If allowing users to execute this directly it may allow more rights than intended! .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq docker.run_stdout \(aqls \-l /etc\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.dockerio.script(container, source, args=None, cwd=None, stdin=None, runas=None, shell=\(aq/bin/sh\(aq, env=None, template=\(aqjinja\(aq, umask=None, timeout=None, reset_system_locale=True, no_clean=False, saltenv=\(aqbase\(aq) Same usage as cmd.script but running inside a container context .INDENT 7.0 .TP .B container container id or grain .TP .B others params and documentation See cmd.retcode .TP .B WARNING: Be advised that this function allows for raw shell access to the named container! If allowing users to execute this directly it may allow more rights than intended! .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq docker.script salt://docker_script.py .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.dockerio.script_retcode(container, source, cwd=None, stdin=None, runas=None, shell=\(aq/bin/sh\(aq, env=None, template=\(aqjinja\(aq, umask=None, timeout=None, reset_system_locale=True, no_clean=False, saltenv=\(aqbase\(aq) Same usage as cmd.script_retcode but running inside a container context .INDENT 7.0 .TP .B container container id or grain .TP .B others params and documentation See cmd.retcode .TP .B WARNING: Be advised that this function allows for raw shell access to the named container! If allowing users to execute this directly it may allow more rights than intended! .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq docker.script_retcode salt://docker_script.py .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.dockerio.search(term) Search for an image on the registry .INDENT 7.0 .TP .B Parameters \fBterm\fP (\fI\%string\fP) \-\- The search keyword to query .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq docker.search .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.dockerio.start(container, binds=None, port_bindings=None, lxc_conf=None, publish_all_ports=None, links=None, privileged=False, dns=None, volumes_from=None, network_mode=None) Restart the specified container .INDENT 7.0 .TP .B container Container id .TP .B Returns the status mapping as usual .INDENT 7.0 .TP .B {\(aqid\(aq: id of the container, \(aqstatus\(aq: True if started } .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq docker.start .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.dockerio.stop(container, timeout=10) Stop a running container .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBcontainer\fP (\fI\%string\fP) \-\- The container id to stop .IP \(bu 2 \fBtimeout\fP (\fI\%int\fP) \-\- Wait for a timeout to let the container exit gracefully before killing it .UNINDENT .TP .B Return type dict .TP .B Returns A status message with the command output ex: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C {\(aqid\(aq: \(aqabcdef123456789\(aq, \(aqstatus\(aq: True} .ft P .fi .UNINDENT .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq docker.stop .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.dockerio.tag(image, repository, tag=None, force=False) Tag an image into a repository .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBimage\fP (\fI\%string\fP) \-\- The image to tag .IP \(bu 2 \fBrepository\fP (\fI\%string\fP) \-\- The repository to tag the image .IP \(bu 2 \fBtag\fP (\fI\%string\fP) \-\- The tag to apply .IP \(bu 2 \fBforce\fP (\fIboolean\fP) \-\- Forces application of the tag .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq docker.tag [tag] [force=(True|False)] .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.dockerio.top(container) Run the docker top command on a specific container .INDENT 7.0 .TP .B container Container id .UNINDENT .sp Returns in the \(aqout\(aq status mapping a mapping for those running processes: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C { \(aqTitles\(aq: top titles list, \(aqprocesses\(aq: list of ordered by titles processes information, \(aqmprocesses\(aq: list of mappings processes information constructed above the upon information } .ft P .fi .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq docker.top .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.dockerio.version() Get docker version .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq docker.version .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.dockerio.wait(container) Blocking wait for a container exit gracefully without timeout killing it .INDENT 7.0 .TP .B container Container id .TP .B Return container id if successful .INDENT 7.0 .TP .B {\(aqid\(aq: id of the container, \(aqstatus\(aq: True if stopped } .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq docker.wait .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.dpkg .sp Support for DEB packages .INDENT 0.0 .TP .B salt.modules.dpkg.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: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq lowpkg.file_list httpd salt \(aq*\(aq lowpkg.file_list httpd postfix salt \(aq*\(aq lowpkg.file_list .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.dpkg.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: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq lowpkg.file_list httpd salt \(aq*\(aq lowpkg.file_list httpd postfix salt \(aq*\(aq lowpkg.file_list .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.dpkg.list_pkgs(*packages) List the packages currently installed in a dict: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C {\(aq\(aq: \(aq\(aq} .ft P .fi .UNINDENT .UNINDENT .sp External dependencies: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C Virtual package resolution requires aptitude. Because this function uses dpkg, virtual packages will be reported as not installed. .ft P .fi .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq lowpkg.list_pkgs salt \(aq*\(aq lowpkg.list_pkgs httpd .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.dpkg.unpurge(*packages) Change package selection for each package specified to \(aqinstall\(aq .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq lowpkg.unpurge curl .ft P .fi .UNINDENT .UNINDENT .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.check_db(*names, **kwargs) New in version 0.17.0. .sp Returns a dict containing the following information for each specified package: .INDENT 7.0 .IP 1. 3 A key \fBfound\fP, which will be a boolean value denoting if a match was found in the package database. .IP 2. 3 If \fBfound\fP is \fBFalse\fP, then a second key called \fBsuggestions\fP will be present, which will contain a list of possible matches. This list will be empty if the package name was specified in \fBcategory/pkgname\fP format, since the suggestions are only intended to disambiguate ambiguous package names (ones submitted without a category). .UNINDENT .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.check_db .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.ebuild.check_extra_requirements(pkgname, pkgver) Check if the installed package already has the given requirements. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.check_extra_requirements \(aqsys\-devel/gcc\(aq \(aq~>4.1.2:4.1::gentoo[nls,fortran]\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.ebuild.depclean(name=None, slot=None, fromrepo=None, pkgs=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 name The name of the package to be cleaned. .TP .B slot Restrict the remove to a specific slot. Ignored if \fBname\fP is None. .TP .B fromrepo Restrict the remove to a specific slot. Ignored if \fBname\fP is None. .TP .B pkgs Clean multiple packages. \fBslot\fP and \fBfromrepo\fP arguments are ignored if this argument is present. Must be passed as a python list. .UNINDENT .sp Return a list containing the removed packages: .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.depclean .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.ebuild.ex_mod_init(low) If the config option \fBebuild.enforce_nice_config\fP is set to True, this module will enforce a nice tree structure for /etc/portage/package.* configuration files. .sp New in version 0.17.0: Initial automatic enforcement added when pkg is used on a Gentoo system. .sp Changed in version 2014.1.0\-Hydrogen: Configure option added to make this behaviour optional, defaulting to off. .sp \fBSEE ALSO:\fP .INDENT 7.0 .INDENT 3.5 \fBebuild.ex_mod_init\fP is called automatically when a state invokes a pkg state on a Gentoo system. \fBsalt.states.pkg.mod_init()\fP .sp \fBebuild.ex_mod_init\fP uses \fBportage_config.enforce_nice_config\fP to do the lifting. \fBsalt.modules.portage_config.enforce_nice_config()\fP .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.ex_mod_init .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.ebuild.install(name=None, refresh=False, pkgs=None, sources=None, slot=None, fromrepo=None, uses=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. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.install .ft P .fi .UNINDENT .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. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.install sys\-devel/gcc slot=\(aq4.4\(aq .ft P .fi .UNINDENT .UNINDENT .TP .B fromrepo Similar to slot, but specifies the repository from the package will be installed. It will install the latest available version in the specified repository. Ignored if "pkgs" or "sources" or "version" is passed. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.install salt fromrepo=\(aqgentoo\(aq .ft P .fi .UNINDENT .UNINDENT .TP .B uses Similar to slot, but specifies a list of use flag. Ignored if "pkgs" or "sources" or "version" is passed. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.install sys\-devel/gcc uses=\(aq["nptl","\-nossp"]\(aq .ft P .fi .UNINDENT .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. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.install pkgs=\(aq["foo","bar","~category/package:slot::repository[use]"]\(aq .ft P .fi .UNINDENT .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. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.install sources=\(aq[{"foo": "salt://foo.tbz2"},{"bar": "salt://bar.tbz2"}]\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .sp Returns a dict containing the new package names and versions: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C {\(aq\(aq: {\(aqold\(aq: \(aq\(aq, \(aqnew\(aq: \(aq\(aq}} .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.ebuild.latest_version(*names, **kwargs) 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: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.latest_version salt \(aq*\(aq pkg.latest_version ... .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.ebuild.list_pkgs(versions_as_list=False, **kwargs) List the packages currently installed in a dict: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C {\(aq\(aq: \(aq\(aq} .ft P .fi .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.list_pkgs .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.ebuild.list_upgrades(refresh=True) List all available package upgrades. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.list_upgrades .ft P .fi .UNINDENT .UNINDENT .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(name=None, slot=None, fromrepo=None, pkgs=None, **kwargs) Portage does not have a purge, this function calls remove followed by depclean to emulate a purge process .INDENT 7.0 .TP .B name The name of the package to be deleted. .TP .B slot Restrict the remove to a specific slot. Ignored if name is None. .TP .B fromrepo Restrict the remove to a specific slot. Ignored if \fBname\fP is None. .UNINDENT .sp Multiple Package Options: .INDENT 7.0 .TP .B pkgs Uninstall multiple packages. \fBslot\fP and \fBfromrepo\fP arguments are ignored if this argument is present. Must be passed as a python list. .UNINDENT .sp New in version 0.16.0. .sp Returns a dict containing the changes. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.purge salt \(aq*\(aq pkg.purge slot=4.4 salt \(aq*\(aq pkg.purge ,, salt \(aq*\(aq pkg.purge pkgs=\(aq["foo", "bar"]\(aq .ft P .fi .UNINDENT .UNINDENT .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: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.refresh_db .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.ebuild.remove(name=None, slot=None, fromrepo=None, pkgs=None, **kwargs) Remove packages via emerge \-\-unmerge. .INDENT 7.0 .TP .B name The name of the package to be deleted. .TP .B slot Restrict the remove to a specific slot. Ignored if \fBname\fP is None. .TP .B fromrepo Restrict the remove to a specific slot. Ignored if \fBname\fP is None. .UNINDENT .sp Multiple Package Options: .INDENT 7.0 .TP .B pkgs Uninstall multiple packages. \fBslot\fP and \fBfromrepo\fP arguments are ignored if this argument is present. Must be passed as a python list. .UNINDENT .sp New in version 0.16.0. .sp Returns a dict containing the changes. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.remove salt \(aq*\(aq pkg.remove slot=4.4 fromrepo=gentoo salt \(aq*\(aq pkg.remove ,, salt \(aq*\(aq pkg.remove pkgs=\(aq["foo", "bar"]\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.ebuild.update(pkg, slot=None, fromrepo=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. .TP .B fromrepo Restrict the update to a particular repository. It will update to the latest version within the repository. .UNINDENT .sp Return a dict containing the new package names and versions: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C {\(aq\(aq: {\(aqold\(aq: \(aq\(aq, \(aqnew\(aq: \(aq\(aq}} .ft P .fi .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.update .ft P .fi .UNINDENT .UNINDENT .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: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C {\(aq\(aq: {\(aqold\(aq: \(aq\(aq, \(aqnew\(aq: \(aq\(aq}} .ft P .fi .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.upgrade .ft P .fi .UNINDENT .UNINDENT .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: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.upgrade_available .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.ebuild.version(*names, **kwargs) 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: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.version salt \(aq*\(aq pkg.version ... .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.ebuild.version_clean(version) Clean the version string removing extra data. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.version_clean .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.ebuild.version_cmp(pkg1, pkg2) 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: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.version_cmp \(aq0.2.4\-0\(aq \(aq0.2.4.1\-0\(aq .ft P .fi .UNINDENT .UNINDENT .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: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq eix.sync .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.eix.update() Update the eix database .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq eix.update .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.eselect .sp Support for eselect, Gentoo\(aqs configuration and management tool. .INDENT 0.0 .TP .B salt.modules.eselect.exec_action(module, action, parameter=\(aq\(aq, state_only=False) Execute an arbitrary action on a module. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq eselect.exec_action [parameter] .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.eselect.get_current_target(module) Get the currently selected target for the given module. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq eselect.get_current_target .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.eselect.get_modules() Get available modules list. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq eselect.get_modules .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.eselect.get_target_list(module) Get available target for the given module. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq eselect.get_target_list .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.eselect.set_target(module, target) Set the target for the given module. Target can be specified by index or name. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq eselect.set_target .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.event .sp Use the \fBSalt Event System\fP to fire events from the master to the minion and vice\-versa. .INDENT 0.0 .TP .B salt.modules.event.fire(data, tag) Fire an event on the local minion event bus. Data must be formed as a dict. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq event.fire \(aq{"data":"my event data"}\(aq \(aqtag\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.event.fire_master(data, tag, preload=None) Fire an event off up to the master server .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq event.fire_master \(aq{"data":"my event data"}\(aq \(aqtag\(aq .ft P .fi .UNINDENT .UNINDENT .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: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq extfs.attributes /dev/sda1 .ft P .fi .UNINDENT .UNINDENT .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: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq extfs.blocks /dev/sda1 .ft P .fi .UNINDENT .UNINDENT .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: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq extfs.dump /dev/sda1 .ft P .fi .UNINDENT .UNINDENT .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: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq extfs.mkfs /dev/sda1 fs_type=ext4 opts=\(aqacl,noexec\(aq .ft P .fi .UNINDENT .UNINDENT .sp Valid options are: .INDENT 7.0 .INDENT 3.5 .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 .ft P .fi .UNINDENT .UNINDENT .sp See the \fBmke2fs(8)\fP manpage for a more complete description of these options. .UNINDENT .INDENT 0.0 .TP .B salt.modules.extfs.tune(device, **kwargs) Set attributes for the specified device (using tune2fs) .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq extfs.tune /dev/sda1 force=True label=wildstallyns opts=\(aqacl,noexec\(aq .ft P .fi .UNINDENT .UNINDENT .sp Valid options are: .INDENT 7.0 .INDENT 3.5 .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 .ft P .fi .UNINDENT .UNINDENT .sp See the \fBmke2fs(8)\fP manpage for a more complete description of these options. .UNINDENT .SS salt.modules.file .sp Manage information about regular files, directories, and special files on the minion, set/read user, group, mode, and data .INDENT 0.0 .TP .B salt.modules.file.access(path, mode) Test whether the Salt process has the specified access to the file. One of the following modes must be specified: .INDENT 7.0 .INDENT 3.5 f: Test the existence of the path r: Test the readability of the path w: Test the writability of the path x: Test whether the path can be executed .UNINDENT .UNINDENT .sp New in version 2014.1.0: (Hydrogen) .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq file.access /path/to/file f salt \(aq*\(aq file.access /path/to/file x .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.file.append(path, *args) New in version 0.9.5. .sp Append text to the end of a file .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .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 .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.file.blockreplace(path, marker_start=\(aq#\-\- start managed zone \-\-\(aq, marker_end=\(aq#\-\- end managed zone \-\-\(aq, content=\(aq\(aq, append_if_not_found=False, prepend_if_not_found=False, backup=\(aq.bak\(aq, dry_run=False, show_changes=True) Replace content of a text block in a file, delimited by line markers .sp New in version 2014.1.0: (Hydrogen) .sp A block of content delimited by comments can help you manage several lines entries without worrying about old entries removal. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 This function will store two copies of the file in\-memory (the original version and the edited version) in order to detect changes and only edit the targeted file if necessary. .UNINDENT .UNINDENT .INDENT 7.0 .TP .B path Filesystem path to the file to be edited .TP .B marker_start The line content identifying a line as the start of the content block. Note that the whole line containing this marker will be considered, so whitespaces or extra content before or after the marker is included in final output .TP .B marker_end The line content identifying a line as the end of the content block. Note that the whole line containing this marker will be considered, so whitespaces or extra content before or after the marker is included in final output .TP .B content The content to be used between the two lines identified by marker_start and marker_stop. .TP .B append_if_not_found False If markers are not found and set to \fBTrue\fP then, the markers and content will be appended to the file. .TP .B prepend_if_not_found False If markers are not found and set to \fBTrue\fP then, the markers and content will be prepended to the file. .TP .B backup The file extension to use for a backup of the file if any edit is made. Set to \fBFalse\fP to skip making a backup. .TP .B dry_run Don\(aqt make any edits to the file. .TP .B show_changes Output a unified diff of the old file and the new file. If \fBFalse\fP, return a boolean if any changes were made. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq file.blockreplace /etc/hosts \(aq#\-\- start managed zone foobar : DO NOT EDIT \-\-\(aq \e \(aq#\-\- end managed zone foobar \-\-\(aq $\(aq10.0.1.1 foo.foobar\en10.0.1.2 bar.foobar\(aq True .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.file.check_file_meta(name, sfn, source, source_sum, user, group, mode, saltenv, template=None, contents=None) Check for the changes in the file metadata. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .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 .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.file.check_hash(path, file_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: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq file.check_hash /etc/fstab md5= .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.file.check_managed(name, source, source_hash, user, group, mode, template, context, defaults, saltenv, contents=None, **kwargs) Check to see what changes need to be made for a file .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .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 .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.file.check_perms(name, ret, user, group, mode, follow_symlinks=False) Check the permissions on files and chown if needed .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq file.check_perms /etc/sudoers \(aq{}\(aq root root 400 .ft P .fi .UNINDENT .UNINDENT .sp Changed in version 2014.1.3: \fBfollow_symlinks\fP option added .UNINDENT .INDENT 0.0 .TP .B salt.modules.file.chgrp(path, group) Change the group of a file .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq file.chgrp /etc/passwd root .ft P .fi .UNINDENT .UNINDENT .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: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq file.chown /etc/passwd root root .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.file.comment(path, regex, char=\(aq#\(aq, backup=\(aq.bak\(aq) Deprecated since version 0.17.0: Use \fBreplace()\fP instead. .sp 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 .sp \fBWARNING:\fP .INDENT 7.0 .INDENT 3.5 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. .UNINDENT .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq file.comment /etc/modules pcspkr .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.file.contains(path, text) Deprecated since version 0.17.0: Use \fBsearch()\fP instead. .sp Return \fBTrue\fP if the file at \fBpath\fP contains \fBtext\fP .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq file.contains /etc/crontab \(aqmymaintenance.sh\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.file.contains_glob(path, glob_expr) Deprecated since version 0.17.0: Use \fBsearch()\fP instead. .sp Return \fBTrue\fP if the given glob matches a string in the named file .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq file.contains_glob /etc/foobar \(aq*cheese*\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.file.contains_regex(path, regex, lchar=\(aq\(aq) Deprecated since version 0.17.0: Use \fBsearch()\fP instead. .sp Return True if the given regular expression matches on any line in the text of a given file. .sp If the lchar argument (leading char) is specified, it will strip \fIlchar\fP from the left side of each line before trying to match .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq file.contains_regex /etc/crontab .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.file.contains_regex_multiline(path, regex) Deprecated since version 0.17.0: Use \fBsearch()\fP instead. .sp Return True if the given regular expression matches anything in the text of a given file .sp Traverses multiple lines at a time, via the salt BufferedReader (reads in chunks) .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq file.contains_regex_multiline /etc/crontab \(aq^maint\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.file.copy(src, dst) Copy a file or directory .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq file.copy /path/to/src /path/to/dst .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.file.delete_backup(path, backup_id) Restore a previous version of a file that was backed up using Salt\(aqs \fBfile state backup\fP system. .sp New in version 0.17.0. .INDENT 7.0 .TP .B path The path on the minion to check for backups .TP .B backup_id The numeric id for the backup you wish to delete, as found using \fBfile.list_backups\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq file.restore_backup /foo/bar/baz.txt 0 .ft P .fi .UNINDENT .UNINDENT .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: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq file.directory_exists /etc .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.file.extract_hash(hash_fn, hash_type=\(aqmd5\(aq, file_name=\(aq\(aq) This routine is called from the \fBfile.managed\fP state to pull a hash from a remote file. Regular expressions are used line by line on the \fBsource_hash\fP file, to find a potential candidate of the indicated hash type. This avoids many problems of arbitrary file lay out rules. It specifically permits pulling hash codes from debian \fB*.dsc\fP files. .sp For example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C openerp_7.0\-latest\-1.tar.gz: file.managed: \- name: /tmp/openerp_7.0\-20121227\-075624\-1_all.deb \- source: http://nightly.openerp.com/7.0/nightly/deb/openerp_7.0\-20121227\-075624\-1.tar.gz \- source_hash: http://nightly.openerp.com/7.0/nightly/deb/openerp_7.0\-20121227\-075624\-1.dsc .ft P .fi .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq file.extract_hash /etc/foo sha512 /path/to/hash/file .ft P .fi .UNINDENT .UNINDENT .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: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq file.file_exists /etc/passwd .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.file.find(path, **kwargs) Approximate the Unix \fBfind(1)\fP command and return a list of paths that meet the specified criteria. .sp The options include match criteria: .INDENT 7.0 .INDENT 3.5 .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 .UNINDENT .UNINDENT .sp and/or actions: .INDENT 7.0 .INDENT 3.5 .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 .UNINDENT .UNINDENT .sp The default action is \(aqprint=path\(aq. .sp file\-glob: .INDENT 7.0 .INDENT 3.5 .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 .UNINDENT .UNINDENT .sp path\-regex: a Python re (regular expression) pattern to match pathnames .sp file\-types: a string of one or more of the following: .INDENT 7.0 .INDENT 3.5 .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 .UNINDENT .UNINDENT .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: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C b: bytes k: kilobytes m: megabytes g: gigabytes t: terabytes .ft P .fi .UNINDENT .UNINDENT .sp interval: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C [w] [d] [h] [m] [s] where: w: week d: day h: hour m: minute s: second .ft P .fi .UNINDENT .UNINDENT .sp print\-opts: a comma and/or space separated list of one or more of the following: .INDENT 7.0 .INDENT 3.5 .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 .UNINDENT .UNINDENT .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .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 .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.file.get_devmm(name) Get major/minor info from a device .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq file.get_devmm /dev/chr .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.file.get_diff(minionfile, masterfile, env=None, saltenv=\(aqbase\(aq) Return unified diff of file compared to file on master .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq file.get_diff /home/fred/.vimrc salt://users/fred/.vimrc .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.file.get_gid(path, follow_symlinks=True) Return the id of the group that owns a given file .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq file.get_gid /etc/passwd .ft P .fi .UNINDENT .UNINDENT .sp Changed in version 0.16.4: \fBfollow_symlinks\fP option added .UNINDENT .INDENT 0.0 .TP .B salt.modules.file.get_group(path, follow_symlinks=True) Return the group that owns a given file .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq file.get_group /etc/passwd .ft P .fi .UNINDENT .UNINDENT .sp Changed in version 0.16.4: \fBfollow_symlinks\fP option added .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: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq file.get_hash /etc/shadow .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.file.get_managed(name, template, source, source_hash, user, group, mode, saltenv, context, defaults, **kwargs) Return the managed file data for file.managed .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .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 .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.file.get_mode(path, follow_symlinks=True) Return the mode of a file .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq file.get_mode /etc/passwd .ft P .fi .UNINDENT .UNINDENT .sp Changed in version 2014.1.0: \fBfollow_symlinks\fP option added .UNINDENT .INDENT 0.0 .TP .B salt.modules.file.get_selinux_context(path) Get an SELinux context from a given path .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq file.get_selinux_context /etc/hosts .ft P .fi .UNINDENT .UNINDENT .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: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq file.get_sum /etc/passwd sha512 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.file.get_uid(path, follow_symlinks=True) Return the id of the user that owns a given file .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq file.get_uid /etc/passwd .ft P .fi .UNINDENT .UNINDENT .sp Changed in version 0.16.4: \fBfollow_symlinks\fP option added .UNINDENT .INDENT 0.0 .TP .B salt.modules.file.get_user(path, follow_symlinks=True) Return the user that owns a given file .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq file.get_user /etc/passwd .ft P .fi .UNINDENT .UNINDENT .sp Changed in version 0.16.4: \fBfollow_symlinks\fP option added .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: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq file.gid_to_group 0 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.file.grep(path, pattern, *args) Grep for a string in the specified file .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 This function\(aqs return value is slated for refinement in future versions of Salt .UNINDENT .UNINDENT .INDENT 7.0 .TP .B path A file path .TP .B pattern A string. For example: \fBtest\fP \fBa[0\-5]\fP .TP .B args grep options. For example: \fB" \-v"\fP \fB" \-i \-B2"\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq file.grep /etc/passwd nobody salt \(aq*\(aq file.grep /etc/sysconfig/network\-scripts/ifcfg\-eth0 ipaddr " \-i" salt \(aq*\(aq file.grep /etc/sysconfig/network\-scripts/ifcfg\-eth0 ipaddr " \-i \-B2" salt \(aq*\(aq file.grep "/etc/sysconfig/network\-scripts/*" ipaddr " \-i \-l" .ft P .fi .UNINDENT .UNINDENT .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: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq file.group_to_gid root .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.file.is_blkdev(name) Check if a file exists and is a block device. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq file.is_blkdev /dev/blk .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.file.is_chrdev(name) Check if a file exists and is a character device. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq file.is_chrdev /dev/chr .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.file.is_fifo(name) Check if a file exists and is a FIFO. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq file.is_fifo /dev/fifo .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.file.lchown(path, user, group) Chown a file, pass the file the desired user and group without following symlinks. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq file.chown /etc/passwd root root .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.file.link(src, path) Create a hard link to a file .sp New in version 2014.1.0: (Hydrogen) .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq file.link /path/to/file /path/to/link .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.file.list_backups(path, limit=None) Lists the previous versions of a file backed up using Salt\(aqs \fBfile state backup\fP system. .sp New in version 0.17.0. .INDENT 7.0 .TP .B path The path on the minion to check for backups .TP .B limit Limit the number of results to the most recent N backups .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq file.list_backups /foo/bar/baz.txt .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.file.lstat(path) Returns the lstat attributes for the given file or dir. Does not support symbolic links. .sp CLI Example: .sp New in version 2014.1.0: (Hydrogen) .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq file.lstat /path/to/file .ft P .fi .UNINDENT .UNINDENT .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: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq file.makedirs /opt/code .ft P .fi .UNINDENT .UNINDENT .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: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq file.makedirs_perms /opt/code .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.file.manage_file(name, sfn, ret, source, source_sum, user, group, mode, saltenv, backup, makedirs=False, template=None, show_diff=True, contents=None, dir_mode=None) Checks the destination against what was retrieved with get_managed and makes the appropriate modifications (if necessary). .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .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 .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.file.mkdir(dir_path, user=None, group=None, mode=None) Ensure that a directory is available. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq file.mkdir /opt/jetty/context .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.file.mknod(name, ntype, major=0, minor=0, user=None, group=None, mode=\(aq0600\(aq) .INDENT 7.0 .INDENT 3.5 Create a block device, character device, or fifo pipe. Identical to the gnu mknod. .sp CLI Examples: .UNINDENT .UNINDENT .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq file.mknod /dev/chr c 180 31 salt \(aq*\(aq file.mknod /dev/blk b 8 999 salt \(aq*\(aq file.nknod /dev/fifo p .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.file.mknod_blkdev(name, major, minor, user=None, group=None, mode=\(aq0660\(aq) Create a block device. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq file.mknod_blkdev /dev/blk 8 999 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.file.mknod_chrdev(name, major, minor, user=None, group=None, mode=\(aq0660\(aq) Create a character device. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq file.mknod_chrdev /dev/chr 180 31 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.file.mknod_fifo(name, user=None, group=None, mode=\(aq0660\(aq) Create a FIFO pipe. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq file.mknod_fifo /dev/fifo .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.file.patch(originalfile, patchfile, options=\(aq\(aq, dry_run=False) New in version 0.10.4. .sp Apply a patch to a file .sp Equivalent to: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C patch .ft P .fi .UNINDENT .UNINDENT .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: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq file.patch /opt/file.txt /tmp/file.txt.patch .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.file.psed(path, before, after, limit=\(aq\(aq, backup=\(aq.bak\(aq, flags=\(aqgMS\(aq, escape_all=False, multi=False) Deprecated since version 0.17.0: Use \fBreplace()\fP instead. .sp Make a simple edit to a file (pure Python version) .sp Equivalent to: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C sed "// s/// " .ft P .fi .UNINDENT .UNINDENT .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 flags \fBgMS\fP.INDENT 7.0 .TP .B Flags to modify the search. Valid values are: .INDENT 7.0 .IP \(bu 2 \fBg\fP: Replace all occurrences of the pattern, not just the first. .IP \(bu 2 \fBI\fP: Ignore case. .IP \(bu 2 \fBL\fP: Make \fB\ew\fP, \fB\eW\fP, \fB\eb\fP, \fB\eB\fP, \fB\es\fP and \fB\eS\fP dependent on the locale. .IP \(bu 2 \fBM\fP: Treat multiple lines as a single line. .IP \(bu 2 \fBS\fP: Make \fI\&.\fP match all characters, including newlines. .IP \(bu 2 \fBU\fP: Make \fB\ew\fP, \fB\eW\fP, \fB\eb\fP, \fB\eB\fP, \fB\ed\fP, \fB\eD\fP, \fB\es\fP and \fB\eS\fP dependent on Unicode. .IP \(bu 2 \fBX\fP: Verbose (whitespace is ignored). .UNINDENT .UNINDENT .TP .B multi: \fBFalse\fP If True, treat the entire file as a single line .UNINDENT .sp Forward slashes and single quotes will be escaped automatically in the \fBbefore\fP and \fBafter\fP patterns. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq file.sed /etc/httpd/httpd.conf \(aqLogLevel warn\(aq \(aqLogLevel info\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.file.readdir(path) Return a list containing the contents of a directory .sp New in version 2014.1.0: (Hydrogen) .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq file.readdir /path/to/dir/ .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.file.readlink(path) Return the path that a symlink points to .sp New in version 2014.1.0: (Hydrogen) .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq file.readlink /path/to/link .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.file.remove(path) Remove the named file .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq file.remove /tmp/foo .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.file.rename(src, dst) Rename a file or directory .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq file.rename /path/to/src /path/to/dst .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.file.replace(path, pattern, repl, count=0, flags=0, bufsize=1, backup=\(aq.bak\(aq, dry_run=False, search_only=False, show_changes=True) Replace occurances of a pattern in a file .sp New in version 0.17.0. .sp This is a pure Python implementation that wraps Python\(aqs \fI\%sub()\fP\&. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBpath\fP \-\- Filesystem path to the file to be edited .IP \(bu 2 \fBpattern\fP \-\- The PCRE search .IP \(bu 2 \fBrepl\fP \-\- The replacement text .IP \(bu 2 \fBcount\fP \-\- Maximum number of pattern occurrences to be replaced .IP \(bu 2 \fBflags\fP (\fIlist or int\fP) \-\- A list of flags defined in the \fI\%re module documentation\fP\&. Each list item should be a string that will correlate to the human\-friendly flag name. E.g., \fB[\(aqIGNORECASE\(aq, \(aqMULTILINE\(aq]\fP\&. Note: multiline searches must specify \fBfile\fP as the \fBbufsize\fP argument below. .IP \(bu 2 \fBbufsize\fP (\fIint or str\fP) \-\- How much of the file to buffer into memory at once. The default value \fB1\fP processes one line at a time. The special value \fBfile\fP may be specified which will read the entire file into memory before processing. Note: multiline searches must specify \fBfile\fP buffering. .IP \(bu 2 \fBbackup\fP \-\- The file extension to use for a backup of the file before editing. Set to \fBFalse\fP to skip making a backup. .IP \(bu 2 \fBdry_run\fP \-\- Don\(aqt make any edits to the file .IP \(bu 2 \fBsearch_only\fP \-\- Just search for the pattern; ignore the replacement; stop on the first match .IP \(bu 2 \fBshow_changes\fP \-\- Output a unified diff of the old file and the new file. If \fBFalse\fP return a boolean if any changes were made. Note: using this option will store two copies of the file in\-memory (the original version and the edited version) in order to generate the diff. .UNINDENT .TP .B Return type bool or str .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq file.replace /etc/httpd/httpd.conf \(aqLogLevel warn\(aq \(aqLogLevel info\(aq salt \(aq*\(aq file.replace /some/file \(aqbefore\(aq \(aqafter\(aq flags=\(aq[MULTILINE, IGNORECASE]\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.file.restore_backup(path, backup_id) Restore a previous version of a file that was backed up using Salt\(aqs \fBfile state backup\fP system. .sp New in version 0.17.0. .INDENT 7.0 .TP .B path The path on the minion to check for backups .TP .B backup_id The numeric id for the backup you wish to restore, as found using \fBfile.list_backups\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq file.restore_backup /foo/bar/baz.txt 0 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.file.restorecon(path, recursive=False) Reset the SELinux context on a given path .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq file.restorecon /home/user/.ssh/authorized_keys .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.file.rmdir(path) Remove the specified directory. Fails if a directory is not empty. .sp New in version 2014.1.0: (Hydrogen) .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq file.rmdir /tmp/foo/ .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.file.search(path, pattern, flags=0, bufsize=1) Search for occurances of a pattern in a file .sp New in version 0.17.0. .sp Params are identical to \fBreplace()\fP\&. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq file.search /etc/crontab \(aqmymaintenance.sh\(aq .ft P .fi .UNINDENT .UNINDENT .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, negate_match=False) Deprecated since version 0.17.0: Use \fBreplace()\fP instead. .sp Make a simple edit to a file .sp Equivalent to: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C sed "// s/// " .ft P .fi .UNINDENT .UNINDENT .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 .TP .B negate_match False Negate the search command (\fB!\fP) .sp New in version 0.17.0. .UNINDENT .sp Forward slashes and single quotes will be escaped automatically in the \fBbefore\fP and \fBafter\fP patterns. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq file.sed /etc/httpd/httpd.conf \(aqLogLevel warn\(aq \(aqLogLevel info\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.file.sed_contains(path, text, limit=\(aq\(aq, flags=\(aqg\(aq) Deprecated since version 0.17.0: Use \fBsearch()\fP instead. .sp Return True if the file at \fBpath\fP contains \fBtext\fP\&. Utilizes sed to perform the search (line\-wise search). .sp Note: the \fBp\fP flag will be added to any flags you pass in. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq file.contains /etc/crontab \(aqmymaintenance.sh\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.file.seek_read(path, size, offset) Seek to a position on a file and write to it .sp New in version 2014.1.0: (Hydrogen) .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq file.seek_read /path/to/file 4096 0 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.file.seek_write(path, data, offset) Seek to a position on a file and write to it .sp New in version 2014.1.0: (Hydrogen) .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq file.seek_write /path/to/file \(aqsome data\(aq 4096 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.file.set_mode(path, mode) Set the mode of a file .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq file.set_mode /etc/passwd 0644 .ft P .fi .UNINDENT .UNINDENT .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: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq file.set_selinux_context path .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.file.source_list(source, source_hash, saltenv) Check the source list and return the source to use .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq file.source_list salt://http/httpd.conf \(aq{hash_type: \(aqmd5\(aq, \(aqhsum\(aq: }\(aq base .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.file.stats(path, hash_type=\(aqmd5\(aq, follow_symlinks=True) Return a dict containing the stats for a given file .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq file.stats /etc/passwd .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.file.statvfs(path) Perform a statvfs call against the filesystem that the file resides on .sp New in version 2014.1.0: (Hydrogen) .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq file.statvfs /path/to/file .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.file.symlink(src, path) Create a symbolic link to a file .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq file.symlink /path/to/file /path/to/link .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.file.touch(name, atime=None, mtime=None) New in version 0.9.5. .sp Just like the \fBtouch\fP 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: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq file.touch /var/log/emptyfile .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.file.truncate(path, length) Seek to a position on a file and write to it .sp New in version 2014.1.0: (Hydrogen) .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq file.truncate /path/to/file 512 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.file.uid_to_user(uid) Convert a uid to a user name .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq file.uid_to_user 0 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.file.uncomment(path, regex, char=\(aq#\(aq, backup=\(aq.bak\(aq) Deprecated since version 0.17.0: Use \fBreplace()\fP instead. .sp 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 .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: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq file.uncomment /etc/hosts.deny \(aqALL: PARANOID\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.file.user_to_uid(user) Convert user name to a uid .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq file.user_to_uid root .ft P .fi .UNINDENT .UNINDENT .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: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq sysctl.assign net.inet.icmp.icmplim 50 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.freebsd_sysctl.get(name) Return a single sysctl parameter for this minion .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq sysctl.get hw.physmem .ft P .fi .UNINDENT .UNINDENT .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: .INDENT 7.0 .INDENT 3.5 .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 .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.freebsd_sysctl.show() Return a list of sysctl parameters for this minion .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq sysctl.show .ft P .fi .UNINDENT .UNINDENT .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: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq jail.fstab .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.freebsdjail.get_enabled() Return which jails are set to be run .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq jail.get_enabled .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.freebsdjail.is_enabled() See if jail service is actually enabled on boot .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq jail.is_enabled .ft P .fi .UNINDENT .UNINDENT .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: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq jail.restart [] .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.freebsdjail.show_config(jail) Display specified jail\(aqs configuration .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq jail.show_config .ft P .fi .UNINDENT .UNINDENT .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: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq jail.start [] .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.freebsdjail.status(jail) See if specified jail is currently running .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq jail.status .ft P .fi .UNINDENT .UNINDENT .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: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq jail.stop [] .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.freebsdjail.sysctl() Dump all jail related kernel states (sysctl) .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq jail.sysctl .ft P .fi .UNINDENT .UNINDENT .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: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq kmod.available .ft P .fi .UNINDENT .UNINDENT .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: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq kmod.check_available kvm .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.freebsdkmod.load(mod) Load the specified kernel module .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq kmod.load kvm .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.freebsdkmod.lsmod() Return a dict containing information about currently loaded modules .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq kmod.lsmod .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.freebsdkmod.remove(mod) Remove the specified kernel module .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq kmod.remove kvm .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.freebsdpkg .sp Remote package support using \fBpkg_add(1)\fP .sp \fBWARNING:\fP .INDENT 0.0 .INDENT 3.5 This module has been completely rewritten. Up to and including version 0.17.0, it supported \fBpkg_add(1)\fP, but checked for the existence of a pkgng local database and, if found, would provide some of pkgng\(aqs functionality. The rewrite of this module has removed all pkgng support, and moved it to the \fBpkgng\fP execution module. For verisions <= 0.17.0, the documentation here should not be considered accurate. If your Minion is running one of these versions, then the documentation for this module can be viewed using the \fBsys.doc\fP function: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt bsdminion sys.doc pkg .ft P .fi .UNINDENT .UNINDENT .UNINDENT .UNINDENT .sp This module acts as the default package provider for FreeBSD 9 and older. If you need to use pkgng on a FreeBSD 9 system, you will need to override the \fBpkg\fP provider by setting the \fBproviders\fP parameter in your Minion config file, in order to use pkgng. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C providers: pkg: pkgng .ft P .fi .UNINDENT .UNINDENT .sp More information on pkgng support can be found in the documentation for the \fBpkgng\fP module. .sp This module will respect the \fBPACKAGEROOT\fP and \fBPACKAGESITE\fP environment variables, if set, but these values can also be overridden in several ways: .INDENT 0.0 .IP 1. 3 \fBSalt configuration parameters.\fP The configuration parameters \fBfreebsdpkg.PACKAGEROOT\fP and \fBfreebsdpkg.PACKAGESITE\fP are recognized. These config parameters are looked up using \fBconfig.get\fP and can thus be specified in the Master config file, Grains, Pillar, or in the Minion config file. Example: .INDENT 3.0 .INDENT 3.5 .sp .nf .ft C freebsdpkg.PACKAGEROOT: ftp://ftp.freebsd.org/ freebsdpkg.PACKAGESITE: ftp://ftp.freebsd.org/pub/FreeBSD/ports/ia64/packages\-9\-stable/Latest/ .ft P .fi .UNINDENT .UNINDENT .IP 2. 3 \fBCLI arguments.\fP Both the \fBpackageroot\fP (used interchangeably with \fBfromrepo\fP for API compatibility) and \fBpackagesite\fP CLI arguments are recognized, and override their config counterparts from section 1 above. .INDENT 3.0 .INDENT 3.5 .sp .nf .ft C salt \-G \(aqos:FreeBSD\(aq pkg.install zsh fromrepo=ftp://ftp2.freebsd.org/ salt \-G \(aqos:FreeBSD\(aq pkg.install zsh packageroot=ftp://ftp2.freebsd.org/ salt \-G \(aqos:FreeBSD\(aq pkg.install zsh packagesite=ftp://ftp2.freebsd.org/pub/FreeBSD/ports/ia64/packages\-9\-stable/Latest/ \&.. note:: These arguments can also be passed through in states: .. code\-block:: yaml zsh: pkg.installed: \- fromrepo: ftp://ftp2.freebsd.org/ .ft P .fi .UNINDENT .UNINDENT .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: .INDENT 7.0 .INDENT 3.5 .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 .UNINDENT .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: .INDENT 7.0 .INDENT 3.5 .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 .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.freebsdpkg.install(name=None, refresh=False, fromrepo=None, pkgs=None, sources=None, **kwargs) Install package(s) using \fBpkg_add(1)\fP .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 or packageroot Specify a package repository from which to install. Overrides the system default, as well as the PACKAGEROOT environment variable. .TP .B packagesite Specify the exact directory from which to install the remote package. Overrides the PACKAGESITE environment variable, if present. .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: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.install pkgs=\(aq["foo", "bar"]\(aq .ft P .fi .UNINDENT .UNINDENT .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: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.install sources=\(aq[{"foo": "salt://foo.deb"}, {"bar": "salt://bar.deb"}]\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .sp Return a dict containing the new package names and versions: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C {\(aq\(aq: {\(aqold\(aq: \(aq\(aq, \(aqnew\(aq: \(aq\(aq}} .ft P .fi .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.install .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.freebsdpkg.latest_version(*names, **kwargs) \fBpkg_add(1)\fP is not capable of querying for remote packages, so this function will always return results as if there is no package available for install or upgrade. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.latest_version salt \(aq*\(aq pkg.latest_version ... .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.freebsdpkg.list_pkgs(versions_as_list=False, with_origin=False, **kwargs) List the packages currently installed as a dict: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C {\(aq\(aq: \(aq\(aq} .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .TP .B with_origin False Return a nested dictionary containing both the origin name and version for each installed package. .sp New in version 2014.1.0: (Hydrogen) .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.list_pkgs .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.freebsdpkg.refresh_db() \fBpkg_add(1)\fP does not use a local database of available packages, so this function simply returns \fBTrue\fP\&. it exists merely for API compatibility. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.refresh_db .ft P .fi .UNINDENT .UNINDENT .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: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.rehash .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.freebsdpkg.remove(name=None, pkgs=None, **kwargs) Remove packages using \fBpkg_delete(1)\fP .INDENT 7.0 .TP .B name The name of the package to be deleted. .UNINDENT .sp Multiple Package Options: .INDENT 7.0 .TP .B pkgs A list of packages to delete. Must be passed as a python list. The \fBname\fP parameter will be ignored if this option is passed. .UNINDENT .sp New in version 0.16.0. .sp Returns a dict containing the changes. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.remove salt \(aq*\(aq pkg.remove ,, salt \(aq*\(aq pkg.remove pkgs=\(aq["foo", "bar"]\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.freebsdpkg.upgrade() Upgrades are not supported with \fBpkg_add(1)\fP\&. This function is included for API compatibility only and always returns an empty dict. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.upgrade .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.freebsdpkg.version(*names, **kwargs) 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. .INDENT 7.0 .TP .B with_origin False Return a nested dictionary containing both the origin name and version for each specified package. .sp New in version 2014.1.0: (Hydrogen) .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.version salt \(aq*\(aq pkg.version ... .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.freebsdports .sp Install software from the FreeBSD \fBports(7)\fP system .sp New in version 2014.1.0: (Hydrogen) .sp This module allows you to install ports using \fBBATCH=yes\fP to bypass configuration prompts. It is recommended to use the the \fBports state\fP to install ports, but it it also possible to use this module exclusively from the command line. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt minion\-id ports.config security/nmap IPV6=off salt minion\-id ports.install security/nmap .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.freebsdports.config(name, reset=False, **kwargs) Modify configuration options for a given port. Multiple options can be specified. To see the available options for a port, use \fBports.showconfig\fP\&. .INDENT 7.0 .TP .B name The port name, in \fBcategory/name\fP format .TP .B reset False If \fBTrue\fP, runs a \fBmake rmconfig\fP for the port, clearing its configuration before setting the desired options .UNINDENT .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq ports.config security/nmap IPV6=off .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.freebsdports.deinstall(name) De\-install a port. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq ports.deinstall security/nmap .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.freebsdports.install(name, clean=True) Install a port from the ports tree. Installs using \fBBATCH=yes\fP for non\-interactive building. To set config options for a given port, use \fBports.config\fP\&. .INDENT 7.0 .TP .B clean True If \fBTrue\fP, cleans after installation. Equivalent to running \fBmake install clean BATCH=yes\fP\&. .UNINDENT .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 It may be helpful to run this function using the \fB\-t\fP option to set a higher timeout, since compiling a port may cause the Salt command to exceed the default timeout. .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \-t 1200 \(aq*\(aq ports.install security/nmap .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.freebsdports.list_all() Lists all ports available. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq ports.list_all .ft P .fi .UNINDENT .UNINDENT .sp \fBWARNING:\fP .INDENT 7.0 .INDENT 3.5 Takes a while to run, and returns a \fBLOT\fP of output .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.freebsdports.rmconfig(name) Clear the cached options for the specified port; run a \fBmake rmconfig\fP .INDENT 7.0 .TP .B name The name of the port to clear .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq ports.rmconfig security/nmap .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.freebsdports.search(name) Search for matches in the ports tree. Globs are supported, and the category is optional .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq ports.search \(aqsecurity/*\(aq salt \(aq*\(aq ports.search \(aqsecurity/n*\(aq salt \(aq*\(aq ports.search nmap .ft P .fi .UNINDENT .UNINDENT .sp \fBWARNING:\fP .INDENT 7.0 .INDENT 3.5 Takes a while to run .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.freebsdports.showconfig(name, default=False, dict_return=False) Show the configuration options for a given port. .INDENT 7.0 .TP .B default False Show the default options for a port (not necessarily the same as the current configuration) .TP .B dict_return False Instead of returning the output of \fBmake showconfig\fP, return the data in an dictionary .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq ports.showconfig security/nmap salt \(aq*\(aq ports.showconfig security/nmap default=True .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.freebsdports.update(extract=False) Update the ports tree .INDENT 7.0 .TP .B extract False If \fBTrue\fP, runs a \fBportsnap extract\fP after fetching, should be used for first\-time installation of the ports tree. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq ports.update .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.freebsdservice .sp The service module for FreeBSD .INDENT 0.0 .TP .B salt.modules.freebsdservice.available(name) Check that the given service is available. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq service.available sshd .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.freebsdservice.disable(name, **kwargs) Disable the named service to start at boot .sp Arguments the same as for enable() .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq service.disable .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.freebsdservice.disabled(name) Return True if the named service is enabled, false otherwise .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq service.disabled .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.freebsdservice.enable(name, **kwargs) Enable the named service to start at boot .INDENT 7.0 .TP .B name service name .TP .B config /etc/rc.conf Config file for managing service. If config value is empty string, then /etc/rc.conf.d/ used. See man rc.conf(5) for details. .sp Also service.config variable can be used to change default. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq service.enable .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.freebsdservice.enabled(name) Return True if the named service is enabled, false otherwise .INDENT 7.0 .TP .B name Service name .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq service.enabled .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.freebsdservice.get_all() Return a list of all available services .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq service.get_all .ft P .fi .UNINDENT .UNINDENT .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: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq service.get_disabled .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.freebsdservice.get_enabled() Return what services are set to run on boot .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq service.get_enabled .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.freebsdservice.missing(name) The inverse of service.available. Returns \fBTrue\fP if the specified service is not available, otherwise returns \fBFalse\fP\&. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq service.missing sshd .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.freebsdservice.reload_(name) Restart the named service .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq service.reload .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.freebsdservice.restart(name) Restart the named service .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq service.restart .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.freebsdservice.start(name) Start the specified service .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq service.start .ft P .fi .UNINDENT .UNINDENT .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 .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq service.status .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.freebsdservice.stop(name) Stop the specified service .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq service.stop .ft P .fi .UNINDENT .UNINDENT .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: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq gem.install vagrant .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.gem.list_(prefix=\(aq\(aq, ruby=None, runas=None) List locally installed gems. .INDENT 7.0 .TP .B prefix : Only list gems when the name matches this prefix. .TP .B ruby None If RVM is installed, the ruby version and gemset to use. .TP .B runas None The user to run gem as. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq gem.list .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.gem.sources_add(source_uri, ruby=None, runas=None) Add a gem source. .INDENT 7.0 .TP .B source_uri The source URI to add. .TP .B ruby None If RVM is installed, the ruby version and gemset to use. .TP .B runas None The user to run gem as. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq gem.sources_add http://rubygems.org/ .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.gem.sources_list(ruby=None, runas=None) List the configured gem sources. .INDENT 7.0 .TP .B ruby None If RVM is installed, the ruby version and gemset to use. .TP .B runas None The user to run gem as. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq gem.sources_list .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.gem.sources_remove(source_uri, ruby=None, runas=None) Remove a gem source. .INDENT 7.0 .TP .B source_uri The source URI to remove. .TP .B ruby None If RVM is installed, the ruby version and gemset to use. .TP .B runas None The user to run gem as. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq gem.sources_remove http://rubygems.org/ .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.gem.uninstall(gems, ruby=None, runas=None) Uninstall one or several gems. .INDENT 7.0 .TP .B gems The gems to uninstall. .TP .B ruby None If RVM is installed, the ruby version and gemset to use. .TP .B runas None The user to run gem as. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq gem.uninstall vagrant .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.gem.update(gems, ruby=None, runas=None) Update one or several gems. .INDENT 7.0 .TP .B gems The gems to update. .TP .B ruby None If RVM is installed, the ruby version and gemset to use. .TP .B runas None The user to run gem as. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq gem.update vagrant .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.gem.update_system(version=\(aq\(aq, ruby=None, runas=None) Update rubygems. .INDENT 7.0 .TP .B version (newest) The version of rubygems to install. .TP .B ruby None If RVM is installed, the ruby version and gemset to use. .TP .B runas None The user to run gem as. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq gem.update_system .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.gentoo_service .sp Top level package command wrapper, used to translate the os detected by grains to the correct service manager .INDENT 0.0 .TP .B salt.modules.gentoo_service.available(name) Returns \fBTrue\fP if the specified service is available, otherwise returns \fBFalse\fP\&. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq service.available sshd .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.gentoo_service.disable(name, **kwargs) Disable the named service to start at boot .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq service.disable .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.gentoo_service.disabled(name) Return True if the named service is enabled, false otherwise .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq service.disabled .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.gentoo_service.enable(name, **kwargs) Enable the named service to start at boot .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq service.enable .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.gentoo_service.enabled(name) Return True if the named service is enabled, false otherwise .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq service.enabled .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.gentoo_service.get_all() Return all available boot services .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq service.get_all .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.gentoo_service.get_disabled() Return a set of services that are installed but disabled .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq service.get_disabled .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.gentoo_service.get_enabled() Return a list of service that are enabled on boot .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq service.get_enabled .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.gentoo_service.missing(name) The inverse of service.available. Returns \fBTrue\fP if the specified service is not available, otherwise returns \fBFalse\fP\&. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq service.missing sshd .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.gentoo_service.restart(name) Restart the named service .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq service.restart .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.gentoo_service.start(name) Start the specified service .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq service.start .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.gentoo_service.status(name, sig=None) Return the status for a service, returns the PID or an empty string if the service is running or not, pass a signature to use to find the service via ps .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq service.status [service signature] .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.gentoo_service.stop(name) Stop the specified service .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq service.stop .ft P .fi .UNINDENT .UNINDENT .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