.\" Man page generated from reStructuredText. . .TH "SALT" "7" "Feb 01, 2017" "2016.11.2" "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 INSTALLATION .sp This section contains instructions to install Salt. If you are setting up your environment for the first time, you should install a Salt master on a dedicated management server or VM, and then install a Salt minion on each system that you want to manage using Salt. For now you don\(aqt need to worry about your architecture, you can easily add components and modify your configuration later without needing to reinstall anything. .sp The general installation process is as follows: .INDENT 0.0 .IP 1. 3 Install a Salt master using the instructions for your platform or by running the Salt bootstrap script. If you use the bootstrap script, be sure to include the \fB\-M\fP option to install the Salt master. .IP 2. 3 Make sure that your Salt minions can find the Salt master\&. .IP 3. 3 Install the Salt minion on each system that you want to manage. .IP 4. 3 Accept the Salt minion keys after the Salt minion connects. .UNINDENT .sp After this, you should be able to run a simple command and receive returns from all connected Salt minions. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq test.ping .ft P .fi .UNINDENT .UNINDENT .SS Quick Install .sp On most distributions, you can set up a \fBSalt Minion\fP with the Salt bootstrap\&. .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 (stable) is currently available via the Arch Linux Official repositories. There are currently \-git packages available in the Arch User repositories (AUR) as well. .SS Stable Release .sp Install Salt stable releases from the Arch Linux Official repositories as follows: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C pacman \-S salt .ft P .fi .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 \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\-git .ft P .fi .UNINDENT .UNINDENT .UNINDENT .UNINDENT .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 Configuring Salt page. .SS Debian GNU/Linux / Raspbian .sp Debian GNU/Linux distribution and some derivatives such as Raspbian already have included Salt packages to their repositories. However, current stable release codenamed "Jessie" contains old outdated Salt release. It is recommended to use SaltStack repository for Debian as described \fI\%below\fP\&. .sp Installation from official Debian and Raspbian repositories is described \fI\%here\fP\&. .SS Installation from the Official SaltStack Repository .sp Packages for Debian 8 (Jessie) and Debian 7 (Wheezy) are available in the Official SaltStack repository. .sp Instructions are at \fI\%https://repo.saltstack.com/#debian\fP\&. .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 Regular security support for Debian 7 ended on April 25th 2016. As a result, 2016.3.1 and 2015.8.10 will be the last Salt releases for which Debian 7 packages are created. .UNINDENT .UNINDENT .SS Installation from the Debian / Raspbian Official Repository .sp Stretch (Testing) and Sid (Unstable) distributions are already contain mostly up\-to\-date Salt packages built by Debian Salt Team. You can install Salt components directly from Debian. .sp On Jessie (Stable) there is an option to install Salt minion from Stretch with \fIpython\-tornado\fP dependency from \fIjessie\-backports\fP repositories. .sp To install fresh release of Salt minion on Jessie: .INDENT 0.0 .IP 1. 3 Add \fIjessie\-backports\fP and \fIstretch\fP repositories: .sp \fBDebian\fP: .INDENT 3.0 .INDENT 3.5 .sp .nf .ft C echo \(aqdeb http://httpredir.debian.org/debian jessie\-backports main\(aq >> /etc/apt/sources.list echo \(aqdeb http://httpredir.debian.org/debian stretch main\(aq >> /etc/apt/sources.list .ft P .fi .UNINDENT .UNINDENT .sp \fBRaspbian\fP: .INDENT 3.0 .INDENT 3.5 .sp .nf .ft C echo \(aqdeb http://archive.raspbian.org/raspbian/ stretch main\(aq >> /etc/apt/sources.list .ft P .fi .UNINDENT .UNINDENT .IP 2. 3 Make Jessie a default release: .INDENT 3.0 .INDENT 3.5 .sp .nf .ft C echo \(aqAPT::Default\-Release "jessie";\(aq > /etc/apt/apt.conf.d/10apt .ft P .fi .UNINDENT .UNINDENT .IP 3. 3 Install Salt dependencies: .sp \fBDebian\fP: .INDENT 3.0 .INDENT 3.5 .sp .nf .ft C apt\-get update apt\-get install python\-zmq python\-tornado/jessie\-backports salt\-common/stretch .ft P .fi .UNINDENT .UNINDENT .sp \fBRaspbian\fP: .INDENT 3.0 .INDENT 3.5 .sp .nf .ft C apt\-get update apt\-get install python\-zmq python\-tornado/stretch salt\-common/stretch .ft P .fi .UNINDENT .UNINDENT .IP 4. 3 Install Salt minion package from Stretch: .INDENT 3.0 .INDENT 3.5 .sp .nf .ft C apt\-get install salt\-minion/stretch .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS Install Packages .sp Install the Salt master, minion or other packages from the repository with the \fIapt\-get\fP command. These examples each install one of Salt components, but more than one package name may be given at a time: .INDENT 0.0 .IP \(bu 2 \fBapt\-get install salt\-api\fP .IP \(bu 2 \fBapt\-get install salt\-cloud\fP .IP \(bu 2 \fBapt\-get install salt\-master\fP .IP \(bu 2 \fBapt\-get install salt\-minion\fP .IP \(bu 2 \fBapt\-get install salt\-ssh\fP .IP \(bu 2 \fBapt\-get install salt\-syndic\fP .UNINDENT .SS Post\-installation tasks .sp Now, go to the Configuring Salt page. .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 \fByum\fP or \fBdnf\fP, depending on your version of Fedora. .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 Released versions of Salt starting with \fB2015.5.2\fP through \fB2016.3.2\fP do not have Fedora packages available though \fI\%EPEL\fP\&. To install a version of Salt within this release array, please use SaltStack\(aqs \fI\%Bootstrap Script\fP and use the git method of installing Salt using the version\(aqs associated release tag. .sp Release \fB2016.3.3\fP and onward will have packaged versions available via \fI\%EPEL\fP\&. .UNINDENT .UNINDENT .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 Installing from \fBupdates\-testing\fP .sp When a new Salt release is packaged, it is first admitted into the \fBupdates\-testing\fP repository, before being moved to the stable repo. .sp To install from \fBupdates\-testing\fP, use the \fBenablerepo\fP argument for yum: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C yum \-\-enablerepo=updates\-testing install salt\-master yum \-\-enablerepo=updates\-testing install salt\-minion .ft P .fi .UNINDENT .UNINDENT .SS Installation Using pip .sp Since Salt is on \fI\%PyPI\fP, it can be installed using pip, though most users prefer to install using a package manager. .sp Installing from pip has a few additional requirements: .INDENT 0.0 .IP \(bu 2 Install the group \(aqDevelopment Tools\(aq, \fBdnf groupinstall \(aqDevelopment Tools\(aq\fP .IP \(bu 2 Install the \(aqzeromq\-devel\(aq package if it fails on linking against that afterwards as well. .UNINDENT .sp A pip install does not make the init scripts or the /etc/salt directory, and you will need to provide your own systemd service unit. .sp Installation from pip: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C pip install salt .ft P .fi .UNINDENT .UNINDENT .sp \fBWARNING:\fP .INDENT 0.0 .INDENT 3.5 If installing from pip (or from source using \fBsetup.py install\fP), be advised that the \fByum\-utils\fP package is needed for Salt to manage packages. Also, if the Python dependencies are not already installed, then you will need additional libraries/tools installed to build some of them. More information on this can be found here\&. .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 Configuring Salt page. .SS FreeBSD .SS Installation .sp Salt is available in binary package form from both the FreeBSD pkgng repository or directly from SaltStack. The instructions below outline installation via both methods: .SS FreeBSD repo .sp The FreeBSD pkgng repository is preconfigured on systems 10.x and above. No configuration is needed to pull from these repositories. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C pkg install py27\-salt .ft P .fi .UNINDENT .UNINDENT .sp These packages are usually available within a few days of upstream release. .SS SaltStack repo .sp SaltStack also hosts internal binary builds of the Salt package, available from \fI\%https://repo.saltstack.com/freebsd/\fP\&. To make use of this repository, add the following file to your system: .sp \fB/usr/local/etc/pkg/repos/saltstack.conf:\fP .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C saltstack: { url: "https://repo.saltstack.com/freebsd/${ABI}/", enabled: yes } .ft P .fi .UNINDENT .UNINDENT .sp You should now be able to install Salt from this new repository: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C pkg install py27\-salt .ft P .fi .UNINDENT .UNINDENT .sp These packages are usually available earlier than upstream FreeBSD. Also available are release candidates and development releases. Use these pre\-release packages with caution. .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: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C sysrc 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: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C sysrc salt_minion_enable="YES" .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 Configuring Salt 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 Configuring Salt page. .SS OpenBSD .sp Salt was added to the OpenBSD ports tree on Aug 10th 2013. It has been tested on OpenBSD 5.5 onwards. .sp Salt is dependent on the following additional ports. These will be installed as dependencies of the \fBsysutils/salt\fP port: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C devel/py\-futures devel/py\-progressbar net/py\-msgpack net/py\-zmq security/py\-crypto security/py\-M2Crypto textproc/py\-MarkupSafe textproc/py\-yaml www/py\-jinja2 www/py\-requests www/py\-tornado .ft P .fi .UNINDENT .UNINDENT .SS Installation .sp To install Salt from the OpenBSD pkg repo, use the command: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C pkg_add salt .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 rcctl enable salt_master .ft P .fi .UNINDENT .UNINDENT .sp To start the Master: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C rcctl start salt_master .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 rcctl enable salt_minion .ft P .fi .UNINDENT .UNINDENT .sp To start the Minion: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C rcctl start salt_minion .ft P .fi .UNINDENT .UNINDENT .sp Now go to the Configuring Salt page. .SS macOS .SS Installation from the Official SaltStack Repository .sp \fBLatest stable build from the selected branch\fP: .sp The output of \fBmd5 \fP should match the contents of the corresponding md5 file. .sp \fI\%Earlier builds from supported branches\fP .sp \fI\%Archived builds from unsupported branches\fP .SS Installation from Homebrew .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C brew install saltstack .ft P .fi .UNINDENT .UNINDENT .sp It should be noted that Homebrew explicitly discourages the \fI\%use of sudo\fP: .INDENT 0.0 .INDENT 3.5 Homebrew is designed to work without using sudo. You can decide to use it but we strongly recommend not to do so. If you have used sudo and run into a bug then it is likely to be the cause. Please don’t file a bug report unless you can reproduce it after reinstalling Homebrew from scratch without using sudo .UNINDENT .UNINDENT .SS Installation from MacPorts .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C sudo port install salt .ft P .fi .UNINDENT .UNINDENT .SS Installation from Pip .sp When only using the macOS system\(aqs pip, install this way: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C sudo pip install salt .ft P .fi .UNINDENT .UNINDENT .SS Salt\-Master Customizations .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 Salt master on macOS is not tested or supported by SaltStack. See \fI\%SaltStack Platform Support\fP for more information. .UNINDENT .UNINDENT .sp To run salt\-master on macOS, 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 On versions previous to macOS 10.10 (Yosemite), increase the root user maxfiles limit: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C sudo launchctl limit maxfiles 4096 8192 .ft P .fi .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 On macOS 10.10 (Yosemite) and higher, maxfiles should not be adjusted. The default limits are sufficient in all but the most extreme scenarios. Overriding these values with the setting below will cause system instability! .UNINDENT .UNINDENT .sp Now the salt\-master should run without errors: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C sudo salt\-master \-\-log\-level=all .ft P .fi .UNINDENT .UNINDENT .SS Post\-installation tasks .sp Now go to the Configuring Salt page. .SS RHEL / CentOS / Scientific Linux / Amazon Linux / Oracle Linux .sp Salt should work properly with all mainstream derivatives of Red Hat Enterprise Linux, including CentOS, Scientific Linux, Oracle Linux, and Amazon Linux. Report any bugs or issues on the \fI\%issue tracker\fP\&. .SS Installation from the Official SaltStack Repository .sp Packages for Redhat, CentOS, and Amazon Linux are available in the SaltStack Repository. .INDENT 0.0 .IP \(bu 2 \fI\%Red Hat / CentOS\fP .IP \(bu 2 \fI\%Amazon Linux\fP .UNINDENT .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 As of 2015.8.0, EPEL repository is no longer required for installing on RHEL systems. SaltStack repository provides all needed dependencies. .UNINDENT .UNINDENT .sp \fBWARNING:\fP .INDENT 0.0 .INDENT 3.5 If installing on Red Hat Enterprise Linux 7 with disabled (not subscribed on) \(aqRHEL Server Releases\(aq or \(aqRHEL Server Optional Channel\(aq repositories, append CentOS 7 GPG key URL to SaltStack yum repository configuration to install required base packages: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C [saltstack\-repo] name=SaltStack repo for Red Hat Enterprise Linux $releasever baseurl=https://repo.saltstack.com/yum/redhat/$releasever/$basearch/latest enabled=1 gpgcheck=1 gpgkey=https://repo.saltstack.com/yum/redhat/$releasever/$basearch/latest/SALTSTACK\-GPG\-KEY.pub https://repo.saltstack.com/yum/redhat/$releasever/$basearch/latest/base/RPM\-GPG\-KEY\-CentOS\-7 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 \fBsystemd\fP and \fBsystemd\-python\fP are required by Salt, but are not installed by the Red Hat 7 \fB@base\fP installation or by the Salt installation. These dependencies might need to be installed before Salt. .UNINDENT .UNINDENT .SS Installation from the Community\-Maintained Repository .sp Beginning with version 0.9.4, Salt has been available in \fI\%EPEL\fP\&. For RHEL/CentOS 5, \fI\%Fedora COPR\fP is a single community repository that provides Salt packages due to the removal from EPEL5. .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 Packages in these repositories are built by community, and it can take a little while until the latest stable SaltStack release become available. .UNINDENT .UNINDENT .SS RHEL/CentOS 6 and 7, Scientific Linux, etc. .sp \fBWARNING:\fP .INDENT 0.0 .INDENT 3.5 Salt 2015.8 is currently not available in EPEL due to unsatisfied dependencies: \fBpython\-crypto\fP 2.6.1 or higher, and \fBpython\-tornado\fP version 4.2.1 or higher. These packages are not currently available in EPEL for Red Hat Enterprise Linux 6 and 7. .UNINDENT .UNINDENT .SS Enabling EPEL .sp If the EPEL repository is not installed on your system, you can download the RPM for \fI\%RHEL/CentOS 6\fP or for \fI\%RHEL/CentOS 7\fP and install it using the following command: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C rpm \-Uvh epel\-release\-X\-Y.rpm .ft P .fi .UNINDENT .UNINDENT .sp Replace \fBepel\-release\-X\-Y.rpm\fP with the appropriate filename. .SS Installing Stable Release .sp Salt is packaged separately for the minion and the master. It is necessary to install only 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 .INDENT 0.0 .IP \(bu 2 \fByum install salt\-master\fP .IP \(bu 2 \fByum install salt\-minion\fP .IP \(bu 2 \fByum install salt\-ssh\fP .IP \(bu 2 \fByum install salt\-syndic\fP .IP \(bu 2 \fByum install salt\-cloud\fP .UNINDENT .UNINDENT .UNINDENT .SS Installing from \fBepel\-testing\fP .sp When a new Salt release is packaged, it is first admitted into the \fBepel\-testing\fP repository, before being moved to the stable EPEL repository. .sp To install from \fBepel\-testing\fP, use the \fBenablerepo\fP argument for \fByum\fP: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C yum \-\-enablerepo=epel\-testing install salt\-minion .ft P .fi .UNINDENT .UNINDENT .SS Installation Using pip .sp Since Salt is on \fI\%PyPI\fP, it can be installed using pip, though most users prefer to install using RPM packages (which can be installed from \fI\%EPEL\fP). .sp Installing from pip has a few additional requirements: .INDENT 0.0 .IP \(bu 2 Install the group \(aqDevelopment Tools\(aq, \fByum groupinstall \(aqDevelopment Tools\(aq\fP .IP \(bu 2 Install the \(aqzeromq\-devel\(aq package if it fails on linking against that afterwards as well. .UNINDENT .sp A pip install does not make the init scripts or the /etc/salt directory, and you will need to provide your own systemd service unit. .sp Installation from pip: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C pip install salt .ft P .fi .UNINDENT .UNINDENT .sp \fBWARNING:\fP .INDENT 0.0 .INDENT 3.5 If installing from pip (or from source using \fBsetup.py install\fP), be advised that the \fByum\-utils\fP package is needed for Salt to manage packages. Also, if the Python dependencies are not already installed, then you will need additional libraries/tools installed to build some of them. More information on this can be found here\&. .UNINDENT .UNINDENT .SS ZeroMQ 4 .sp We recommend using ZeroMQ 4 where available. SaltStack provides ZeroMQ 4.0.5 and pyzmq 14.5.0 in the \fI\%SaltStack Repository\fP as well as a separate \fI\%zeromq4 COPR\fP repository. .sp If this repository is added \fIbefore\fP Salt is installed, then installing either \fBsalt\-master\fP or \fBsalt\-minion\fP will automatically pull in ZeroMQ 4.0.5, and additional steps to upgrade ZeroMQ and pyzmq are unnecessary. .sp \fBWARNING:\fP .INDENT 0.0 .INDENT 3.5 RHEL/CentOS 5 Users Using COPR repos on RHEL/CentOS 5 requires that the \fBpython\-hashlib\fP package be installed. Not having it present will result in checksum errors because YUM will not be able to process the SHA256 checksums used by COPR. .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 For RHEL/CentOS 5 installations, if using the SaltStack repo or Fedora COPR to install Salt (as described \fI\%above\fP), then it is not necessary to enable the \fI\%zeromq4 COPR\fP, because those repositories already include ZeroMQ 4. .UNINDENT .UNINDENT .SS Package Management .sp Salt\(aqs interface to \fByum\fP makes heavy use of the \fBrepoquery\fP utility, from the \fI\%yum\-utils\fP package. This package will be installed as a dependency if salt is installed via EPEL. However, if salt has been installed using pip, or a host is being managed using salt\-ssh, then as of version 2014.7.0 \fI\%yum\-utils\fP will be installed automatically to satisfy this dependency. .SS Post\-installation tasks .SS Master .sp To have the Master start automatically at boot time: .sp \fBRHEL/CentOS 5 and 6\fP .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C chkconfig salt\-master on .ft P .fi .UNINDENT .UNINDENT .sp \fBRHEL/CentOS 7\fP .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: .sp \fBRHEL/CentOS 5 and 6\fP .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C service salt\-master start .ft P .fi .UNINDENT .UNINDENT .sp \fBRHEL/CentOS 7\fP .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C systemctl start salt\-master.service .ft P .fi .UNINDENT .UNINDENT .SS Minion .sp To have the Minion start automatically at boot time: .sp \fBRHEL/CentOS 5 and 6\fP .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C chkconfig salt\-minion on .ft P .fi .UNINDENT .UNINDENT .sp \fBRHEL/CentOS 7\fP .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: .sp \fBRHEL/CentOS 5 and 6\fP .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C service salt\-minion start .ft P .fi .UNINDENT .UNINDENT .sp \fBRHEL/CentOS 7\fP .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 Configuring Salt 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 .IP \(bu 2 py_yaml .IP \(bu 2 py_pyzmq .IP \(bu 2 py_jinja2 .IP \(bu 2 py_msgpack_python .IP \(bu 2 py_m2crypto .IP \(bu 2 py_crypto .IP \(bu 2 python .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 .SS Installation from the Official SaltStack Repository .sp Packages for Ubuntu 16 (Xenial), Ubuntu 14 (Trusty), and Ubuntu 12 (Precise) are available in the SaltStack repository. .sp Instructions are at \fI\%https://repo.saltstack.com/#ubuntu\fP\&. .SS Install Packages .sp Install the Salt master, minion or other packages from the repository with the \fIapt\-get\fP command. These examples each install one of Salt components, but more than one package name may be given at a time: .INDENT 0.0 .IP \(bu 2 \fBapt\-get install salt\-api\fP .IP \(bu 2 \fBapt\-get install salt\-cloud\fP .IP \(bu 2 \fBapt\-get install salt\-master\fP .IP \(bu 2 \fBapt\-get install salt\-minion\fP .IP \(bu 2 \fBapt\-get install salt\-ssh\fP .IP \(bu 2 \fBapt\-get install salt\-syndic\fP .UNINDENT .SS Post\-installation tasks .sp Now go to the Configuring Salt page. .SS Windows .sp Salt has full support for running the Salt minion on Windows. You must connect Windows Salt minions to a Salt master on a supported operating system to control your Salt Minions. .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 Installation from the Official SaltStack Repository .sp \fBLatest stable build from the selected branch\fP: .sp The output of \fBmd5sum \fP should match the contents of the corresponding md5 file. .sp \fI\%Earlier builds from supported branches\fP .sp \fI\%Archived builds from unsupported branches\fP .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 The installation executable installs 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 2008 Server 32bit. Please file a bug report on our GitHub repo if issues for other platforms are found. .sp The installer will detect previous installations of Salt and ask if you would like to remove them. Clicking OK will remove the Salt binaries and related files but leave any existing config, cache, and PKI information. .sp The installer asks for two additional bits of information to configure the minion; the master hostname and the minion name. The installer will update the minion config with these options. .sp The final page allows you to select which services to start. .sp The \fBsalt\-minion\fP service will appear in the Windows Service Manager and can be started and stopped there or with the command line program \fBsc\fP like any other Windows service. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C sc start salt\-minion net start salt\-minion .ft P .fi .UNINDENT .UNINDENT .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 Installation Prerequisites .sp Most Salt functionality should work just fine right out of the box. A few Salt modules rely on PowerShell. The minimum version of PowerShell required for Salt is version 3. If you intend to work with DSC then Powershell version 5 is the minimum. .SS Silent Installer Options .sp The installer can be run silently by providing the \fB/S\fP option at the command line. The installer also accepts the following options for configuring the Salt Minion silently: .INDENT 0.0 .IP \(bu 2 \fI/master=\fP A string value to set the IP address or host name of the master. Default value is \(aqsalt\(aq .IP \(bu 2 \fI/minion\-name=\fP A string value to set the minion name. Default is \(aqhostname\(aq .IP \(bu 2 \fI/start\-minion=\fP Either a 1 or 0. \(aq1\(aq will start the salt\-minion service, \(aq0\(aq will not. Default is to start the service after installation. .UNINDENT .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 \fI/start\-service\fP has been deprecated but will continue to function as expected for the time being. .UNINDENT .UNINDENT .sp Here are some examples of using the silent installer: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C # Will install the minion and start the service *\-Setup\-*.exe /S /master=yoursaltmaster /minion\-name=yourminionname .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C # Will install the minion but will NOT start the salt\-minion service *\-Setup\-*.exe /S /master=yoursaltmaster /minion\-name=yourminionname /start\-minion=0 .ft P .fi .UNINDENT .UNINDENT .SS Running the Salt Minion on Windows as an Unprivileged User .sp Notes: .INDENT 0.0 .IP \(bu 2 These instructions were tested with Windows Server 2008 R2 .IP \(bu 2 They are generalizable to any version of Windows that supports a salt\-minion .UNINDENT .SS Create the Unprivileged User that the Salt Minion will Run As .INDENT 0.0 .IP 1. 4 Click \fBStart\fP > \fBControl Panel\fP > \fBUser Accounts\fP\&. .IP 2. 4 Click \fBAdd or remove user accounts\fP\&. .IP 3. 4 Click \fBCreate new account\fP\&. .IP 4. 4 Enter \fBsalt\-user\fP (or a name of your preference) in the \fBNew account name\fP field. .IP 5. 4 Select the \fBStandard user\fP radio button. .IP 6. 4 Click the \fBCreate Account\fP button. .IP 7. 4 Click on the newly created user account. .IP 8. 4 Click the \fBCreate a password\fP link. .IP 9. 4 In the \fBNew password\fP and \fBConfirm new password\fP fields, provide a password (e.g "SuperSecretMinionPassword4Me!"). .IP 10. 4 In the \fBType a password hint\fP field, provide appropriate text (e.g. "My Salt Password"). .IP 11. 4 Click the \fBCreate password\fP button. .IP 12. 4 Close the \fBChange an Account\fP window. .UNINDENT .SS Add the New User to the Access Control List for the Salt Folder .INDENT 0.0 .IP 1. 3 In a File Explorer window, browse to the path where Salt is installed (the default path is \fBC:\eSalt\fP). .IP 2. 3 Right\-click on the \fBSalt\fP folder and select \fBProperties\fP\&. .IP 3. 3 Click on the \fBSecurity\fP tab. .IP 4. 3 Click the \fBEdit\fP button. .IP 5. 3 Click the \fBAdd\fP button. .IP 6. 3 Type the name of your designated Salt user and click the \fBOK\fP button. .IP 7. 3 Check the box to \fBAllow\fP the \fBModify\fP permission. .IP 8. 3 Click the \fBOK\fP button. .IP 9. 3 Click the \fBOK\fP button to close the \fBSalt Properties\fP window. .UNINDENT .SS Update the Windows Service User for the \fBsalt\-minion\fP Service .INDENT 0.0 .IP 1. 4 Click \fBStart\fP > \fBAdministrative Tools\fP > \fBServices\fP\&. .IP 2. 4 In the Services list, right\-click on \fBsalt\-minion\fP and select \fBProperties\fP\&. .IP 3. 4 Click the \fBLog On\fP tab. .IP 4. 4 Click the \fBThis account\fP radio button. .IP 5. 4 Provide the account credentials created in section A. .IP 6. 4 Click the \fBOK\fP button. .IP 7. 4 Click the \fBOK\fP button to the prompt confirming that the user \fBhas been granted the Log On As A Service right\fP\&. .IP 8. 4 Click the \fBOK\fP button to the prompt confirming that \fBThe new logon name will not take effect until you stop and restart the service\fP\&. .IP 9. 4 Right\-Click on \fBsalt\-minion\fP and select \fBStop\fP\&. .IP 10. 4 Right\-Click on \fBsalt\-minion\fP and select \fBStart\fP\&. .UNINDENT .SS Building and Developing on Windows .sp This document will explain how to set up a development environment for Salt on Windows. The development environment allows you to work with the source code to customize or fix bugs. It will also allow you to build your own installation. .sp There are several scripts to automate creating a Windows installer as well as setting up an environment that facilitates developing and troubleshooting Salt code. They are located in the \fBpkg\ewindows\fP directory in the Salt repo \fI\%(here)\fP\&. .SS Scripts: .TS center; |l|l|. _ T{ Script T} T{ Description T} _ T{ \fBbuild_env.ps1\fP T} T{ A PowerShell script that sets up the build environment T} _ T{ \fBbuild_pkg.bat\fP T} T{ A batch file that builds a Windows installer based on the contents of the \fBC:\ePython27\fP directory T} _ T{ \fBbuild.bat\fP T} T{ A batch file that fully automates the building of the Windows installer using the above two scripts T} _ .TE .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 The \fBbuild.bat\fP and \fBbuild_pkg.bat\fP scripts both accept a single parameter to specify the version of Salt that will be displayed in the Windows installer. If no version is passed, the version will be determined using git. .UNINDENT .UNINDENT .SS Prerequisite Software .sp The only prerequisite is \fI\%Git for Windows\fP\&. .SS Create a Build Environment .SS 1. Working Directory .sp Create a \fBSalt\-Dev\fP directory on the root of \fBC:\fP\&. This will be our working directory. Navigate to \fBSalt\-Dev\fP and clone the \fI\%Salt\fP repo from GitHub. .sp Open a command line and type: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C cd \e md Salt\-Dev cd Salt\-Dev git clone https://github.com/saltstack/salt .ft P .fi .UNINDENT .UNINDENT .sp Go into the \fBsalt\fP directory and checkout the version of salt to work with (2016.3 or higher). .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C cd salt git checkout 2016.3 .ft P .fi .UNINDENT .UNINDENT .SS 2. Setup the Python Environment .sp Navigate to the \fBpkg\ewindows\fP directory and execute the \fBbuild_env.ps1\fP PowerShell script. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C cd pkg\ewindows powershell \-file build_env.ps1 .ft P .fi .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 You can also do this from Explorer by navigating to the \fBpkg\ewindows\fP directory, right clicking the \fBbuild_env.ps1\fP powershell script and selecting \fBRun with PowerShell\fP .UNINDENT .UNINDENT .sp This will download and install Python with all the dependencies needed to develop and build Salt. .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 If you get an error or the script fails to run you may need to change the execution policy. Open a powershell window and type the following command: .UNINDENT .UNINDENT .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C Set\-ExecutionPolicy RemoteSigned .ft P .fi .UNINDENT .UNINDENT .SS 3. Salt in Editable Mode .sp Editable mode allows you to more easily modify and test the source code. For more information see the \fI\%Pip documentation\fP\&. .sp Navigate to the root of the \fBsalt\fP directory and install Salt in editable mode with \fBpip\fP .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C cd \eSalt\-Dev\esalt pip install \-e . .ft P .fi .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 The \fB\&.\fP is important .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 If \fBpip\fP is not recognized, you may need to restart your shell to get the updated path .UNINDENT .UNINDENT .SS 4. Setup Salt Configuration .sp Salt requires a minion configuration file and a few other directories. The default config file is named \fBminion\fP located in \fBC:\esalt\econf\fP\&. The easiest way to set this up is to copy the contents of the \fBsalt\epkg\ewindows\ebuildenv\fP directory to \fBC:\esalt\fP\&. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C cd \e md salt xcopy /s /e \eSalt\-Dev\esalt\epkg\ewindows\ebuildenv\e* \esalt\e .ft P .fi .UNINDENT .UNINDENT .sp Now go into the \fBC:\esalt\econf\fP directory and edit the file name \fBminion\fP (no extension). You need to configure the master and id parameters in this file. Edit the following lines: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C master: id: .ft P .fi .UNINDENT .UNINDENT .SS Create a Windows Installer .sp To create a Windows installer, follow steps 1 and 2 from \fI\%Create a Build Environment\fP above. Then proceed to 3 below: .SS 3. Install Salt .sp To create the installer for Window we install Salt using Python instead of pip. Navigate to the root \fBsalt\fP directory and install Salt. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C cd \eSalt\-Dev\esalt python setup.py install .ft P .fi .UNINDENT .UNINDENT .SS 4. Create the Windows Installer .sp Navigate to the \fBpkg\ewindows\fP directory and run the \fBbuild_pkg.bat\fP with the build version (2016.3) script. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C cd pkg\ewindows build_pkg.bat 2016.3 .ft P .fi .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 If no version is passed, the \fBbuild_pkg.bat\fP will guess the version number using git. .UNINDENT .UNINDENT .SS Creating a Windows Installer: Alternate Method (Easier) .sp Clone the \fI\%Salt\fP repo from GitHub into the directory of your choice. We\(aqre going to use \fBSalt\-Dev\fP\&. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C cd \e md Salt\-Dev cd Salt\-Dev git clone https://github.com/saltstack/salt .ft P .fi .UNINDENT .UNINDENT .sp Go into the \fBsalt\fP directory and checkout the version of Salt you want to build. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C cd salt git checkout 2016.3 .ft P .fi .UNINDENT .UNINDENT .sp Then navigate to \fBpkg\ewindows\fP and run the \fBbuild.bat\fP script with the version you\(aqre building. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C cd pkg\ewindows build.bat 2016.3 .ft P .fi .UNINDENT .UNINDENT .sp This will install everything needed to build a Windows installer for Salt. The binary will be in the \fBsalt\epkg\ewindows\einstaller\fP directory. .SS Testing the Salt minion .INDENT 0.0 .IP 1. 3 Create the directory \fBC:\esalt\fP (if it doesn\(aqt exist already) .IP 2. 3 .INDENT 3.0 .TP .B Copy the example \fBconf\fP and \fBvar\fP directories from \fBpkg\ewindows\ebuildenv\fP into \fBC:\esalt\fP .UNINDENT .IP 3. 3 Edit \fBC:\esalt\econf\eminion\fP .INDENT 3.0 .INDENT 3.5 .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C master: ipaddress or hostname of your salt\-master .ft P .fi .UNINDENT .UNINDENT .UNINDENT .UNINDENT .IP 4. 3 Start the salt\-minion .INDENT 3.0 .INDENT 3.5 .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C cd C:\ePython27\eScripts python salt\-minion \-l debug .ft P .fi .UNINDENT .UNINDENT .UNINDENT .UNINDENT .IP 5. 3 On the salt\-master accept the new minion\(aqs key .INDENT 3.0 .INDENT 3.5 .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C sudo salt\-key \-A .ft P .fi .UNINDENT .UNINDENT .sp This accepts all unaccepted keys. If you\(aqre concerned about security just accept the key for this specific minion. .UNINDENT .UNINDENT .IP 6. 3 Test that your minion is responding .INDENT 3.0 .INDENT 3.5 On the salt\-master run: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C sudo salt \(aq*\(aq test.ping .ft P .fi .UNINDENT .UNINDENT .UNINDENT .UNINDENT .UNINDENT .sp You should get the following response: \fB{\(aqyour minion hostname\(aq: True}\fP .SS Packages Management Under Windows 2003 .sp Windows Server 2003 and Windows XP have both reached End of Support. Though Salt is not officially supported on operating systems that are EoL, some functionality may continue to work. .sp On Windows Server 2003, you need to install optional component "WMI Windows Installer Provider" to get a full list of installed packages. If you don\(aqt have this, salt\-minion can\(aqt report some installed software. .SS SUSE .SS Installation from the Official SaltStack Repository .sp Packages for SUSE 12 SP1, SUSE 12, SUSE 11, openSUSE 13 and openSUSE Leap 42.1 are available in the SaltStack Repository. .sp Instructions are at \fI\%https://repo.saltstack.com/#suse\fP\&. .SS Installation from the SUSE Repository .sp Since openSUSE 13.2, Salt 2014.1.11 is available in the primary repositories. With the release of SUSE manager 3 a new repository setup has been created. The new repo will by systemsmanagement:saltstack, which is the source for newer stable packages. For backward compatibility a linkpackage will be created to the old devel:language:python repo. All development of suse packages will be done in systemsmanagement:saltstack:testing. This will ensure that salt will be in mainline suse repo\(aqs, a stable release repo and a testing repo for further enhancements. .SS Installation .sp Salt can be installed using \fBzypper\fP and is available in the standard openSUSE/SLES 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 Tumbleweed run the following as root: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C zypper addrepo http://download.opensuse.org/repositories/systemsmanagement:/saltstack/openSUSE_Tumbleweed/systemsmanagement:saltstack.repo zypper refresh zypper install salt salt\-minion salt\-master .ft P .fi .UNINDENT .UNINDENT .sp For openSUSE 42.1 Leap run the following as root: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C zypper addrepo http://download.opensuse.org/repositories/systemsmanagement:/saltstack/openSUSE_Leap_42.1/systemsmanagement:saltstack.repo zypper refresh zypper install salt salt\-minion salt\-master .ft P .fi .UNINDENT .UNINDENT .sp For openSUSE 13.2 run the following as root: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C zypper addrepo http://download.opensuse.org/repositories/systemsmanagement:/saltstack/openSUSE_13.2/systemsmanagement:saltstack.repo zypper refresh zypper install salt salt\-minion salt\-master .ft P .fi .UNINDENT .UNINDENT .SS SUSE Linux Enterprise .sp For SLE 12 run the following as root: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C zypper addrepo http://download.opensuse.org/repositories/systemsmanagement:/saltstack/SLE_12/systemsmanagement:saltstack.repo zypper refresh zypper install salt salt\-minion salt\-master .ft P .fi .UNINDENT .UNINDENT .sp For SLE 11 SP4 run the following as root: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C zypper addrepo http://download.opensuse.org/repositories/systemsmanagement:/saltstack/SLE_11_SP4/systemsmanagement:saltstack.repo zypper refresh zypper install salt salt\-minion salt\-master .ft P .fi .UNINDENT .UNINDENT .sp Now go to the Configuring Salt page. .SS Initial Configuration .SS Configuring Salt .sp Salt configuration is very simple. The default configuration for the master will work for most installations and the only requirement for setting up a minion is to set the location of the master in the minion configuration file. .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 master configuration reference 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 minion configuration reference 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 \fB\-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 \fB\-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 \fBlog 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 logging document\&. .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 .IP \(bu 2 /var/run/salt .UNINDENT .sp More information about running salt as a non\-privileged user can be found here\&. .UNINDENT .UNINDENT .sp There is also a full troubleshooting guide available. .SS Key Identity .sp Salt provides commands to validate the identity of your Salt master and Salt minions before the initial key exchange. Validating key identity helps avoid inadvertently connecting to the wrong Salt master, and helps prevent a potential MiTM attack when establishing the initial connection. .SS Master Key Fingerprint .sp Print the master key fingerprint by running the following command on the Salt master: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt\-key \-F master .ft P .fi .UNINDENT .UNINDENT .sp Copy the \fBmaster.pub\fP fingerprint from the \fILocal Keys\fP section, and then set this value as the \fBmaster_finger\fP in the minion configuration file. Save the configuration file and then restart the Salt minion. .SS Minion Key Fingerprint .sp Run the following command on each Salt minion to view the minion key fingerprint: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt\-call \-\-local key.finger .ft P .fi .UNINDENT .UNINDENT .sp Compare this value to the value that is displayed when you run the \fBsalt\-key \-\-finger \fP command on the Salt master. .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 salt\-key manpage .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 targeting is important. From there, depending on the way you wish to use Salt, you should also proceed to learn about Remote Execution and Configuration Management\&. .SS Additional Installation Guides .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 .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 Debian and derivatives .INDENT 0.0 .IP \(bu 2 Debian GNU/Linux 7/8 .IP \(bu 2 Linux Mint Debian Edition 1 (based on Debian 8) .IP \(bu 2 Kali Linux 1.0 (based on Debian 7) .UNINDENT .SS Red Hat family .INDENT 0.0 .IP \(bu 2 Amazon Linux 2012.09/2013.03/2013.09/2014.03/2014.09 .IP \(bu 2 CentOS 5/6/7 .IP \(bu 2 Fedora 17/18/20/21/22 .IP \(bu 2 Oracle Linux 5/6/7 .IP \(bu 2 Red Hat Enterprise Linux 5/6/7 .IP \(bu 2 Scientific Linux 5/6/7 .UNINDENT .SS SUSE family .INDENT 0.0 .IP \(bu 2 openSUSE 12/13 .IP \(bu 2 openSUSE Leap 42 .IP \(bu 2 openSUSE Tumbleweed 2015 .IP \(bu 2 SUSE Linux Enterprise Server 11 SP1/11 SP2/11 SP3/12 .UNINDENT .SS Ubuntu and derivatives .INDENT 0.0 .IP \(bu 2 Elementary OS 0.2 (based on Ubuntu 12.04) .IP \(bu 2 Linaro 12.04 .IP \(bu 2 Linux Mint 13/14/16/17 .IP \(bu 2 Trisquel GNU/Linux 6 (based on Ubuntu 12.04) .IP \(bu 2 Ubuntu 10.x/11.x/12.x/13.x/14.x/15.x/16.x .UNINDENT .SS Other Linux distro .INDENT 0.0 .IP \(bu 2 Arch Linux .IP \(bu 2 Gentoo .UNINDENT .SS UNIX systems .sp \fBBSD\fP: .INDENT 0.0 .IP \(bu 2 OpenBSD (\fBpip\fP installation) .IP \(bu 2 FreeBSD 9/10/11 .UNINDENT .sp \fBSunOS\fP: .INDENT 0.0 .IP \(bu 2 SmartOS .UNINDENT .SS Example Usage .sp If you\(aqre looking for the \fIone\-liner\fP to install Salt, please scroll to the bottom and use the instructions for \fI\%Installing via an Insecure One\-Liner\fP .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 In every two\-step example, you would be well\-served to examine the downloaded file and examine it to ensure that it does what you expect. .UNINDENT .UNINDENT .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 \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 These examples below show how to bootstrap Salt directly from GitHub or other Git repository. Run the script without any parameters to get latest stable Salt packages for your system from \fI\%SaltStack corporate repository\fP\&. See first example in the \fI\%Install using wget\fP section. .UNINDENT .UNINDENT .SS Install using curl .sp Using \fBcurl\fP to install latest development version from GitHub: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C curl \-o bootstrap\-salt.sh \-L https://bootstrap.saltstack.com sudo sh bootstrap\-salt.sh 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 \-o bootstrap\-salt.sh \-L https://bootstrap.saltstack.com sudo sh bootstrap\-salt.sh git v2015.8.8 .ft P .fi .UNINDENT .UNINDENT .sp To install a specific branch from a Git fork: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C curl \-o bootstrap\-salt.sh \-L https://bootstrap.saltstack.com sudo sh bootstrap\-salt.sh \-g https://github.com/myuser/salt.git git mybranch .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 \-o bootstrap\-salt.sh \-L https://bootstrap.saltstack.com sudo sh bootstrap\-salt.sh \-M \-N git develop .ft P .fi .UNINDENT .UNINDENT .sp If your host has Internet access only via HTTP proxy: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C PROXY=\(aqhttp://user:password@myproxy.example.com:3128\(aq curl \-o bootstrap\-salt.sh \-L \-x "$PROXY" https://bootstrap.saltstack.com sudo sh bootstrap\-salt.sh \-G \-H "$PROXY" git .ft P .fi .UNINDENT .UNINDENT .SS Install using wget .sp Using \fBwget\fP to install your distribution\(aqs stable packages: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C wget \-O bootstrap\-salt.sh https://bootstrap.saltstack.com sudo sh bootstrap\-salt.sh .ft P .fi .UNINDENT .UNINDENT .sp Downloading the script from develop branch: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C wget \-O bootstrap\-salt.sh https://bootstrap.saltstack.com/develop sudo sh bootstrap\-salt.sh .ft P .fi .UNINDENT .UNINDENT .sp Installing a specific version from git using \fBwget\fP: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C wget \-O bootstrap\-salt.sh https://bootstrap.saltstack.com sudo sh bootstrap\-salt.sh \-P git v2015.8.8 .ft P .fi .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 On the above example we added \fI\-P\fP which will allow PIP packages to be installed if required but it\(aqs not a necessary flag for Git based bootstraps. .UNINDENT .UNINDENT .SS Install using Python .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 "https://bootstrap.saltstack.com" > bootstrap\-salt.sh sudo sh bootstrap\-salt.sh git develop .ft P .fi .UNINDENT .UNINDENT .sp All Python versions should support the following in\-line code: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C python \-c \(aqimport urllib; print urllib.urlopen("https://bootstrap.saltstack.com").read()\(aq > bootstrap\-salt.sh sudo sh bootstrap\-salt.sh git develop .ft P .fi .UNINDENT .UNINDENT .SS Install using fetch .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 bootstrap\-salt.sh https://bootstrap.saltstack.com sudo sh bootstrap\-salt.sh .ft P .fi .UNINDENT .UNINDENT .sp If you have any SSL issues install \fBca_root_nssp\fP: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C pkg install ca_root_nssp .ft P .fi .UNINDENT .UNINDENT .sp And either copy the certificates to the place where fetch can find them: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C cp /usr/local/share/certs/ca\-root\-nss.crt /etc/ssl/cert.pem .ft P .fi .UNINDENT .UNINDENT .sp Or link them to the right place: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C ln \-s /usr/local/share/certs/ca\-root\-nss.crt /etc/ssl/cert.pem .ft P .fi .UNINDENT .UNINDENT .SS Installing via an Insecure One\-Liner .sp The following examples illustrate how to install Salt via a one\-liner. .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 Warning! These methods do not involve a verification step and assume that the delivered file is trustworthy. .UNINDENT .UNINDENT .sp Any of the example above which use two\-lines can be made to run in a single\-line configuration with minor modifications. .sp For example, using \fBcurl\fP to install your distribution\(aqs stable packages: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C curl \-L https://bootstrap.saltstack.com | sudo sh .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 \- https://bootstrap.saltstack.com | sudo sh .ft P .fi .UNINDENT .UNINDENT .sp Installing the latest develop branch of Salt: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C curl \-L https://bootstrap.saltstack.com | sudo sh \-s \-\- git develop .ft P .fi .UNINDENT .UNINDENT .SS Command Line Options .sp Here\(aqs a summary of the command line options: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C $ sh bootstrap\-salt.sh \-h Usage : bootstrap\-salt.sh [options] Installation types: \- stable (default) \- stable [version] (ubuntu specific) \- daily (ubuntu specific) \- testing (redhat specific) \- git Examples: \- bootstrap\-salt.sh \- bootstrap\-salt.sh stable \- bootstrap\-salt.sh stable 2014.7 \- bootstrap\-salt.sh daily \- bootstrap\-salt.sh testing \- bootstrap\-salt.sh git \- bootstrap\-salt.sh git develop \- bootstrap\-salt.sh git v0.17.0 \- bootstrap\-salt.sh git 8c3fadf15ec183e5ce8c63739850d543617e4357 Options: \-h Display this message \-v Display script version \-n No colours. \-D Show debug output. \-c Temporary configuration directory \-g Salt repository URL. (default: git://github.com/saltstack/salt.git) \-G Instead of cloning from git://github.com/saltstack/salt.git, clone from https://github.com/saltstack/salt.git (Usually necessary on systems which have the regular git protocol port blocked, where https usually is not) \-k Temporary directory holding the minion keys which will pre\-seed the master. \-s Sleep time used when waiting for daemons to start, restart and when checking for the services running. Default: 3 \-M Also install salt\-master \-S Also install salt\-syndic \-N Do not install salt\-minion \-X Do not start daemons after installation \-C Only run the configuration function. This option automatically bypasses any installation. \-P 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. NOTE: This only works for functions which actually implement pip based installations. \-F Allow copied files to overwrite existing(config, init.d, etc) \-U If set, fully upgrade the system prior to bootstrapping salt \-K If set, keep the temporary files in the temporary directories specified with \-c and \-k. \-I If set, allow insecure connections while downloading any files. For example, pass \(aq\-\-no\-check\-certificate\(aq to \(aqwget\(aq or \(aq\-\-insecure\(aq to \(aqcurl\(aq \-A Pass the salt\-master DNS name or IP. This will be stored under ${BS_SALT_ETC_DIR}/minion.d/99\-master\-address.conf \-i Pass the salt\-minion id. This will be stored under ${BS_SALT_ETC_DIR}/minion_id \-L Install the Apache Libcloud package if possible(required for salt\-cloud) \-p Extra\-package to install while installing salt dependencies. One package per \-p flag. You\(aqre responsible for providing the proper package name. \-d Disable check_service functions. Setting this flag disables the \(aqinstall__check_services\(aq checks. You can also do this by touching /tmp/disable_salt_checks on the target host. Defaults ${BS_FALSE} \-H Use the specified http proxy for the installation \-Z Enable external software source for newer ZeroMQ(Only available for RHEL/CentOS/Fedora/Ubuntu based distributions) \-b Assume that dependencies are already installed and software sources are set up. If git is selected, git tree is still checked out as dependency step. .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 \fB4505\fP and \fB4506\fP, 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 Fedora 18 and beyond / RHEL 7 / CentOS 7 .sp Starting with Fedora 18 \fI\%FirewallD\fP is the tool that is used to dynamically manage the firewall rules on a host. It has support for IPv4/6 settings and the separation of runtime and permanent configurations. To interact with FirewallD use the command line client \fBfirewall\-cmd\fP\&. .sp \fBfirewall\-cmd example\fP: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C firewall\-cmd \-\-permanent \-\-zone= \-\-add\-port=4505\-4506/tcp .ft P .fi .UNINDENT .UNINDENT .sp Please choose the desired zone according to your setup. Don\(aqt forget to reload after you made your changes. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C firewall\-cmd \-\-reload .ft P .fi .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\%https://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 Minion 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 \fI\%Linux 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 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 \fBSEE ALSO:\fP .INDENT 0.0 .INDENT 3.5 Many ways to preseed minion keys .sp Salt has other ways to generate and pre\-accept minion keys in addition to the manual steps outlined below. .sp salt\-cloud performs these same steps automatically when new cloud VMs are created (unless instructed not to). .sp salt\-api exposes an HTTP call to Salt\(aqs REST API to \fBgenerate and download the new minion keys as a tarball\fP\&. .UNINDENT .UNINDENT .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. For Amazon EC2 only, an AWS best practice is to use IAM Roles to pass credentials. (See blog post, \fI\%http://blogs.aws.amazon.com/security/post/Tx610S2MLVZWEA/Using\-IAM\-roles\-to\-distribute\-non\-AWS\-credentials\-to\-your\-EC2\-instances\fP ) .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.apply\fP or any other salt commands that require master authentication. .SS The macOS (Maverick) Developer Step By Step Guide To Salt Installation .sp This document provides a step\-by\-step guide to installing a Salt cluster consisting of one master, and one minion running on a local VM hosted on macOS. .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 This guide is aimed at developers who wish to run Salt in a virtual machine. The official (Linux) walkthrough can be found \fI\%here\fP\&. .UNINDENT .UNINDENT .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 macOS, 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, compiles, 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" macOS 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/Homebrew/install/master/install)" .ft P .fi .UNINDENT .UNINDENT .sp Now type the following commands in your terminal (you may want to type \fBbrew doctor\fP 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 macOS: .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. .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 macOS 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 into 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 change 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 macOS host). 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 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 can accept them later on. However, this requires accepting the minion key every time the minion is destroyed or created (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 using 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 = "/etc/salt/minion" 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. .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 \fB/srv/salt/top.sls\fP (and subfiles/folders), and then applied by running the \fBstate.apply\fP function to have the Salt master order its minions to update their instructions and run the associated commands. .sp First Create an empty file on your Salt master (macOS 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.apply .ft P .fi .UNINDENT .UNINDENT .sp This should return an error stating: \fBNo Top file or external nodes data matches found\fP\&. .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 \fB/srv/salt/top.sls\fP (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 \fB/srv/salt/bin/nginx.sls\fP 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 \fBstate.apply\fP function again: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C sudo salt \(aqminion1\(aq state.apply .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/en/latest/index.html#configuration\-management\fP .SS running salt as normal user tutorial .sp \fBBefore continuing\fP make sure you have a working Salt installation by following the installation and the configuration instructions. .INDENT 0.0 .INDENT 3.5 .IP "Stuck?" .sp There are many ways to get help from the Salt community including our \fI\%mailing list\fP and our \fI\%IRC channel\fP #salt. .UNINDENT .UNINDENT .SS Running Salt functions as non root user .sp If you don\(aqt want to run salt cloud as root or even install it you can configure it to have a virtual root in your working directory. .sp The salt system uses the \fBsalt.syspath\fP module to find the variables .sp If you run the salt\-build, it will generated in: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C \&./build/lib.linux\-x86_64\-2.7/salt/_syspaths.py .ft P .fi .UNINDENT .UNINDENT .sp To generate it, run the command: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C python setup.py build .ft P .fi .UNINDENT .UNINDENT .sp Copy the generated module into your salt directory .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C cp ./build/lib.linux\-x86_64\-2.7/salt/_syspaths.py salt/_syspaths.py .ft P .fi .UNINDENT .UNINDENT .sp Edit it to include needed variables and your new paths .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C # you need to edit this ROOT_DIR = *your current dir* + \(aq/salt/root\(aq # you need to edit this INSTALL_DIR = *location of source code* CONFIG_DIR = ROOT_DIR + \(aq/etc/salt\(aq CACHE_DIR = ROOT_DIR + \(aq/var/cache/salt\(aq SOCK_DIR = ROOT_DIR + \(aq/var/run/salt\(aq SRV_ROOT_DIR= ROOT_DIR + \(aq/srv\(aq BASE_FILE_ROOTS_DIR = ROOT_DIR + \(aq/srv/salt\(aq BASE_PILLAR_ROOTS_DIR = ROOT_DIR + \(aq/srv/pillar\(aq BASE_MASTER_ROOTS_DIR = ROOT_DIR + \(aq/srv/salt\-master\(aq LOGS_DIR = ROOT_DIR + \(aq/var/log/salt\(aq PIDFILE_DIR = ROOT_DIR + \(aq/var/run\(aq CLOUD_DIR = INSTALL_DIR + \(aq/cloud\(aq BOOTSTRAP = CLOUD_DIR + \(aq/deploy/bootstrap\-salt.sh\(aq .ft P .fi .UNINDENT .UNINDENT .sp Create the directory structure .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C mkdir \-p root/etc/salt root/var/cache/run root/run/salt root/srv root/srv/salt root/srv/pillar root/srv/salt\-master root/var/log/salt root/var/run .ft P .fi .UNINDENT .UNINDENT .sp Populate the configuration files: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C cp \-r conf/* root/etc/salt/ .ft P .fi .UNINDENT .UNINDENT .sp Edit your \fBroot/etc/salt/master\fP configuration that is used by salt\-cloud: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C user: *your user name* .ft P .fi .UNINDENT .UNINDENT .sp Run like this: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C PYTHONPATH=\(gapwd\(ga scripts/salt\-cloud .ft P .fi .UNINDENT .UNINDENT .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 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 Minion Configuration .sp Throughout this document there are several references to setting different options to configure a masterless Minion. Salt Minions are easy to configure via a configuration file that is located, by default, in \fB/etc/salt/minion\fP\&. Note, however, that on FreeBSD systems, the minion configuration file is located in \fB/usr/local/etc/salt/minion\fP\&. .sp You can learn more about minion configuration options in the Configuring the Salt Minion docs. .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 and 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 The declared state can now be executed with: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt\-call state.apply .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.apply \-\-local .ft P .fi .UNINDENT .UNINDENT .SS External Pillars .sp External pillars are supported when running in masterless mode. .SS Salt Masterless Quickstart .sp Running a masterless salt\-minion lets you use Salt\(aqs configuration management for a single machine without calling out to a Salt master on another machine. .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 It is also useful for testing out state trees before deploying to a production setup. .SS Bootstrap Salt Minion .sp The \fI\%salt\-bootstrap\fP script makes bootstrapping a server with Salt simple for any OS with a Bourne shell: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C curl \-L https://bootstrap.saltstack.com \-o bootstrap_salt.sh sudo sh bootstrap_salt.sh .ft P .fi .UNINDENT .UNINDENT .sp See the \fI\%salt\-bootstrap\fP documentation for other one liners. When using \fI\%Vagrant\fP to test out salt, the \fI\%Vagrant salt provisioner\fP will provision the VM for you. .SS Telling Salt to Run Masterless .sp To instruct the minion to not look for a master, the \fBfile_client\fP configuration option needs to be set in the minion configuration file. By default the \fBfile_client\fP is set to \fBremote\fP so that the minion gathers file server and pillar data from the salt 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 minion will not look for a master and will assume that the local system has all of the file and pillar resources. .sp Configuration which resided in the master configuration (e.g. \fB/etc/salt/master\fP) should be moved to the minion configuration since the minion does not read the master configuration. .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 Create State Tree .sp Following the successful installation of a salt\-minion, the next step is to create a state tree, which is where the SLS files that comprise the possible states of the minion are stored. .sp The following example walks through the steps necessary to create a state tree that ensures that the server has the Apache webserver installed. .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 For a complete explanation on Salt States, see the \fI\%tutorial\fP\&. .UNINDENT .UNINDENT .INDENT 0.0 .IP 1. 3 Create the \fBtop.sls\fP 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 the 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 \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 The apache package has different names on different platforms, for instance on Debian/Ubuntu it is apache2, on Fedora/RHEL it is httpd and on Arch it is apache .UNINDENT .UNINDENT .sp The only thing left is to provision our minion using \fBsalt\-call\fP\&. .SS Salt\-call .sp The salt\-call command is used to run remote execution 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: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt\-call \-\-local state.apply .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 and not to contact a Salt Master for instructions. .sp To provide verbose output, use \fB\-l debug\fP: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt\-call \-\-local state.apply \-l debug .ft P .fi .UNINDENT .UNINDENT .sp The minion first examines the \fBtop.sls\fP file and determines that it is a part of the group matched by \fB*\fP glob and that the \fBwebserver\fP SLS should be applied. .sp It then examines the \fBwebserver.sls\fP file and finds the \fBapache\fP state, which installs the Apache package. .sp The minion should now have Apache installed, and the next step is to begin learning how to write more complex states\&. .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\%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) .IP \(bu 2 \fI\%MarkupSafe\fP \- Implements a XML/HTML/XHTML Markup safe string for Python .IP \(bu 2 \fI\%apache\-libcloud\fP \- Python lib for interacting with many of the popular cloud service providers using a unified API .IP \(bu 2 \fI\%Requests\fP \- HTTP library .IP \(bu 2 \fI\%Tornado\fP \- Web framework and asynchronous networking library .IP \(bu 2 \fI\%futures\fP \- Backport of the concurrent.futures package from Python 3.2 .UNINDENT .sp Depending on the chosen Salt transport, \fI\%ZeroMQ\fP or \fI\%RAET\fP, dependencies vary: .INDENT 0.0 .IP \(bu 2 ZeroMQ: .INDENT 2.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 .UNINDENT .IP \(bu 2 RAET: .INDENT 2.0 .IP \(bu 2 \fI\%libnacl\fP \- Python bindings to \fI\%libsodium\fP .IP \(bu 2 \fI\%ioflo\fP \- The flo programming interface raet and salt\-raet is built on .IP \(bu 2 \fI\%RAET\fP \- The worlds most awesome UDP protocol .UNINDENT .UNINDENT .sp Salt defaults to the \fI\%ZeroMQ\fP transport, and the choice can be made at install time, for example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C python setup.py \-\-salt\-transport=raet install .ft P .fi .UNINDENT .UNINDENT .sp This way, only the required dependencies are pulled by the setup script if need be. .sp If installing using pip, the \fB\-\-salt\-transport\fP install option can be provided like: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C pip install \-\-install\-option="\-\-salt\-transport=raet" salt .ft P .fi .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 Salt does not bundle dependencies that are typically distributed as part of the base OS. If you have unmet dependencies and are using a custom or minimal installation, you might need to install some additional packages from your OS vendor. .UNINDENT .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. Backward compatibility for minions running newer versions of salt than their masters is not guaranteed. .sp Whenever possible, backward compatibility between new masters and old minions will be preserved. Generally, the only exception to this policy is in case of a security vulnerability. .sp \fBSEE ALSO:\fP .INDENT 0.0 .INDENT 3.5 Installing Salt for development and contributing to the project. .UNINDENT .UNINDENT .SS Building Packages using Salt Pack .sp Salt\-pack is an open\-source package builder for most commonly used Linux platforms, for example: Redhat/CentOS and Debian/Ubuntu families, utilizing SaltStack states and execution modules to build Salt and a specified set of dependencies, from which a platform specific repository can be built. .sp \fI\%https://github.com/saltstack/salt\-pack\fP .SH CONFIGURING SALT .sp This section explains how to configure user access, view and store job results, secure and troubleshoot, and how to perform many other administrative tasks. .SS Configuring the Salt Master .sp The Salt system is amazingly simple and easy to configure, the two components of the Salt system each have a respective configuration file. The \fBsalt\-master\fP is configured via the master configuration file, and the \fBsalt\-minion\fP is configured via the minion configuration file. .sp \fBSEE ALSO:\fP .INDENT 0.0 .INDENT 3.5 Example master configuration file\&. .UNINDENT .UNINDENT .sp The configuration file for the salt\-master is located at \fB/etc/salt/master\fP by default. A notable exception is FreeBSD, where the configuration file is located at \fB/usr/local/etc/salt\fP\&. The available options are as follows: .SS Primary Master Configuration .SS \fBinterface\fP .sp Default: \fB0.0.0.0\fP (all interfaces) .sp The local interface to bind to. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C interface: 192.168.0.1 .ft P .fi .UNINDENT .UNINDENT .SS \fBipv6\fP .sp Default: \fBFalse\fP .sp Whether the master should listen for IPv6 connections. If this is set to True, the interface option must be adjusted too (for example: \fBinterface: \(aq::\(aq\fP) .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C ipv6: True .ft P .fi .UNINDENT .UNINDENT .SS \fBpublish_port\fP .sp Default: \fB4505\fP .sp The network port to set up the publication interface. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C publish_port: 4505 .ft P .fi .UNINDENT .UNINDENT .SS \fBmaster_id\fP .sp Default: \fBNone\fP .sp The id to be passed in the publish job to minions. This is used for MultiSyndics to return the job to the requesting master. .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 This must be the same string as the syndic is configured with. .UNINDENT .UNINDENT .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C master_id: MasterOfMaster .ft P .fi .UNINDENT .UNINDENT .SS \fBuser\fP .sp Default: \fBroot\fP .sp The user to run the Salt processes .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C user: root .ft P .fi .UNINDENT .UNINDENT .SS \fBmax_open_files\fP .sp Default: \fB100000\fP .sp Each minion connecting to the master uses AT LEAST one file descriptor, the master subscription connection. If enough minions connect you might start seeing on the console(and then salt\-master crashes): .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C Too many open files (tcp_listener.cpp:335) Aborted (core dumped) .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C max_open_files: 100000 .ft P .fi .UNINDENT .UNINDENT .sp By default this value will be the one of \fIulimit \-Hn\fP, i.e., the hard limit for max open files. .sp To set a different value than the default one, uncomment, and configure this setting. Remember that this value CANNOT be higher than the hard limit. Raising the hard limit depends on the OS and/or distribution, a good way to find the limit is to search the internet for something like this: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C raise max open files hard limit debian .ft P .fi .UNINDENT .UNINDENT .SS \fBworker_threads\fP .sp Default: \fB5\fP .sp The number of threads to start for receiving commands and replies from minions. If minions are stalling on replies because you have many minions, raise the worker_threads value. .sp Worker threads should not be put below 3 when using the peer system, but can drop down to 1 worker otherwise. .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 When the master daemon starts, it is expected behaviour to see multiple salt\-master processes, even if \(aqworker_threads\(aq is set to \(aq1\(aq. At a minimum, a controlling process will start along with a Publisher, an EventPublisher, and a number of MWorker processes will be started. The number of MWorker processes is tuneable by the \(aqworker_threads\(aq configuration value while the others are not. .UNINDENT .UNINDENT .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C worker_threads: 5 .ft P .fi .UNINDENT .UNINDENT .SS \fBret_port\fP .sp Default: \fB4506\fP .sp The port used by the return server, this is the server used by Salt to receive execution returns and command executions. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C ret_port: 4506 .ft P .fi .UNINDENT .UNINDENT .SS \fBpidfile\fP .sp Default: \fB/var/run/salt\-master.pid\fP .sp Specify the location of the master pidfile. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C pidfile: /var/run/salt\-master.pid .ft P .fi .UNINDENT .UNINDENT .SS \fBroot_dir\fP .sp Default: \fB/\fP .sp The system root directory to operate from, change this to make Salt run from an alternative root. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C root_dir: / .ft P .fi .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 This directory is prepended to the following options: \fI\%pki_dir\fP, \fI\%cachedir\fP, \fI\%sock_dir\fP, \fI\%log_file\fP, \fI\%autosign_file\fP, \fI\%autoreject_file\fP, \fI\%pidfile\fP\&. .UNINDENT .UNINDENT .SS \fBconf_file\fP .sp Default: \fB/etc/salt/master\fP .sp The path to the master\(aqs configuration file. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C conf_file: /etc/salt/master .ft P .fi .UNINDENT .UNINDENT .SS \fBpki_dir\fP .sp Default: \fB/etc/salt/pki/master\fP .sp The directory to store the pki authentication keys. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C pki_dir: /etc/salt/pki/master .ft P .fi .UNINDENT .UNINDENT .SS \fBextension_modules\fP .sp Changed in version 2016.3.0: The default location for this directory has been moved. Prior to this version, the location was a directory named \fBextmods\fP in the Salt cachedir (on most platforms, \fB/var/cache/salt/extmods\fP). It has been moved into the master cachedir (on most platforms, \fB/var/cache/salt/master/extmods\fP). .sp Directory for custom modules. This directory can contain subdirectories for each of Salt\(aqs module types such as \fBrunners\fP, \fBoutput\fP, \fBwheel\fP, \fBmodules\fP, \fBstates\fP, \fBreturners\fP, \fBengines\fP, etc. This path is appended to \fI\%root_dir\fP\&. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C extension_modules: /root/salt_extmods .ft P .fi .UNINDENT .UNINDENT .SS \fBmodule_dirs\fP .sp Default: \fB[]\fP .sp Like \fBextension_modules\fP, but a list of extra directories to search for Salt modules. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C module_dirs: \- /var/cache/salt/minion/extmods .ft P .fi .UNINDENT .UNINDENT .SS \fBcachedir\fP .sp Default: \fB/var/cache/salt/master\fP .sp The location used to store cache information, particularly the job information for executed salt commands. .sp This directory may contain sensitive data and should be protected accordingly. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C cachedir: /var/cache/salt/master .ft P .fi .UNINDENT .UNINDENT .SS \fBverify_env\fP .sp Default: \fBTrue\fP .sp Verify and set permissions on configuration directories at startup. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C verify_env: True .ft P .fi .UNINDENT .UNINDENT .SS \fBkeep_jobs\fP .sp Default: \fB24\fP .sp Set the number of hours to keep old job information. Note that setting this option to \fB0\fP disables the cache cleaner. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C keep_jobs: 24 .ft P .fi .UNINDENT .UNINDENT .SS \fBgather_job_timeout\fP .sp New in version 2014.7.0. .sp Default: \fB10\fP .sp The number of seconds to wait when the client is requesting information about running jobs. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C gather_job_timeout: 10 .ft P .fi .UNINDENT .UNINDENT .SS \fBtimeout\fP .sp Default: \fB5\fP .sp Set the default timeout for the salt command and api. .SS \fBloop_interval\fP .sp Default: \fB60\fP .sp The loop_interval option controls the seconds for the master\(aqs maintenance process check cycle. This process updates file server backends, cleans the job cache and executes the scheduler. .SS \fBoutput\fP .sp Default: \fBnested\fP .sp Set the default outputter used by the salt command. .SS \fBoutput_file\fP .sp Default: None .sp Set the default output file used by the salt command. Default is to output to the CLI and not to a file. Functions the same way as the "\-\-out\-file" CLI option, only sets this to a single file for all salt commands. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C output_file: /path/output/file .ft P .fi .UNINDENT .UNINDENT .SS \fBcolor\fP .sp Default: \fBTrue\fP .sp By default output is colored, to disable colored output set the color value to False. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C color: False .ft P .fi .UNINDENT .UNINDENT .SS \fBcli_summary\fP .sp Default: \fBFalse\fP .sp When set to \fBTrue\fP, displays a summary of the number of minions targeted, the number of minions returned, and the number of minions that did not return. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C cli_summary: False .ft P .fi .UNINDENT .UNINDENT .SS \fBsock_dir\fP .sp Default: \fB/var/run/salt/master\fP .sp Set the location to use for creating Unix sockets for master process communication. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C sock_dir: /var/run/salt/master .ft P .fi .UNINDENT .UNINDENT .SS \fBenable_gpu_grains\fP .sp Default: \fBTrue\fP .sp Enable GPU hardware data for your master. Be aware that the master can take a while to start up when lspci and/or dmidecode is used to populate the grains for the master. .SS \fBjob_cache\fP .sp Default: \fBTrue\fP .sp The master maintains a temporary job cache. While this is a great addition, it can be a burden on the master for larger deployments (over 5000 minions). Disabling the job cache will make previously executed jobs unavailable to the jobs system and is not generally recommended. Normally it is wise to make sure the master has access to a faster IO system or a tmpfs is mounted to the jobs dir. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C job_cache: True .ft P .fi .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 Setting the \fBjob_cache\fP to \fBFalse\fP will not cache minion returns, but the JID directory for each job is still created. The creation of the JID directories is necessary because Salt uses those directories to check for JID collisions. By setting this option to \fBFalse\fP, the job cache directory, which is \fB/var/cache/salt/master/jobs/\fP by default, will be smaller, but the JID directories will still be present. .sp Note that the \fI\%keep_jobs\fP option can be set to a lower value, such as \fB1\fP, to limit the number of hours jobs are stored in the job cache. (The default is 24 hours.) .sp Please see the Managing the Job Cache documentation for more information. .UNINDENT .UNINDENT .SS \fBminion_data_cache\fP .sp Default: \fBTrue\fP .sp The minion data cache is a cache of information about the minions stored on the master, this information is primarily the pillar, grains and mine data. The data is cached via the cache subsystem in the Master cachedir under the name of the minion or in a supported database. The data is used to predetermine what minions are expected to reply from executions. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C minion_data_cache: True .ft P .fi .UNINDENT .UNINDENT .SS \fBcache\fP .sp Default: \fBlocalfs\fP .sp Cache subsystem module to use for minion data cache. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C cache: consul .ft P .fi .UNINDENT .UNINDENT .SS \fBext_job_cache\fP .sp Default: \fB\(aq\(aq\fP .sp Used to specify a default returner for all minions. When this option is set, the specified returner needs to be properly configured and the minions will always default to sending returns to this returner. This will also disable the local job cache on the master. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C ext_job_cache: redis .ft P .fi .UNINDENT .UNINDENT .SS \fBevent_return\fP .sp New in version 2015.5.0. .sp Default: \fB\(aq\(aq\fP .sp Specify the returner(s) to use to log events. Each returner may have installation and configuration requirements. Read the returner\(aqs documentation. .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 Not all returners support event returns. Verify that a returner has an \fBevent_return()\fP function before configuring this option with a returner. .UNINDENT .UNINDENT .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C event_return: \- syslog \- splunk .ft P .fi .UNINDENT .UNINDENT .SS \fBevent_return_queue\fP .sp New in version 2015.5.0. .sp Default: \fB0\fP .sp On busy systems, enabling event_returns can cause a considerable load on the storage system for returners. Events can be queued on the master and stored in a batched fashion using a single transaction for multiple events. By default, events are not queued. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C event_return_queue: 0 .ft P .fi .UNINDENT .UNINDENT .SS \fBevent_return_whitelist\fP .sp New in version 2015.5.0. .sp Default: \fB[]\fP .sp Only return events matching tags in a whitelist. .sp Changed in version 2016.11.0: Supports glob matching patterns. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C event_return_whitelist: \- salt/master/a_tag \- salt/run/*/ret .ft P .fi .UNINDENT .UNINDENT .SS \fBevent_return_blacklist\fP .sp New in version 2015.5.0. .sp Default: \fB[]\fP .sp Store all event returns _except_ the tags in a blacklist. .sp Changed in version 2016.11.0: Supports glob matching patterns. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C event_return_blacklist: \- salt/master/not_this_tag \- salt/wheel/*/ret .ft P .fi .UNINDENT .UNINDENT .SS \fBmax_event_size\fP .sp New in version 2014.7.0. .sp Default: \fB1048576\fP .sp Passing very large events can cause the minion to consume large amounts of memory. This value tunes the maximum size of a message allowed onto the master event bus. The value is expressed in bytes. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C max_event_size: 1048576 .ft P .fi .UNINDENT .UNINDENT .SS \fBmaster_job_cache\fP .sp New in version 2014.7.0. .sp Default: \fBlocal_cache\fP .sp Specify the returner to use for the job cache. The job cache will only be interacted with from the salt master and therefore does not need to be accessible from the minions. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C master_job_cache: redis .ft P .fi .UNINDENT .UNINDENT .SS \fBenforce_mine_cache\fP .sp Default: False .sp By\-default when disabling the minion_data_cache mine will stop working since it is based on cached data, by enabling this option we explicitly enabling only the cache for the mine system. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C enforce_mine_cache: False .ft P .fi .UNINDENT .UNINDENT .SS \fBmax_minions\fP .sp Default: 0 .sp The maximum number of minion connections allowed by the master. Use this to accommodate the number of minions per master if you have different types of hardware serving your minions. The default of \fB0\fP means unlimited connections. Please note that this can slow down the authentication process a bit in large setups. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C max_minions: 100 .ft P .fi .UNINDENT .UNINDENT .SS \fBcon_cache\fP .sp Default: False .sp If max_minions is used in large installations, the master might experience high\-load situations because of having to check the number of connected minions for every authentication. This cache provides the minion\-ids of all connected minions to all MWorker\-processes and greatly improves the performance of max_minions. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C con_cache: True .ft P .fi .UNINDENT .UNINDENT .SS \fBpresence_events\fP .sp Default: False .sp Causes the master to periodically look for actively connected minions. Presence events are fired on the event bus on a regular interval with a list of connected minions, as well as events with lists of newly connected or disconnected minions. This is a master\-only operation that does not send executions to minions. Note, this does not detect minions that connect to a master via localhost. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C presence_events: False .ft P .fi .UNINDENT .UNINDENT .SS \fBtransport\fP .sp Default: \fBzeromq\fP .sp Changes the underlying transport layer. ZeroMQ is the recommended transport while additional transport layers are under development. Supported values are \fBzeromq\fP, \fBraet\fP (experimental), and \fBtcp\fP (experimental). This setting has a significant impact on performance and should not be changed unless you know what you are doing! Transports are explained in Salt Transports\&. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C transport: zeromq .ft P .fi .UNINDENT .UNINDENT .SS \fBtransport_opts\fP .sp Default: \fB{}\fP .sp (experimental) Starts multiple transports and overrides options for each transport with the provided dictionary This setting has a significant impact on performance and should not be changed unless you know what you are doing! Transports are explained in Salt Transports\&. The following example shows how to start a TCP transport alongside a ZMQ transport. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C transport_opts: tcp: publish_port: 4605 ret_port: 4606 zeromq: [] .ft P .fi .UNINDENT .UNINDENT .SS Salt\-SSH Configuration .SS \fBroster_file\fP .sp Default: \fB/etc/salt/roster\fP .sp Pass in an alternative location for the salt\-ssh roster file. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C roster_file: /root/roster .ft P .fi .UNINDENT .UNINDENT .SS \fBssh_log_file\fP .sp New in version 2016.3.5. .sp Default: \fB/var/log/salt/ssh\fP .sp Specify the log file of the \fBsalt\-ssh\fP command. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C ssh_log_file: /var/log/salt/ssh .ft P .fi .UNINDENT .UNINDENT .SS \fBssh_minion_opts\fP .sp Default: None .sp Pass in minion option overrides that will be inserted into the SHIM for salt\-ssh calls. The local minion config is not used for salt\-ssh. Can be overridden on a per\-minion basis in the roster (\fBminion_opts\fP) .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C ssh_minion_opts: gpg_keydir: /root/gpg .ft P .fi .UNINDENT .UNINDENT .SS \fBssh_use_home_key\fP .sp Default: False .sp Set this to True to default to using \fB~/.ssh/id_rsa\fP for salt\-ssh authentication with minions .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C ssh_use_home_key: False .ft P .fi .UNINDENT .UNINDENT .SS \fBthin_extra_mods\fP .sp Default: None .sp List of additional modules, needed to be included into the Salt Thin. Pass a list of importable Python modules that are typically located in the \fIsite\-packages\fP Python directory so they will be also always included into the Salt Thin, once generated. .SS Master Security Settings .SS \fBopen_mode\fP .sp Default: \fBFalse\fP .sp Open mode is a dangerous security feature. One problem encountered with pki authentication systems is that keys can become "mixed up" and authentication begins to fail. Open mode turns off authentication and tells the master to accept all authentication. This will clean up the pki keys received from the minions. Open mode should not be turned on for general use. Open mode should only be used for a short period of time to clean up pki keys. To turn on open mode set this value to \fBTrue\fP\&. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C open_mode: False .ft P .fi .UNINDENT .UNINDENT .SS \fBauto_accept\fP .sp Default: \fBFalse\fP .sp Enable auto_accept. This setting will automatically accept all incoming public keys from minions. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C auto_accept: False .ft P .fi .UNINDENT .UNINDENT .SS \fBautosign_timeout\fP .sp New in version 2014.7.0. .sp Default: \fB120\fP .sp Time in minutes that a incoming public key with a matching name found in pki_dir/minion_autosign/keyid is automatically accepted. Expired autosign keys are removed when the master checks the minion_autosign directory. This method to auto accept minions can be safer than an autosign_file because the keyid record can expire and is limited to being an exact name match. This should still be considered a less than secure option, due to the fact that trust is based on just the requesting minion id. .SS \fBautosign_file\fP .sp Default: \fBnot defined\fP .sp If the \fBautosign_file\fP is specified incoming keys specified in the autosign_file will be automatically accepted. Matches will be searched for first by string comparison, then by globbing, then by full\-string regex matching. This should still be considered a less than secure option, due to the fact that trust is based on just the requesting minion id. .SS \fBautoreject_file\fP .sp New in version 2014.1.0. .sp Default: \fBnot defined\fP .sp Works like \fI\%autosign_file\fP, but instead allows you to specify minion IDs for which keys will automatically be rejected. Will override both membership in the \fI\%autosign_file\fP and the \fI\%auto_accept\fP setting. .SS \fBpublisher_acl\fP .sp Default: \fB{}\fP .sp Enable user accounts on the master to execute specific modules. These modules can be expressed as regular expressions. Note that client_acl option is deprecated by publisher_acl option and will be removed in future releases. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C publisher_acl: fred: \- test.ping \- pkg.* .ft P .fi .UNINDENT .UNINDENT .SS \fBpublisher_acl_blacklist\fP .sp Default: \fB{}\fP .sp Blacklist users or modules .sp This example would blacklist all non sudo users, including root from running any commands. It would also blacklist any use of the "cmd" module. Note that client_acl_blacklist option is deprecated by publisher_acl_blacklist option and will be removed in future releases. .sp This is completely disabled by default. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C publisher_acl_blacklist: users: \- root \- \(aq^(?!sudo_).*$\(aq # all non sudo users modules: \- cmd .ft P .fi .UNINDENT .UNINDENT .SS \fBexternal_auth\fP .sp Default: \fB{}\fP .sp The external auth system uses the Salt auth modules to authenticate and validate users to access areas of the Salt system. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C external_auth: pam: fred: \- test.* .ft P .fi .UNINDENT .UNINDENT .SS \fBtoken_expire\fP .sp Default: \fB43200\fP .sp Time (in seconds) for a newly generated token to live. .sp Default: 12 hours .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C token_expire: 43200 .ft P .fi .UNINDENT .UNINDENT .SS \fBtoken_expire_user_override\fP .sp Default: \fBFalse\fP .sp Allow eauth users to specify the expiry time of the tokens they generate. .sp A boolean applies to all users or a dictionary of whitelisted eauth backends and usernames may be given: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C token_expire_user_override: pam: \- fred \- tom ldap: \- gary .ft P .fi .UNINDENT .UNINDENT .SS \fBfile_recv\fP .sp Default: \fBFalse\fP .sp Allow minions to push files to the master. This is disabled by default, for security purposes. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C file_recv: False .ft P .fi .UNINDENT .UNINDENT .SS \fBfile_recv_max_size\fP .sp New in version 2014.7.0. .sp Default: \fB100\fP .sp Set a hard\-limit on the size of the files that can be pushed to the master. It will be interpreted as megabytes. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C file_recv_max_size: 100 .ft P .fi .UNINDENT .UNINDENT .SS \fBmaster_sign_pubkey\fP .sp Default: \fBFalse\fP .sp Sign the master auth\-replies with a cryptographic signature of the master\(aqs public key. Please see the tutorial how to use these settings in the \fI\%Multimaster\-PKI with Failover Tutorial\fP .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C master_sign_pubkey: True .ft P .fi .UNINDENT .UNINDENT .SS \fBmaster_sign_key_name\fP .sp Default: \fBmaster_sign\fP .sp The customizable name of the signing\-key\-pair without suffix. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C master_sign_key_name: .ft P .fi .UNINDENT .UNINDENT .SS \fBmaster_pubkey_signature\fP .sp Default: \fBmaster_pubkey_signature\fP .sp The name of the file in the master\(aqs pki\-directory that holds the pre\-calculated signature of the master\(aqs public\-key. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C master_pubkey_signature: .ft P .fi .UNINDENT .UNINDENT .SS \fBmaster_use_pubkey_signature\fP .sp Default: \fBFalse\fP .sp Instead of computing the signature for each auth\-reply, use a pre\-calculated signature. The \fI\%master_pubkey_signature\fP must also be set for this. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C master_use_pubkey_signature: True .ft P .fi .UNINDENT .UNINDENT .SS \fBrotate_aes_key\fP .sp Default: \fBTrue\fP .sp Rotate the salt\-masters AES\-key when a minion\-public is deleted with salt\-key. This is a very important security\-setting. Disabling it will enable deleted minions to still listen in on the messages published by the salt\-master. Do not disable this unless it is absolutely clear what this does. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C rotate_aes_key: True .ft P .fi .UNINDENT .UNINDENT .SS \fBssl\fP .sp New in version 2016.11.0. .sp Default: \fBNone\fP .sp TLS/SSL connection options. This could be set to a dictionary containing arguments corresponding to python \fBssl.wrap_socket\fP method. For details see \fI\%Tornado\fP and \fI\%Python\fP documentation. .sp Note: to set enum arguments values like \fBcert_reqs\fP and \fBssl_version\fP use constant names without ssl module prefix: \fBCERT_REQUIRED\fP or \fBPROTOCOL_SSLv23\fP\&. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C ssl: keyfile: certfile: ssl_version: PROTOCOL_TLSv1_2 .ft P .fi .UNINDENT .UNINDENT .SS Master Module Management .SS \fBrunner_dirs\fP .sp Default: \fB[]\fP .sp Set additional directories to search for runner modules. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C runner_dirs: \- /var/lib/salt/runners .ft P .fi .UNINDENT .UNINDENT .SS \fBcython_enable\fP .sp Default: \fBFalse\fP .sp Set to true to enable Cython modules (.pyx files) to be compiled on the fly on the Salt master. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C cython_enable: False .ft P .fi .UNINDENT .UNINDENT .SS Master State System Settings .SS \fBstate_top\fP .sp Default: \fBtop.sls\fP .sp The state system uses a "top" file to tell the minions what environment to use and what modules to use. The state_top file is defined relative to the root of the base environment. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C state_top: top.sls .ft P .fi .UNINDENT .UNINDENT .SS \fBmaster_tops\fP .sp Default: \fB{}\fP .sp The master_tops option replaces the external_nodes option by creating a pluggable system for the generation of external top data. The external_nodes option is deprecated by the master_tops option. To gain the capabilities of the classic external_nodes system, use the following configuration: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C master_tops: ext_nodes: .ft P .fi .UNINDENT .UNINDENT .SS \fBexternal_nodes\fP .sp Default: None .sp The external_nodes option allows Salt to gather data that would normally be placed in a top file from and external node controller. The external_nodes option is the executable that will return the ENC data. Remember that Salt will look for external nodes AND top files and combine the results if both are enabled and available! .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C external_nodes: cobbler\-ext\-nodes .ft P .fi .UNINDENT .UNINDENT .SS \fBrenderer\fP .sp Default: \fByaml_jinja\fP .sp The renderer to use on the minions to render the state data. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C renderer: yaml_jinja .ft P .fi .UNINDENT .UNINDENT .SS \fBjinja_trim_blocks\fP .sp New in version 2014.1.0. .sp Default: \fBFalse\fP .sp If this is set to \fBTrue\fP, the first newline after a Jinja block is removed (block, not variable tag!). Defaults to \fBFalse\fP and corresponds to the Jinja environment init variable \fBtrim_blocks\fP\&. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C jinja_trim_blocks: False .ft P .fi .UNINDENT .UNINDENT .SS \fBjinja_lstrip_blocks\fP .sp New in version 2014.1.0. .sp Default: \fBFalse\fP .sp If this is set to \fBTrue\fP, leading spaces and tabs are stripped from the start of a line to a block. Defaults to \fBFalse\fP and corresponds to the Jinja environment init variable \fBlstrip_blocks\fP\&. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C jinja_lstrip_blocks: False .ft P .fi .UNINDENT .UNINDENT .SS \fBfailhard\fP .sp Default: \fBFalse\fP .sp Set the global failhard flag. This informs all states to stop running states at the moment a single state fails. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C failhard: False .ft P .fi .UNINDENT .UNINDENT .SS \fBstate_verbose\fP .sp Default: \fBTrue\fP .sp Controls the verbosity of state runs. By default, the results of all states are returned, but setting this value to \fBFalse\fP will cause salt to only display output for states that failed or states that have changes. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C state_verbose: False .ft P .fi .UNINDENT .UNINDENT .SS \fBstate_output\fP .sp Default: \fBfull\fP .sp The state_output setting changes if the output is the full multi line output for each changed state if set to \(aqfull\(aq, but if set to \(aqterse\(aq the output will be shortened to a single line. If set to \(aqmixed\(aq, the output will be terse unless a state failed, in which case that output will be full. If set to \(aqchanges\(aq, the output will be full unless the state didn\(aqt change. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C state_output: full .ft P .fi .UNINDENT .UNINDENT .SS \fBstate_aggregate\fP .sp Default: \fBFalse\fP .sp Automatically aggregate all states that have support for mod_aggregate by setting to \fBTrue\fP\&. Or pass a list of state module names to automatically aggregate just those types. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C state_aggregate: \- pkg .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C state_aggregate: True .ft P .fi .UNINDENT .UNINDENT .SS \fBstate_events\fP .sp Default: \fBFalse\fP .sp Send progress events as each function in a state run completes execution by setting to \fBTrue\fP\&. Progress events are in the format \fBsalt/job//prog//\fP\&. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C state_events: True .ft P .fi .UNINDENT .UNINDENT .SS \fByaml_utf8\fP .sp Default: \fBFalse\fP .sp Enable extra routines for YAML renderer used states containing UTF characters. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C yaml_utf8: False .ft P .fi .UNINDENT .UNINDENT .SS \fBrunner_returns\fP .sp Default: \fBFalse\fP .sp If set to \fBTrue\fP, runner jobs will be saved to job cache (defined by \fI\%master_job_cache\fP). .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C runner_returns: True .ft P .fi .UNINDENT .UNINDENT .SS Master File Server Settings .SS \fBfileserver_backend\fP .sp Default: \fB[\(aqroots\(aq]\fP .sp Salt supports a modular fileserver backend system, this system allows the salt master to link directly to third party systems to gather and manage the files available to minions. Multiple backends can be configured and will be searched for the requested file in the order in which they are defined here. The default setting only enables the standard backend \fBroots\fP, which is configured using the \fI\%file_roots\fP option. .sp Example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C fileserver_backend: \- roots \- git .ft P .fi .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 For masterless Salt, this parameter must be specified in the minion config file. .UNINDENT .UNINDENT .SS \fBfileserver_followsymlinks\fP .sp New in version 2014.1.0. .sp Default: \fBTrue\fP .sp By default, the file_server follows symlinks when walking the filesystem tree. Currently this only applies to the default roots fileserver_backend. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C fileserver_followsymlinks: True .ft P .fi .UNINDENT .UNINDENT .SS \fBfileserver_ignoresymlinks\fP .sp New in version 2014.1.0. .sp Default: \fBFalse\fP .sp If you do not want symlinks to be treated as the files they are pointing to, set \fBfileserver_ignoresymlinks\fP to \fBTrue\fP\&. By default this is set to False. When set to \fBTrue\fP, any detected symlink while listing files on the Master will not be returned to the Minion. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C fileserver_ignoresymlinks: False .ft P .fi .UNINDENT .UNINDENT .SS \fBfileserver_limit_traversal\fP .sp New in version 2014.1.0. .sp Default: \fBFalse\fP .sp By default, the Salt fileserver recurses fully into all defined environments to attempt to find files. To limit this behavior so that the fileserver only traverses directories with SLS files and special Salt directories like _modules, set \fBfileserver_limit_traversal\fP to \fBTrue\fP\&. This might be useful for installations where a file root has a very large number of files and performance is impacted. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C fileserver_limit_traversal: False .ft P .fi .UNINDENT .UNINDENT .SS \fBfileserver_list_cache_time\fP .sp New in version 2014.1.0. .sp Changed in version 2016.11.0: The default was changed from \fB30\fP seconds to \fB20\fP\&. .sp Default: \fB20\fP .sp Salt caches the list of files/symlinks/directories for each fileserver backend and environment as they are requested, to guard against a performance bottleneck at scale when many minions all ask the fileserver which files are available simultaneously. This configuration parameter allows for the max age of that cache to be altered. .sp Set this value to \fB0\fP to disable use of this cache altogether, but keep in mind that this may increase the CPU load on the master when running a highstate on a large number of minions. .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 Rather than altering this configuration parameter, it may be advisable to use the \fBfileserver.clear_list_cache\fP runner to clear these caches. .UNINDENT .UNINDENT .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C fileserver_list_cache_time: 5 .ft P .fi .UNINDENT .UNINDENT .SS \fBhash_type\fP .sp Default: \fBsha256\fP .sp The hash_type is the hash to use when discovering the hash of a file on the master server. The default is sha256, but md5, sha1, sha224, sha384, and sha512 are also supported. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C hash_type: sha256 .ft P .fi .UNINDENT .UNINDENT .SS \fBfile_buffer_size\fP .sp Default: \fB1048576\fP .sp The buffer size in the file server in bytes. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C file_buffer_size: 1048576 .ft P .fi .UNINDENT .UNINDENT .SS \fBfile_ignore_regex\fP .sp Default: \fB\(aq\(aq\fP .sp A regular expression (or a list of expressions) that will be matched against the file path before syncing the modules and states to the minions. This includes files affected by the file.recurse state. For example, if you manage your custom modules and states in subversion and don\(aqt want all the \(aq.svn\(aq folders and content synced to your minions, you could set this to \(aq/.svn($|/)\(aq. By default nothing is ignored. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C file_ignore_regex: \- \(aq/\e.svn($|/)\(aq \- \(aq/\e.git($|/)\(aq .ft P .fi .UNINDENT .UNINDENT .SS \fBfile_ignore_glob\fP .sp Default \fB\(aq\(aq\fP .sp A file glob (or list of file globs) that will be matched against the file path before syncing the modules and states to the minions. This is similar to file_ignore_regex above, but works on globs instead of regex. By default nothing is ignored. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C file_ignore_glob: \- \(aq\e*.pyc\(aq \- \(aq\e*/somefolder/\e*.bak\(aq \- \(aq\e*.swp\(aq .ft P .fi .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 Vim\(aqs .swp files are a common cause of Unicode errors in \fBfile.recurse\fP states which use templating. Unless there is a good reason to distribute them via the fileserver, it is good practice to include \fB\(aq\e*.swp\(aq\fP in the \fI\%file_ignore_glob\fP\&. .UNINDENT .UNINDENT .SS roots: Master\(aqs Local File Server .SS \fBfile_roots\fP .sp Default: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C base: \- /srv/salt .ft P .fi .UNINDENT .UNINDENT .sp Salt runs a lightweight file server written in ZeroMQ to deliver files to minions. This file server is built into the master daemon and does not require a dedicated port. .sp The file server works on environments passed to the master. Each environment can have multiple root directories. The subdirectories in the multiple file roots cannot match, otherwise the downloaded files will not be able to be reliably ensured. A base environment is required to house the top file. .sp Example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C file_roots: base: \- /srv/salt dev: \- /srv/salt/dev/services \- /srv/salt/dev/states prod: \- /srv/salt/prod/services \- /srv/salt/prod/states .ft P .fi .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 For masterless Salt, this parameter must be specified in the minion config file. .UNINDENT .UNINDENT .SS git: Git Remote File Server Backend .SS \fBgitfs_remotes\fP .sp Default: \fB[]\fP .sp When using the \fBgit\fP fileserver backend at least one git remote needs to be defined. The user running the salt master will need read access to the repo. .sp The repos will be searched in order to find the file requested by a client and the first repo to have the file will return it. Branches and tags are translated into salt environments. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C gitfs_remotes: \- git://github.com/saltstack/salt\-states.git \- file:///var/git/saltmaster .ft P .fi .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 \fBfile://\fP repos will be treated as a remote and copied into the master\(aqs gitfs cache, so only the \fIlocal\fP refs for those repos will be exposed as fileserver environments. .UNINDENT .UNINDENT .sp As of 2014.7.0, it is possible to have per\-repo versions of several of the gitfs configuration parameters. For more information, see the GitFS Walkthrough\&. .SS \fBgitfs_provider\fP .sp New in version 2014.7.0. .sp Optional parameter used to specify the provider to be used for gitfs. More information can be found in the GitFS Walkthrough\&. .sp Must be one of the following: \fBpygit2\fP, \fBgitpython\fP, or \fBdulwich\fP\&. If unset, then each will be tried in that same order, and the first one with a compatible version installed will be the provider that is used. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C gitfs_provider: dulwich .ft P .fi .UNINDENT .UNINDENT .SS \fBgitfs_ssl_verify\fP .sp Changed in version 2016.11.0. .sp Default: \fBTrue\fP .sp Specifies whether or not to ignore SSL certificate errors when contacting the remote repository. The \fBFalse\fP setting is useful if you\(aqre using a git repo that uses a self\-signed certificate. However, keep in mind that setting this to anything other \fBTrue\fP is a considered insecure, and using an SSH\-based transport (if available) may be a better option. .sp In the 2016.11.0 release, the default config value changed from \fBFalse\fP to \fBTrue\fP\&. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C gitfs_ssl_verify: True .ft P .fi .UNINDENT .UNINDENT .SS \fBgitfs_mountpoint\fP .sp New in version 2014.7.0. .sp Default: \fB\(aq\(aq\fP .sp Specifies a path on the salt fileserver which will be prepended to all files served by gitfs. This option can be used in conjunction with \fI\%gitfs_root\fP\&. It can also be configured on a per\-remote basis, see here for more info. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C gitfs_mountpoint: salt://foo/bar .ft P .fi .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 The \fBsalt://\fP protocol designation can be left off (in other words, \fBfoo/bar\fP and \fBsalt://foo/bar\fP are equivalent). Assuming a file \fBbaz.sh\fP in the root of a gitfs remote, and the above example mountpoint, this file would be served up via \fBsalt://foo/bar/baz.sh\fP\&. .UNINDENT .UNINDENT .SS \fBgitfs_root\fP .sp Default: \fB\(aq\(aq\fP .sp Relative path to a subdirectory within the repository from which Salt should begin to serve files. This is useful when there are files in the repository that should not be available to the Salt fileserver. Can be used in conjunction with \fI\%gitfs_mountpoint\fP\&. If used, then from Salt\(aqs perspective the directories above the one specified will be ignored and the relative path will (for the purposes of gitfs) be considered as the root of the repo. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C gitfs_root: somefolder/otherfolder .ft P .fi .UNINDENT .UNINDENT .sp Changed in version 2014.7.0: Ability to specify gitfs roots on a per\-remote basis was added. See here for more info. .SS \fBgitfs_base\fP .sp Default: \fBmaster\fP .sp Defines which branch/tag should be used as the \fBbase\fP environment. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C gitfs_base: salt .ft P .fi .UNINDENT .UNINDENT .sp Changed in version 2014.7.0: Ability to specify the base on a per\-remote basis was added. See here for more info. .SS \fBgitfs_saltenv\fP .sp New in version 2016.11.0. .sp Default: \fB[]\fP .sp Global settings for per\-saltenv configuration parameters\&. Though per\-saltenv configuration parameters are typically one\-off changes specific to a single gitfs remote, and thus more often configured on a per\-remote basis, this parameter can be used to specify per\-saltenv changes which should apply to all remotes. For example, the below configuration will map the \fBdevelop\fP branch to the \fBdev\fP saltenv for all gitfs remotes. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C gitfs_saltenv: \- dev: \- ref: develop .ft P .fi .UNINDENT .UNINDENT .SS \fBgitfs_env_whitelist\fP .sp New in version 2014.7.0. .sp Default: \fB[]\fP .sp Used to restrict which environments are made available. Can speed up state runs if the repos in \fI\%gitfs_remotes\fP contain many branches/tags. More information can be found in the GitFS Walkthrough\&. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C gitfs_env_whitelist: \- base \- v1.* \- \(aqmybranch\ed+\(aq .ft P .fi .UNINDENT .UNINDENT .SS \fBgitfs_env_blacklist\fP .sp New in version 2014.7.0. .sp Default: \fB[]\fP .sp Used to restrict which environments are made available. Can speed up state runs if the repos in \fI\%gitfs_remotes\fP contain many branches/tags. More information can be found in the GitFS Walkthrough\&. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C gitfs_env_blacklist: \- base \- v1.* \- \(aqmybranch\ed+\(aq .ft P .fi .UNINDENT .UNINDENT .SS \fBgitfs_global_lock\fP .sp New in version 2015.8.9. .sp Default: \fBTrue\fP .sp When set to \fBFalse\fP, if there is an update lock for a gitfs remote and the pid written to it is not running on the master, the lock file will be automatically cleared and a new lock will be obtained. When set to \fBTrue\fP, Salt will simply log a warning when there is an update lock present. .sp On single\-master deployments, disabling this option can help automatically deal with instances where the master was shutdown/restarted during the middle of a gitfs update, leaving a update lock in place. .sp However, on multi\-master deployments with the gitfs cachedir shared via \fI\%GlusterFS\fP, nfs, or another network filesystem, it is strongly recommended not to disable this option as doing so will cause lock files to be removed if they were created by a different master. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C # Disable global lock gitfs_global_lock: False .ft P .fi .UNINDENT .UNINDENT .SS GitFS Authentication Options .sp These parameters only currently apply to the pygit2 gitfs provider. Examples of how to use these can be found in the GitFS Walkthrough\&. .SS \fBgitfs_user\fP .sp New in version 2014.7.0. .sp Default: \fB\(aq\(aq\fP .sp Along with \fI\%gitfs_password\fP, is used to authenticate to HTTPS remotes. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C gitfs_user: git .ft P .fi .UNINDENT .UNINDENT .SS \fBgitfs_password\fP .sp New in version 2014.7.0. .sp Default: \fB\(aq\(aq\fP .sp Along with \fI\%gitfs_user\fP, is used to authenticate to HTTPS remotes. This parameter is not required if the repository does not use authentication. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C gitfs_password: mypassword .ft P .fi .UNINDENT .UNINDENT .SS \fBgitfs_insecure_auth\fP .sp New in version 2014.7.0. .sp Default: \fBFalse\fP .sp By default, Salt will not authenticate to an HTTP (non\-HTTPS) remote. This parameter enables authentication over HTTP. \fBEnable this at your own risk.\fP .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C gitfs_insecure_auth: True .ft P .fi .UNINDENT .UNINDENT .SS \fBgitfs_pubkey\fP .sp New in version 2014.7.0. .sp Default: \fB\(aq\(aq\fP .sp Along with \fI\%gitfs_privkey\fP (and optionally \fI\%gitfs_passphrase\fP), is used to authenticate to SSH remotes. This parameter (or its per\-remote counterpart) is required for SSH remotes. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C gitfs_pubkey: /path/to/key.pub .ft P .fi .UNINDENT .UNINDENT .SS \fBgitfs_privkey\fP .sp New in version 2014.7.0. .sp Default: \fB\(aq\(aq\fP .sp Along with \fI\%gitfs_pubkey\fP (and optionally \fI\%gitfs_passphrase\fP), is used to authenticate to SSH remotes. This parameter (or its per\-remote counterpart) is required for SSH remotes. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C gitfs_privkey: /path/to/key .ft P .fi .UNINDENT .UNINDENT .SS \fBgitfs_passphrase\fP .sp New in version 2014.7.0. .sp Default: \fB\(aq\(aq\fP .sp This parameter is optional, required only when the SSH key being used to authenticate is protected by a passphrase. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C gitfs_passphrase: mypassphrase .ft P .fi .UNINDENT .UNINDENT .SS hg: Mercurial Remote File Server Backend .SS \fBhgfs_remotes\fP .sp New in version 0.17.0. .sp Default: \fB[]\fP .sp When using the \fBhg\fP fileserver backend at least one mercurial remote needs to be defined. The user running the salt master will need read access to the repo. .sp The repos will be searched in order to find the file requested by a client and the first repo to have the file will return it. Branches and/or bookmarks are translated into salt environments, as defined by the \fI\%hgfs_branch_method\fP parameter. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C hgfs_remotes: \- https://username@bitbucket.org/username/reponame .ft P .fi .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 As of 2014.7.0, it is possible to have per\-repo versions of the \fI\%hgfs_root\fP, \fI\%hgfs_mountpoint\fP, \fI\%hgfs_base\fP, and \fI\%hgfs_branch_method\fP parameters. For example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C hgfs_remotes: \- https://username@bitbucket.org/username/repo1 \- base: saltstates \- https://username@bitbucket.org/username/repo2: \- root: salt \- mountpoint: salt://foo/bar/baz \- https://username@bitbucket.org/username/repo3: \- root: salt/states \- branch_method: mixed .ft P .fi .UNINDENT .UNINDENT .UNINDENT .UNINDENT .SS \fBhgfs_branch_method\fP .sp New in version 0.17.0. .sp Default: \fBbranches\fP .sp Defines the objects that will be used as fileserver environments. .INDENT 0.0 .IP \(bu 2 \fBbranches\fP \- Only branches and tags will be used .IP \(bu 2 \fBbookmarks\fP \- Only bookmarks and tags will be used .IP \(bu 2 \fBmixed\fP \- Branches, bookmarks, and tags will be used .UNINDENT .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C hgfs_branch_method: mixed .ft P .fi .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 Starting in version 2014.1.0, the value of the \fI\%hgfs_base\fP parameter defines which branch is used as the \fBbase\fP environment, allowing for a \fBbase\fP environment to be used with an \fI\%hgfs_branch_method\fP of \fBbookmarks\fP\&. .sp Prior to this release, the \fBdefault\fP branch will be used as the \fBbase\fP environment. .UNINDENT .UNINDENT .SS \fBhgfs_mountpoint\fP .sp New in version 2014.7.0. .sp Default: \fB\(aq\(aq\fP .sp Specifies a path on the salt fileserver which will be prepended to all files served by hgfs. This option can be used in conjunction with \fI\%hgfs_root\fP\&. It can also be configured on a per\-remote basis, see \fI\%here\fP for more info. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C hgfs_mountpoint: salt://foo/bar .ft P .fi .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 The \fBsalt://\fP protocol designation can be left off (in other words, \fBfoo/bar\fP and \fBsalt://foo/bar\fP are equivalent). Assuming a file \fBbaz.sh\fP in the root of an hgfs remote, this file would be served up via \fBsalt://foo/bar/baz.sh\fP\&. .UNINDENT .UNINDENT .SS \fBhgfs_root\fP .sp New in version 0.17.0. .sp Default: \fB\(aq\(aq\fP .sp Relative path to a subdirectory within the repository from which Salt should begin to serve files. This is useful when there are files in the repository that should not be available to the Salt fileserver. Can be used in conjunction with \fI\%hgfs_mountpoint\fP\&. If used, then from Salt\(aqs perspective the directories above the one specified will be ignored and the relative path will (for the purposes of hgfs) be considered as the root of the repo. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C hgfs_root: somefolder/otherfolder .ft P .fi .UNINDENT .UNINDENT .sp Changed in version 2014.7.0: Ability to specify hgfs roots on a per\-remote basis was added. See \fI\%here\fP for more info. .SS \fBhgfs_base\fP .sp New in version 2014.1.0. .sp Default: \fBdefault\fP .sp Defines which branch should be used as the \fBbase\fP environment. Change this if \fI\%hgfs_branch_method\fP is set to \fBbookmarks\fP to specify which bookmark should be used as the \fBbase\fP environment. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C hgfs_base: salt .ft P .fi .UNINDENT .UNINDENT .SS \fBhgfs_env_whitelist\fP .sp New in version 2014.7.0. .sp Default: \fB[]\fP .sp Used to restrict which environments are made available. Can speed up state runs if your hgfs remotes contain many branches/bookmarks/tags. Full names, globs, and regular expressions are supported. If using a regular expression, the expression must match the entire minion ID. .sp If used, only branches/bookmarks/tags which match one of the specified expressions will be exposed as fileserver environments. .sp If used in conjunction with \fI\%hgfs_env_blacklist\fP, then the subset of branches/bookmarks/tags which match the whitelist but do \fInot\fP match the blacklist will be exposed as fileserver environments. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C hgfs_env_whitelist: \- base \- v1.* \- \(aqmybranch\ed+\(aq .ft P .fi .UNINDENT .UNINDENT .SS \fBhgfs_env_blacklist\fP .sp New in version 2014.7.0. .sp Default: \fB[]\fP .sp Used to restrict which environments are made available. Can speed up state runs if your hgfs remotes contain many branches/bookmarks/tags. Full names, globs, and regular expressions are supported. If using a regular expression, the expression must match the entire minion ID. .sp If used, branches/bookmarks/tags which match one of the specified expressions will \fInot\fP be exposed as fileserver environments. .sp If used in conjunction with \fI\%hgfs_env_whitelist\fP, then the subset of branches/bookmarks/tags which match the whitelist but do \fInot\fP match the blacklist will be exposed as fileserver environments. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C hgfs_env_blacklist: \- base \- v1.* \- \(aqmybranch\ed+\(aq .ft P .fi .UNINDENT .UNINDENT .SS svn: Subversion Remote File Server Backend .SS \fBsvnfs_remotes\fP .sp New in version 0.17.0. .sp Default: \fB[]\fP .sp When using the \fBsvn\fP fileserver backend at least one subversion remote needs to be defined. The user running the salt master will need read access to the repo. .sp The repos will be searched in order to find the file requested by a client and the first repo to have the file will return it. The trunk, branches, and tags become environments, with the trunk being the \fBbase\fP environment. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C svnfs_remotes: \- svn://foo.com/svn/myproject .ft P .fi .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 As of 2014.7.0, it is possible to have per\-repo versions of the following configuration parameters: .INDENT 0.0 .IP \(bu 2 \fI\%svnfs_root\fP .IP \(bu 2 \fI\%svnfs_mountpoint\fP .IP \(bu 2 \fI\%svnfs_trunk\fP .IP \(bu 2 \fI\%svnfs_branches\fP .IP \(bu 2 \fI\%svnfs_tags\fP .UNINDENT .sp For example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C svnfs_remotes: \- svn://foo.com/svn/project1 \- svn://foo.com/svn/project2: \- root: salt \- mountpoint: salt://foo/bar/baz \- svn//foo.com/svn/project3: \- root: salt/states \- branches: branch \- tags: tag .ft P .fi .UNINDENT .UNINDENT .UNINDENT .UNINDENT .SS \fBsvnfs_mountpoint\fP .sp New in version 2014.7.0. .sp Default: \fB\(aq\(aq\fP .sp Specifies a path on the salt fileserver which will be prepended to all files served by hgfs. This option can be used in conjunction with \fI\%svnfs_root\fP\&. It can also be configured on a per\-remote basis, see \fI\%here\fP for more info. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C svnfs_mountpoint: salt://foo/bar .ft P .fi .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 The \fBsalt://\fP protocol designation can be left off (in other words, \fBfoo/bar\fP and \fBsalt://foo/bar\fP are equivalent). Assuming a file \fBbaz.sh\fP in the root of an svnfs remote, this file would be served up via \fBsalt://foo/bar/baz.sh\fP\&. .UNINDENT .UNINDENT .SS \fBsvnfs_root\fP .sp New in version 0.17.0. .sp Default: \fB\(aq\(aq\fP .sp Relative path to a subdirectory within the repository from which Salt should begin to serve files. This is useful when there are files in the repository that should not be available to the Salt fileserver. Can be used in conjunction with \fI\%svnfs_mountpoint\fP\&. If used, then from Salt\(aqs perspective the directories above the one specified will be ignored and the relative path will (for the purposes of svnfs) be considered as the root of the repo. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C svnfs_root: somefolder/otherfolder .ft P .fi .UNINDENT .UNINDENT .sp Changed in version 2014.7.0: Ability to specify svnfs roots on a per\-remote basis was added. See \fI\%here\fP for more info. .SS \fBsvnfs_trunk\fP .sp New in version 2014.7.0. .sp Default: \fBtrunk\fP .sp Path relative to the root of the repository where the trunk is located. Can also be configured on a per\-remote basis, see \fI\%here\fP for more info. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C svnfs_trunk: trunk .ft P .fi .UNINDENT .UNINDENT .SS \fBsvnfs_branches\fP .sp New in version 2014.7.0. .sp Default: \fBbranches\fP .sp Path relative to the root of the repository where the branches are located. Can also be configured on a per\-remote basis, see \fI\%here\fP for more info. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C svnfs_branches: branches .ft P .fi .UNINDENT .UNINDENT .SS \fBsvnfs_tags\fP .sp New in version 2014.7.0. .sp Default: \fBtags\fP .sp Path relative to the root of the repository where the tags are located. Can also be configured on a per\-remote basis, see \fI\%here\fP for more info. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C svnfs_tags: tags .ft P .fi .UNINDENT .UNINDENT .SS \fBsvnfs_env_whitelist\fP .sp New in version 2014.7.0. .sp Default: \fB[]\fP .sp Used to restrict which environments are made available. Can speed up state runs if your svnfs remotes contain many branches/tags. Full names, globs, and regular expressions are supported. If using a regular expression, the expression must match the entire minion ID. .sp If used, only branches/tags which match one of the specified expressions will be exposed as fileserver environments. .sp If used in conjunction with \fI\%svnfs_env_blacklist\fP, then the subset of branches/tags which match the whitelist but do \fInot\fP match the blacklist will be exposed as fileserver environments. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C svnfs_env_whitelist: \- base \- v1.* \- \(aqmybranch\ed+\(aq .ft P .fi .UNINDENT .UNINDENT .SS \fBsvnfs_env_blacklist\fP .sp New in version 2014.7.0. .sp Default: \fB[]\fP .sp Used to restrict which environments are made available. Can speed up state runs if your svnfs remotes contain many branches/tags. Full names, globs, and regular expressions are supported. If using a regular expression, the expression must match the entire minion ID. .sp If used, branches/tags which match one of the specified expressions will \fInot\fP be exposed as fileserver environments. .sp If used in conjunction with \fI\%svnfs_env_whitelist\fP, then the subset of branches/tags which match the whitelist but do \fInot\fP match the blacklist will be exposed as fileserver environments. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C svnfs_env_blacklist: \- base \- v1.* \- \(aqmybranch\ed+\(aq .ft P .fi .UNINDENT .UNINDENT .SS minion: MinionFS Remote File Server Backend .SS \fBminionfs_env\fP .sp New in version 2014.7.0. .sp Default: \fBbase\fP .sp Environment from which MinionFS files are made available. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C minionfs_env: minionfs .ft P .fi .UNINDENT .UNINDENT .SS \fBminionfs_mountpoint\fP .sp New in version 2014.7.0. .sp Default: \fB\(aq\(aq\fP .sp Specifies a path on the salt fileserver from which minionfs files are served. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C minionfs_mountpoint: salt://foo/bar .ft P .fi .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 The \fBsalt://\fP protocol designation can be left off (in other words, \fBfoo/bar\fP and \fBsalt://foo/bar\fP are equivalent). .UNINDENT .UNINDENT .SS \fBminionfs_whitelist\fP .sp New in version 2014.7.0. .sp Default: \fB[]\fP .sp Used to restrict which minions\(aq pushed files are exposed via minionfs. If using a regular expression, the expression must match the entire minion ID. .sp If used, only the pushed files from minions which match one of the specified expressions will be exposed. .sp If used in conjunction with \fI\%minionfs_blacklist\fP, then the subset of hosts which match the whitelist but do \fInot\fP match the blacklist will be exposed. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C minionfs_whitelist: \- server01 \- dev* \- \(aqmail\ed+.mydomain.tld\(aq .ft P .fi .UNINDENT .UNINDENT .SS \fBminionfs_blacklist\fP .sp New in version 2014.7.0. .sp Default: \fB[]\fP .sp Used to restrict which minions\(aq pushed files are exposed via minionfs. If using a regular expression, the expression must match the entire minion ID. .sp If used, only the pushed files from minions which match one of the specified expressions will \fInot\fP be exposed. .sp If used in conjunction with \fI\%minionfs_whitelist\fP, then the subset of hosts which match the whitelist but do \fInot\fP match the blacklist will be exposed. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C minionfs_blacklist: \- server01 \- dev* \- \(aqmail\ed+.mydomain.tld\(aq .ft P .fi .UNINDENT .UNINDENT .SS Pillar Configuration .SS \fBpillar_roots\fP .sp Default: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C base: \- /srv/pillar .ft P .fi .UNINDENT .UNINDENT .sp Set the environments and directories used to hold pillar sls data. This configuration is the same as \fI\%file_roots\fP: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C pillar_roots: base: \- /srv/pillar dev: \- /srv/pillar/dev prod: \- /srv/pillar/prod .ft P .fi .UNINDENT .UNINDENT .SS \fBpillar_opts\fP .sp Default: \fBFalse\fP .sp The \fBpillar_opts\fP option adds the master configuration file data to a dict in the pillar called \fBmaster\fP\&. This can be used to set simple configurations in the master config file that can then be used on minions. .sp Note that setting this option to \fBTrue\fP means the master config file will be included in all minion\(aqs pillars. While this makes global configuration of services and systems easy, it may not be desired if sensitive data is stored in the master configuration. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C pillar_opts: False .ft P .fi .UNINDENT .UNINDENT .SS \fBext_pillar\fP .sp The ext_pillar option allows for any number of external pillar interfaces to be called when populating pillar data. The configuration is based on ext_pillar functions. The available ext_pillar functions can be found herein: .sp \fI\%https://github.com/saltstack/salt/blob/develop/salt/pillar\fP .sp By default, the ext_pillar interface is not configured to run. .sp Default: \fB[]\fP .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C ext_pillar: \- hiera: /etc/hiera.yaml \- cmd_yaml: cat /etc/salt/yaml \- reclass: inventory_base_uri: /etc/reclass .ft P .fi .UNINDENT .UNINDENT .sp There are additional details at salt\-pillars .SS \fBext_pillar_first\fP .sp New in version 2015.5.0. .sp Default: \fBFalse\fP .sp This option allows for external pillar sources to be evaluated before \fI\%pillar_roots\fP\&. External pillar data is evaluated separately from \fI\%pillar_roots\fP pillar data, and then both sets of pillar data are merged into a single pillar dictionary, so the value of this config option will have an impact on which key "wins" when there is one of the same name in both the external pillar data and \fI\%pillar_roots\fP pillar data. By setting this option to \fBTrue\fP, ext_pillar keys will be overridden by \fI\%pillar_roots\fP, while leaving it as \fBFalse\fP will allow ext_pillar keys to override those from \fI\%pillar_roots\fP\&. .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 For a while, this config option did not work as specified above, because of a bug in Pillar compilation. This bug has been resolved in version 2016.3.4 and later. .UNINDENT .UNINDENT .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C ext_pillar_first: False .ft P .fi .UNINDENT .UNINDENT .SS \fBpillar_raise_on_missing\fP .sp New in version 2015.5.0. .sp Default: \fBFalse\fP .sp Set this option to \fBTrue\fP to force a \fBKeyError\fP to be raised whenever an attempt to retrieve a named value from pillar fails. When this option is set to \fBFalse\fP, the failed attempt returns an empty string. .SS Git External Pillar (git_pillar) Configuration Options .SS \fBgit_pillar_provider\fP .sp New in version 2015.8.0. .sp Specify the provider to be used for git_pillar. Must be either \fBpygit2\fP or \fBgitpython\fP\&. If unset, then both will be tried in that same order, and the first one with a compatible version installed will be the provider that is used. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C git_pillar_provider: gitpython .ft P .fi .UNINDENT .UNINDENT .SS \fBgit_pillar_base\fP .sp New in version 2015.8.0. .sp Default: \fBmaster\fP .sp If the desired branch matches this value, and the environment is omitted from the git_pillar configuration, then the environment for that git_pillar remote will be \fBbase\fP\&. For example, in the configuration below, the \fBfoo\fP branch/tag would be assigned to the \fBbase\fP environment, while \fBbar\fP would be mapped to the \fBbar\fP environment. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C git_pillar_base: foo ext_pillar: \- git: \- foo https://mygitserver/git\-pillar.git \- bar https://mygitserver/git\-pillar.git .ft P .fi .UNINDENT .UNINDENT .SS \fBgit_pillar_branch\fP .sp New in version 2015.8.0. .sp Default: \fBmaster\fP .sp If the branch is omitted from a git_pillar remote, then this branch will be used instead. For example, in the configuration below, the first two remotes would use the \fBpillardata\fP branch/tag, while the third would use the \fBfoo\fP branch/tag. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C git_pillar_branch: pillardata ext_pillar: \- git: \- https://mygitserver/pillar1.git \- https://mygitserver/pillar2.git: \- root: pillar \- foo https://mygitserver/pillar3.git .ft P .fi .UNINDENT .UNINDENT .SS \fBgit_pillar_env\fP .sp New in version 2015.8.0. .sp Default: \fB\(aq\(aq\fP (unset) .sp Environment to use for git_pillar remotes. This is normally derived from the branch/tag (or from a per\-remote \fBenv\fP parameter), but if set this will override the process of deriving the env from the branch/tag name. For example, in the configuration below the \fBfoo\fP branch would be assigned to the \fBbase\fP environment, while the \fBbar\fP branch would need to explicitly have \fBbar\fP configured as it\(aqs environment to keep it from also being mapped to the \fBbase\fP environment. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C git_pillar_env: base ext_pillar: \- git: \- foo https://mygitserver/git\-pillar.git \- bar https://mygitserver/git\-pillar.git: \- env: bar .ft P .fi .UNINDENT .UNINDENT .sp For this reason, this option is recommended to be left unset, unless the use case calls for all (or almost all) of the git_pillar remotes to use the same environment irrespective of the branch/tag being used. .SS \fBgit_pillar_root\fP .sp New in version 2015.8.0. .sp Default: \fB\(aq\(aq\fP .sp Path relative to the root of the repository where the git_pillar top file and SLS files are located. In the below configuration, the pillar top file and SLS files would be looked for in a subdirectory called \fBpillar\fP\&. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C git_pillar_root: pillar ext_pillar: \- git: \- master https://mygitserver/pillar1.git \- master https://mygitserver/pillar2.git .ft P .fi .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 This is a global option. If only one or two repos need to have their files sourced from a subdirectory, then \fI\%git_pillar_root\fP can be omitted and the root can be specified on a per\-remote basis, like so: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C ext_pillar: \- git: \- master https://mygitserver/pillar1.git \- master https://mygitserver/pillar2.git: \- root: pillar .ft P .fi .UNINDENT .UNINDENT .sp In this example, for the first remote the top file and SLS files would be looked for in the root of the repository, while in the second remote the pillar data would be retrieved from the \fBpillar\fP subdirectory. .UNINDENT .UNINDENT .SS \fBgit_pillar_ssl_verify\fP .sp New in version 2015.8.0. .sp Changed in version 2016.11.0. .sp Default: \fBFalse\fP .sp Specifies whether or not to ignore SSL certificate errors when contacting the remote repository. The \fBFalse\fP setting is useful if you\(aqre using a git repo that uses a self\-signed certificate. However, keep in mind that setting this to anything other \fBTrue\fP is a considered insecure, and using an SSH\-based transport (if available) may be a better option. .sp In the 2016.11.0 release, the default config value changed from \fBFalse\fP to \fBTrue\fP\&. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C git_pillar_ssl_verify: True .ft P .fi .UNINDENT .UNINDENT .SS \fBgit_pillar_global_lock\fP .sp New in version 2015.8.9. .sp Default: \fBTrue\fP .sp When set to \fBFalse\fP, if there is an update/checkout lock for a git_pillar remote and the pid written to it is not running on the master, the lock file will be automatically cleared and a new lock will be obtained. When set to \fBTrue\fP, Salt will simply log a warning when there is an lock present. .sp On single\-master deployments, disabling this option can help automatically deal with instances where the master was shutdown/restarted during the middle of a git_pillar update/checkout, leaving a lock in place. .sp However, on multi\-master deployments with the git_pillar cachedir shared via \fI\%GlusterFS\fP, nfs, or another network filesystem, it is strongly recommended not to disable this option as doing so will cause lock files to be removed if they were created by a different master. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C # Disable global lock git_pillar_global_lock: False .ft P .fi .UNINDENT .UNINDENT .SS Git External Pillar Authentication Options .sp These parameters only currently apply to the \fBpygit2\fP \fI\%git_pillar_provider\fP\&. Authentication works the same as it does in gitfs, as outlined in the GitFS Walkthrough, though the global configuration options are named differently to reflect that they are for git_pillar instead of gitfs. .SS \fBgit_pillar_user\fP .sp New in version 2015.8.0. .sp Default: \fB\(aq\(aq\fP .sp Along with \fI\%git_pillar_password\fP, is used to authenticate to HTTPS remotes. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C git_pillar_user: git .ft P .fi .UNINDENT .UNINDENT .SS \fBgit_pillar_password\fP .sp New in version 2015.8.0. .sp Default: \fB\(aq\(aq\fP .sp Along with \fI\%git_pillar_user\fP, is used to authenticate to HTTPS remotes. This parameter is not required if the repository does not use authentication. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C git_pillar_password: mypassword .ft P .fi .UNINDENT .UNINDENT .SS \fBgit_pillar_insecure_auth\fP .sp New in version 2015.8.0. .sp Default: \fBFalse\fP .sp By default, Salt will not authenticate to an HTTP (non\-HTTPS) remote. This parameter enables authentication over HTTP. \fBEnable this at your own risk.\fP .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C git_pillar_insecure_auth: True .ft P .fi .UNINDENT .UNINDENT .SS \fBgit_pillar_pubkey\fP .sp New in version 2015.8.0. .sp Default: \fB\(aq\(aq\fP .sp Along with \fI\%git_pillar_privkey\fP (and optionally \fI\%git_pillar_passphrase\fP), is used to authenticate to SSH remotes. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C git_pillar_pubkey: /path/to/key.pub .ft P .fi .UNINDENT .UNINDENT .SS \fBgit_pillar_privkey\fP .sp New in version 2015.8.0. .sp Default: \fB\(aq\(aq\fP .sp Along with \fI\%git_pillar_pubkey\fP (and optionally \fI\%git_pillar_passphrase\fP), is used to authenticate to SSH remotes. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C git_pillar_privkey: /path/to/key .ft P .fi .UNINDENT .UNINDENT .SS \fBgit_pillar_passphrase\fP .sp New in version 2015.8.0. .sp Default: \fB\(aq\(aq\fP .sp This parameter is optional, required only when the SSH key being used to authenticate is protected by a passphrase. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C git_pillar_passphrase: mypassphrase .ft P .fi .UNINDENT .UNINDENT .SS Pillar Merging Options .SS \fBpillar_source_merging_strategy\fP .sp New in version 2014.7.0. .sp Default: \fBsmart\fP .sp The pillar_source_merging_strategy option allows you to configure merging strategy between different sources. It accepts 5 values: .INDENT 0.0 .IP \(bu 2 \fBnone\fP: .UNINDENT .sp New in version 2016.3.4: It will not do any merging at all and only parse the pillar data from the passed environment and \(aqbase\(aq if no environment was specified. .INDENT 0.0 .IP \(bu 2 \fBrecurse\fP: .sp it will merge recursively mapping of data. For example, theses 2 sources: .INDENT 2.0 .INDENT 3.5 .sp .nf .ft C foo: 42 bar: element1: True .ft P .fi .UNINDENT .UNINDENT .INDENT 2.0 .INDENT 3.5 .sp .nf .ft C bar: element2: True baz: quux .ft P .fi .UNINDENT .UNINDENT .sp will be merged as: .INDENT 2.0 .INDENT 3.5 .sp .nf .ft C foo: 42 bar: element1: True element2: True baz: quux .ft P .fi .UNINDENT .UNINDENT .IP \(bu 2 \fBaggregate\fP: .sp instructs aggregation of elements between sources that use the #!yamlex renderer. .sp For example, these two documents: .INDENT 2.0 .INDENT 3.5 .sp .nf .ft C #!yamlex foo: 42 bar: !aggregate { element1: True } baz: !aggregate quux .ft P .fi .UNINDENT .UNINDENT .INDENT 2.0 .INDENT 3.5 .sp .nf .ft C #!yamlex bar: !aggregate { element2: True } baz: !aggregate quux2 .ft P .fi .UNINDENT .UNINDENT .sp will be merged as: .INDENT 2.0 .INDENT 3.5 .sp .nf .ft C foo: 42 bar: element1: True element2: True baz: \- quux \- quux2 .ft P .fi .UNINDENT .UNINDENT .IP \(bu 2 \fBoverwrite\fP: .sp Will use the behaviour of the 2014.1 branch and earlier. .sp Overwrites elements according the order in which they are processed. .sp First pillar processed: .INDENT 2.0 .INDENT 3.5 .sp .nf .ft C A: first_key: blah second_key: blah .ft P .fi .UNINDENT .UNINDENT .sp Second pillar processed: .INDENT 2.0 .INDENT 3.5 .sp .nf .ft C A: third_key: blah fourth_key: blah .ft P .fi .UNINDENT .UNINDENT .sp will be merged as: .INDENT 2.0 .INDENT 3.5 .sp .nf .ft C A: third_key: blah fourth_key: blah .ft P .fi .UNINDENT .UNINDENT .IP \(bu 2 \fBsmart\fP (default): .sp Guesses the best strategy based on the "renderer" setting. .UNINDENT .SS \fBpillar_merge_lists\fP .sp New in version 2015.8.0. .sp Default: \fBFalse\fP .sp Recursively merge lists by aggregating them instead of replacing them. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C pillar_merge_lists: False .ft P .fi .UNINDENT .UNINDENT .SS Pillar Cache Options .SS \fBpillar_cache\fP .sp New in version 2015.8.8. .sp Default: \fBFalse\fP .sp A master can cache pillars locally to bypass the expense of having to render them for each minion on every request. This feature should only be enabled in cases where pillar rendering time is known to be unsatisfactory and any attendant security concerns about storing pillars in a master cache have been addressed. .sp When enabling this feature, be certain to read through the additional \fBpillar_cache_*\fP configuration options to fully understand the tunable parameters and their implications. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C pillar_cache: False .ft P .fi .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 Setting \fBpillar_cache: True\fP has no effect on targeting minions with pillar\&. .UNINDENT .UNINDENT .SS \fBpillar_cache_ttl\fP .sp New in version 2015.8.8. .sp Default: \fB3600\fP .sp If and only if a master has set \fBpillar_cache: True\fP, the cache TTL controls the amount of time, in seconds, before the cache is considered invalid by a master and a fresh pillar is recompiled and stored. .SS \fBpillar_cache_backend\fP .sp New in version 2015.8.8. .sp Default: \fBdisk\fP .sp If an only if a master has set \fBpillar_cache: True\fP, one of several storage providers can be utilized: .INDENT 0.0 .IP \(bu 2 \fBdisk\fP (default): .sp The default storage backend. This caches rendered pillars to the master cache. Rendered pillars are serialized and deserialized as \fBmsgpack\fP structures for speed. Note that pillars are stored UNENCRYPTED. Ensure that the master cache has permissions set appropriately (sane defaults are provided). .IP \(bu 2 \fBmemory\fP [EXPERIMENTAL]: .sp An optional backend for pillar caches which uses a pure\-Python in\-memory data structure for maximal performance. There are several caveats, however. First, because each master worker contains its own in\-memory cache, there is no guarantee of cache consistency between minion requests. This works best in situations where the pillar rarely if ever changes. Secondly, and perhaps more importantly, this means that unencrypted pillars will be accessible to any process which can examine the memory of the \fBsalt\-master\fP! This may represent a substantial security risk. .UNINDENT .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C pillar_cache_backend: disk .ft P .fi .UNINDENT .UNINDENT .SS Syndic Server Settings .sp A Salt syndic is a Salt master used to pass commands from a higher Salt master to minions below the syndic. Using the syndic is simple. If this is a master that will have syndic servers(s) below it, set the \fBorder_masters\fP setting to \fBTrue\fP\&. .sp If this is a master that will be running a syndic daemon for passthrough the \fBsyndic_master\fP setting needs to be set to the location of the master server. .sp Do not forget that, in other words, it means that it shares with the local minion its ID and PKI directory. .SS \fBorder_masters\fP .sp Default: \fBFalse\fP .sp Extra data needs to be sent with publications if the master is controlling a lower level master via a syndic minion. If this is the case the order_masters value must be set to True .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C order_masters: False .ft P .fi .UNINDENT .UNINDENT .SS \fBsyndic_master\fP .sp Changed in version 2016.3.5,2016.11.1: Set default higher level master address. .sp Default: \fBmasterofmasters\fP .sp If this master will be running the \fBsalt\-syndic\fP to connect to a higher level master, specify the higher level master with this configuration value. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C syndic_master: masterofmasters .ft P .fi .UNINDENT .UNINDENT .sp You can optionally connect a syndic to multiple higher level masters by setting the \fBsyndic_master\fP value to a list: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C syndic_master: \- masterofmasters1 \- masterofmasters2 .ft P .fi .UNINDENT .UNINDENT .sp Each higher level master must be set up in a multi\-master configuration. .SS \fBsyndic_master_port\fP .sp Default: \fB4506\fP .sp If this master will be running the \fBsalt\-syndic\fP to connect to a higher level master, specify the higher level master port with this configuration value. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C syndic_master_port: 4506 .ft P .fi .UNINDENT .UNINDENT .SS \fBsyndic_pidfile\fP .sp Default: \fB/var/run/salt\-syndic.pid\fP .sp If this master will be running the \fBsalt\-syndic\fP to connect to a higher level master, specify the pidfile of the syndic daemon. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C syndic_pidfile: /var/run/syndic.pid .ft P .fi .UNINDENT .UNINDENT .SS \fBsyndic_log_file\fP .sp Default: \fB/var/log/salt/syndic\fP .sp If this master will be running the \fBsalt\-syndic\fP to connect to a higher level master, specify the log file of the syndic daemon. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C syndic_log_file: /var/log/salt\-syndic.log .ft P .fi .UNINDENT .UNINDENT .SS \fBsyndic_failover\fP .sp New in version 2016.3.0. .sp Default: \fBrandom\fP .sp The behaviour of the multi\-syndic when connection to a master of masters failed. Can specify \fBrandom\fP (default) or \fBordered\fP\&. If set to \fBrandom\fP, masters will be iterated in random order. If \fBordered\fP is specified, the configured order will be used. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C syndic_failover: random .ft P .fi .UNINDENT .UNINDENT .SS \fBsyndic_wait\fP .sp Default: \fB5\fP .sp The number of seconds for the salt client to wait for additional syndics to check in with their lists of expected minions before giving up. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C syndic_wait: 5 .ft P .fi .UNINDENT .UNINDENT .SS Peer Publish Settings .sp Salt minions can send commands to other minions, but only if the minion is allowed to. By default "Peer Publication" is disabled, and when enabled it is enabled for specific minions and specific commands. This allows secure compartmentalization of commands based on individual minions. .SS \fBpeer\fP .sp Default: \fB{}\fP .sp The configuration uses regular expressions to match minions and then a list of regular expressions to match functions. The following will allow the minion authenticated as foo.example.com to execute functions from the test and pkg modules. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C peer: foo.example.com: \- test.* \- pkg.* .ft P .fi .UNINDENT .UNINDENT .sp This will allow all minions to execute all commands: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C peer: .*: \- .* .ft P .fi .UNINDENT .UNINDENT .sp This is not recommended, since it would allow anyone who gets root on any single minion to instantly have root on all of the minions! .sp By adding an additional layer you can limit the target hosts in addition to the accessible commands: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C peer: foo.example.com: \(aqdb*\(aq: \- test.* \- pkg.* .ft P .fi .UNINDENT .UNINDENT .SS \fBpeer_run\fP .sp Default: \fB{}\fP .sp The peer_run option is used to open up runners on the master to access from the minions. The peer_run configuration matches the format of the peer configuration. .sp The following example would allow foo.example.com to execute the manage.up runner: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C peer_run: foo.example.com: \- manage.up .ft P .fi .UNINDENT .UNINDENT .SS Master Logging Settings .SS \fBlog_file\fP .sp Default: \fB/var/log/salt/master\fP .sp The master log can be sent to a regular file, local path name, or network location. See also \fBlog_file\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: 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 messages to send to the console. See also \fBlog_level\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. See also \fBlog_level_logfile\fP\&. When it is not set explicitly it will inherit the level set by \fBlog_level\fP option. .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. See also \fBlog_datefmt\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. See also \fBlog_datefmt_logfile\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. See also \fBlog_fmt_console\fP\&. .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 Log colors are enabled in \fBlog_fmt_console\fP rather than the \fI\%color\fP config since the logging system is loaded before the master config. .sp Console log colors are specified by these additional formatters: .sp %(colorlevel)s %(colorname)s %(colorprocess)s %(colormsg)s .sp Since it is desirable to include the surrounding brackets, \(aq[\(aq and \(aq]\(aq, in the coloring of the messages, these color formatters also include padding as well. Color LogRecord attributes are only available for console logging. .UNINDENT .UNINDENT .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C log_fmt_console: \(aq%(colorlevel)s %(colormsg)s\(aq 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)03d [%(name)\-17s][%(levelname)\-8s] %(message)s\fP .sp The format of the log file logging messages. See also \fBlog_fmt_logfile\fP\&. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C log_fmt_logfile: \(aq%(asctime)s,%(msecs)03d [%(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. See also \fBlog_granular_levels\fP\&. .SS Node Groups .sp Default: \fB{}\fP .sp Node groups allow for logical groupings of minion nodes. A group consists of a group name and a compound target. .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 group3: \(aqG@os:Debian and N@group1\(aq group4: \- \(aqG@foo:bar\(aq \- \(aqor\(aq \- \(aqG@foo:baz\(aq .ft P .fi .UNINDENT .UNINDENT .sp More information on using nodegroups can be found here\&. .SS Range Cluster Settings .SS \fBrange_server\fP .sp Default: \fB\(aqrange:80\(aq\fP .sp The range server (and optional port) that serves your cluster information \fI\%https://github.com/ytoolshed/range/wiki/%22yamlfile%22\-module\-file\-spec\fP .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C range_server: range:80 .ft P .fi .UNINDENT .UNINDENT .SS Include Configuration .SS \fBdefault_include\fP .sp Default: \fBmaster.d/*.conf\fP .sp The master can include configuration from other files. Per default the master will automatically include all config files from \fBmaster.d/*.conf\fP where \fBmaster.d\fP is relative to the directory of the master configuration file. .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 Salt creates files in the \fBmaster.d\fP directory for its own use. These files are prefixed with an underscore. A common example of this is the \fB_schedule.conf\fP file. .UNINDENT .UNINDENT .SS \fBinclude\fP .sp Default: \fBnot defined\fP .sp The master can include configuration from other files. To enable this, pass a list of paths to this option. The paths can be either relative or absolute; if relative, they are considered to be relative to the directory the main minion configuration file lives in. Paths can make use of shell\-style globbing. If no files are matched by a path passed to this option then the master will log a warning message. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C # Include files from a master.d directory in the same # directory as the master config file include: master.d/* # Include a single extra file into the configuration include: /etc/roles/webserver # Include several files and the master.d directory include: \- extra_config \- master.d/* \- /etc/roles/webserver .ft P .fi .UNINDENT .UNINDENT .SS Windows Software Repo Settings .SS \fBwinrepo_provider\fP .sp New in version 2015.8.0. .sp Specify the provider to be used for winrepo. Must be either \fBpygit2\fP or \fBgitpython\fP\&. If unset, then both will be tried in that same order, and the first one with a compatible version installed will be the provider that is used. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C winrepo_provider: gitpython .ft P .fi .UNINDENT .UNINDENT .SS \fBwinrepo_dir\fP .sp Changed in version 2015.8.0: Renamed from \fBwin_repo\fP to \fBwinrepo_dir\fP\&. .sp Default: \fB/srv/salt/win/repo\fP .sp Location on the master where the \fI\%winrepo_remotes\fP are checked out for pre\-2015.8.0 minions. 2015.8.0 and later minions use \fI\%winrepo_remotes_ng\fP instead. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C winrepo_dir: /srv/salt/win/repo .ft P .fi .UNINDENT .UNINDENT .SS \fBwinrepo_dir_ng\fP .sp New in version 2015.8.0: A new ng repo was added. .sp Default: \fB/srv/salt/win/repo\-ng\fP .sp Location on the master where the \fI\%winrepo_remotes_ng\fP are checked out for 2015.8.0 and later minions. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C winrepo_dir_ng: /srv/salt/win/repo\-ng .ft P .fi .UNINDENT .UNINDENT .SS \fBwinrepo_cachefile\fP .sp Changed in version 2015.8.0: Renamed from \fBwin_repo_mastercachefile\fP to \fBwinrepo_cachefile\fP .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 2015.8.0 and later minions do not use this setting since the cachefile is now located on the minion. .UNINDENT .UNINDENT .sp Default: \fBwinrepo.p\fP .sp Path relative to \fI\%winrepo_dir\fP where the winrepo cache should be created. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C winrepo_cachefile: winrepo.p .ft P .fi .UNINDENT .UNINDENT .SS \fBwinrepo_remotes\fP .sp Changed in version 2015.8.0: Renamed from \fBwin_gitrepos\fP to \fBwinrepo_remotes\fP\&. .sp Default: \fB[\(aqhttps://github.com/saltstack/salt\-winrepo.git\(aq]\fP .sp List of git repositories to checkout and include in the winrepo for pre\-2015.8.0 minions. 2015.8.0 and later minions use \fI\%winrepo_remotes_ng\fP instead. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C winrepo_remotes: \- https://github.com/saltstack/salt\-winrepo.git .ft P .fi .UNINDENT .UNINDENT .sp To specify a specific revision of the repository, prepend a commit ID to the URL of the repository: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C winrepo_remotes: \- \(aq https://github.com/saltstack/salt\-winrepo.git\(aq .ft P .fi .UNINDENT .UNINDENT .sp Replace \fB\fP with the SHA1 hash of a commit ID. Specifying a commit ID is useful in that it allows one to revert back to a previous version in the event that an error is introduced in the latest revision of the repo. .SS \fBwinrepo_remotes_ng\fP .sp New in version 2015.8.0: A new ng repo was added. .sp Default: \fB[\(aqhttps://github.com/saltstack/salt\-winrepo\-ng.git\(aq]\fP .sp List of git repositories to checkout and include in the winrepo for 2015.8.0 and later minions. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C winrepo_remotes_ng: \- https://github.com/saltstack/salt\-winrepo\-ng.git .ft P .fi .UNINDENT .UNINDENT .sp To specify a specific revision of the repository, prepend a commit ID to the URL of the repository: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C winrepo_remotes: \- \(aq https://github.com/saltstack/salt\-winrepo\-ng.git\(aq .ft P .fi .UNINDENT .UNINDENT .sp Replace \fB\fP with the SHA1 hash of a commit ID. Specifying a commit ID is useful in that it allows one to revert back to a previous version in the event that an error is introduced in the latest revision of the repo. .SS \fBwinrepo_branch\fP .sp New in version 2015.8.0. .sp Default: \fBmaster\fP .sp If the branch is omitted from a winrepo remote, then this branch will be used instead. For example, in the configuration below, the first two remotes would use the \fBwinrepo\fP branch/tag, while the third would use the \fBfoo\fP branch/tag. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C winrepo_branch: winrepo ext_pillar: \- git: \- https://mygitserver/winrepo1.git \- https://mygitserver/winrepo2.git: \- foo https://mygitserver/winrepo3.git .ft P .fi .UNINDENT .UNINDENT .SS \fBwinrepo_ssl_verify\fP .sp New in version 2015.8.0. .sp Changed in version 2016.11.0. .sp Default: \fBFalse\fP .sp Specifies whether or not to ignore SSL certificate errors when contacting the remote repository. The \fBFalse\fP setting is useful if you\(aqre using a git repo that uses a self\-signed certificate. However, keep in mind that setting this to anything other \fBTrue\fP is a considered insecure, and using an SSH\-based transport (if available) may be a better option. .sp In the 2016.11.0 release, the default config value changed from \fBFalse\fP to \fBTrue\fP\&. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C winrepo_ssl_verify: True .ft P .fi .UNINDENT .UNINDENT .SS Winrepo Authentication Options .sp These parameters only currently apply to the \fBpygit2\fP \fI\%winrepo_provider\fP\&. Authentication works the same as it does in gitfs, as outlined in the GitFS Walkthrough, though the global configuration options are named differently to reflect that they are for winrepo instead of gitfs. .SS \fBwinrepo_user\fP .sp New in version 2015.8.0. .sp Default: \fB\(aq\(aq\fP .sp Along with \fI\%winrepo_password\fP, is used to authenticate to HTTPS remotes. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C winrepo_user: git .ft P .fi .UNINDENT .UNINDENT .SS \fBwinrepo_password\fP .sp New in version 2015.8.0. .sp Default: \fB\(aq\(aq\fP .sp Along with \fI\%winrepo_user\fP, is used to authenticate to HTTPS remotes. This parameter is not required if the repository does not use authentication. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C winrepo_password: mypassword .ft P .fi .UNINDENT .UNINDENT .SS \fBwinrepo_insecure_auth\fP .sp New in version 2015.8.0. .sp Default: \fBFalse\fP .sp By default, Salt will not authenticate to an HTTP (non\-HTTPS) remote. This parameter enables authentication over HTTP. \fBEnable this at your own risk.\fP .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C winrepo_insecure_auth: True .ft P .fi .UNINDENT .UNINDENT .SS \fBwinrepo_pubkey\fP .sp New in version 2015.8.0. .sp Default: \fB\(aq\(aq\fP .sp Along with \fI\%winrepo_privkey\fP (and optionally \fI\%winrepo_passphrase\fP), is used to authenticate to SSH remotes. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C winrepo_pubkey: /path/to/key.pub .ft P .fi .UNINDENT .UNINDENT .SS \fBwinrepo_privkey\fP .sp New in version 2015.8.0. .sp Default: \fB\(aq\(aq\fP .sp Along with \fI\%winrepo_pubkey\fP (and optionally \fI\%winrepo_passphrase\fP), is used to authenticate to SSH remotes. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C winrepo_privkey: /path/to/key .ft P .fi .UNINDENT .UNINDENT .SS \fBwinrepo_passphrase\fP .sp New in version 2015.8.0. .sp Default: \fB\(aq\(aq\fP .sp This parameter is optional, required only when the SSH key being used to authenticate is protected by a passphrase. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C winrepo_passphrase: mypassphrase .ft P .fi .UNINDENT .UNINDENT .SS Configuring the Salt Minion .sp The Salt system is amazingly simple and easy to configure. The two components of the Salt system each have a respective configuration file. The \fBsalt\-master\fP is configured via the master configuration file, and the \fBsalt\-minion\fP is configured via the minion configuration file. .sp \fBSEE ALSO:\fP .INDENT 0.0 .INDENT 3.5 example minion configuration file .UNINDENT .UNINDENT .sp The Salt Minion configuration is very simple. Typically, the only value that needs to be set is the master value so the minion knows where to locate its master. .sp By default, the salt\-minion configuration will be in \fB/etc/salt/minion\fP\&. A notable exception is FreeBSD, where the configuration will be in \fB/usr/local/etc/salt/minion\fP\&. .SS Minion Primary Configuration .SS \fBmaster\fP .sp Default: \fBsalt\fP .sp The hostname or ipv4 of the master. .sp Default: \fBsalt\fP .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C master: salt .ft P .fi .UNINDENT .UNINDENT .sp The option can can also be set to a list of masters, enabling multi\-master mode. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C master: \- address1 \- address2 .ft P .fi .UNINDENT .UNINDENT .sp Changed in version 2014.7.0: The master can be dynamically configured. The \fI\%master\fP value can be set to an module function which will be executed and will assume that the returning value is the ip or hostname of the desired master. If a function is being specified, then the \fI\%master_type\fP option must be set to \fBfunc\fP, to tell the minion that the value is a function to be run and not a fully\-qualified domain name. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C master: module.function master_type: func .ft P .fi .UNINDENT .UNINDENT .sp In addition, instead of using multi\-master mode, the minion can be configured to use the list of master addresses as a failover list, trying the first address, then the second, etc. until the minion successfully connects. To enable this behavior, set \fI\%master_type\fP to \fBfailover\fP: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C master: \- address1 \- address2 master_type: failover .ft P .fi .UNINDENT .UNINDENT .SS \fBmaster_type\fP .sp New in version 2014.7.0. .sp Default: \fBstr\fP .sp The type of the \fI\%master\fP variable. Can be \fBstr\fP, \fBfailover\fP, \fBfunc\fP or \fBdisable\fP\&. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C master_type: failover .ft P .fi .UNINDENT .UNINDENT .sp If this option is set to \fBfailover\fP, \fI\%master\fP must be a list of master addresses. The minion will then try each master in the order specified in the list until it successfully connects. \fI\%master_alive_interval\fP must also be set, this determines how often the minion will verify the presence of the master. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C master_type: func .ft P .fi .UNINDENT .UNINDENT .sp If the master needs to be dynamically assigned by executing a function instead of reading in the static master value, set this to \fBfunc\fP\&. This can be used to manage the minion\(aqs master setting from an execution module. By simply changing the algorithm in the module to return a new master ip/fqdn, restart the minion and it will connect to the new master. .sp As of version 2016.11.0 this option can be set to \fBdisable\fP and the minion will never attempt to talk to the master. This is useful for running a masterless minion daemon. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C master_type: disable .ft P .fi .UNINDENT .UNINDENT .SS \fBmax_event_size\fP .sp New in version 2014.7.0. .sp Default: \fB1048576\fP .sp Passing very large events can cause the minion to consume large amounts of memory. This value tunes the maximum size of a message allowed onto the minion event bus. The value is expressed in bytes. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C max_event_size: 1048576 .ft P .fi .UNINDENT .UNINDENT .SS \fBmaster_failback\fP .sp New in version 2016.3.0. .sp Default: \fBFalse\fP .sp If the minion is in multi\-master mode and the :conf_minion\(gamaster_type\(ga configuration option is set to \fBfailover\fP, this setting can be set to \fBTrue\fP to force the minion to fail back to the first master in the list if the first master is back online. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C master_failback: False .ft P .fi .UNINDENT .UNINDENT .SS \fBmaster_failback_interval\fP .sp New in version 2016.3.0. .sp Default: \fB0\fP .sp If the minion is in multi\-master mode, the :conf_minion\(gamaster_type\(ga configuration is set to \fBfailover\fP, and the \fBmaster_failback\fP option is enabled, the master failback interval can be set to ping the top master with this interval, in seconds. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C master_failback_interval: 0 .ft P .fi .UNINDENT .UNINDENT .SS \fBmaster_alive_interval\fP .sp Default: \fB0\fP .sp Configures how often, in seconds, the minion will verify that the current master is alive and responding. The minion will try to establish a connection to the next master in the list if it finds the existing one is dead. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C master_alive_interval: 30 .ft P .fi .UNINDENT .UNINDENT .SS \fBmaster_shuffle\fP .sp New in version 2014.7.0. .sp Default: \fBFalse\fP .sp If \fI\%master\fP is a list of addresses and :conf_minion\(gamaster_type\(ga is \fBfailover\fP, shuffle them before trying to connect to distribute the minions over all available masters. This uses Python\(aqs \fI\%random.shuffle\fP method. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C master_shuffle: True .ft P .fi .UNINDENT .UNINDENT .SS \fBrandom_master\fP .sp Default: \fBFalse\fP .sp If \fI\%master\fP is a list of addresses, shuffle them before trying to connect to distribute the minions over all available masters. This uses Python\(aqs \fI\%random.randint\fP method. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C random_master: True .ft P .fi .UNINDENT .UNINDENT .SS \fBretry_dns\fP .sp Default: \fB30\fP .sp Set the number of seconds to wait before attempting to resolve the master hostname if name resolution fails. Defaults to 30 seconds. Set to zero if the minion should shutdown and not retry. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C retry_dns: 30 .ft P .fi .UNINDENT .UNINDENT .SS \fBmaster_port\fP .sp Default: \fB4506\fP .sp The port of the master ret server, this needs to coincide with the ret_port option on the Salt master. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C master_port: 4506 .ft P .fi .UNINDENT .UNINDENT .SS \fBuser\fP .sp Default: \fBroot\fP .sp The user to run the Salt processes .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C user: root .ft P .fi .UNINDENT .UNINDENT .SS \fBsudo_user\fP .sp Default: \fB\(aq\(aq\fP .sp The user to run salt remote execution commands as via sudo. If this option is enabled then sudo will be used to change the active user executing the remote command. If enabled the user will need to be allowed access via the sudoers file for the user that the salt minion is configured to run as. The most common option would be to use the root user. If this option is set the \fBuser\fP option should also be set to a non\-root user. If migrating from a root minion to a non root minion the minion cache should be cleared and the minion pki directory will need to be changed to the ownership of the new user. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C sudo_user: root .ft P .fi .UNINDENT .UNINDENT .SS \fBpidfile\fP .sp Default: \fB/var/run/salt\-minion.pid\fP .sp The location of the daemon\(aqs process ID file .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C pidfile: /var/run/salt\-minion.pid .ft P .fi .UNINDENT .UNINDENT .SS \fBroot_dir\fP .sp Default: \fB/\fP .sp This directory is prepended to the following options: \fI\%pki_dir\fP, \fI\%cachedir\fP, \fI\%log_file\fP, \fI\%sock_dir\fP, and \fBpidfile\fP\&. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C root_dir: / .ft P .fi .UNINDENT .UNINDENT .SS \fBconf_file\fP .sp Default: \fB/etc/salt/minion\fP .sp The path to the minion\(aqs configuration file. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C conf_file: /etc/salt/minion .ft P .fi .UNINDENT .UNINDENT .SS \fBpki_dir\fP .sp Default: \fB/etc/salt/pki/minion\fP .sp The directory used to store the minion\(aqs public and private keys. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C pki_dir: /etc/salt/pki/minion .ft P .fi .UNINDENT .UNINDENT .SS \fBid\fP .sp Default: the system\(aqs hostname .sp \fBSEE ALSO:\fP .INDENT 0.0 .INDENT 3.5 Salt Walkthrough .sp The \fBSetting up a Salt Minion\fP section contains detailed information on how the hostname is determined. .UNINDENT .UNINDENT .sp Explicitly declare the id for this minion to use. Since Salt uses detached ids it is possible to run multiple minions on the same machine but with different ids. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C id: foo.bar.com .ft P .fi .UNINDENT .UNINDENT .SS \fBminion_id_caching\fP .sp New in version 0.17.2. .sp Default: \fBTrue\fP .sp Caches the minion id to a file when the minion\(aqs .nf :minion_conf:\(gaid\(ga .fi is not statically defined in the minion config. This setting prevents potential problems when automatic minion id resolution changes, which can cause the minion to lose connection with the master. To turn off minion id caching, set this config to \fBFalse\fP\&. .sp For more information, please see \fI\%Issue #7558\fP and \fI\%Pull Request #8488\fP\&. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C minion_id_caching: True .ft P .fi .UNINDENT .UNINDENT .SS \fBappend_domain\fP .sp Default: \fBNone\fP .sp Append a domain to a hostname in the event that it does not exist. This is useful for systems where \fBsocket.getfqdn()\fP does not actually result in a FQDN (for instance, Solaris). .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C append_domain: foo.org .ft P .fi .UNINDENT .UNINDENT .SS \fBcachedir\fP .sp Default: \fB/var/cache/salt/minion\fP .sp The location for minion cache data. .sp This directory may contain sensitive data and should be protected accordingly. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C cachedir: /var/cache/salt/minion .ft P .fi .UNINDENT .UNINDENT .SS \fBappend_minionid_config_dirs\fP .sp Default: \fB[]\fP (the empty list) for regular minions, \fB[\(aqcachedir\(aq]\fP for proxy minions. .sp Append minion_id to these configuration directories. Helps with multiple proxies and minions running on the same machine. Allowed elements in the list: \fBpki_dir\fP, \fBcachedir\fP, \fBextension_modules\fP\&. Normally not needed unless running several proxies and/or minions on the same machine. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C append_minionid_config_dirs: \- pki_dir \- cachedir .ft P .fi .UNINDENT .UNINDENT .SS \fBverify_env\fP .sp Default: \fBTrue\fP .sp Verify and set permissions on configuration directories at startup. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C verify_env: True .ft P .fi .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 When set to \fBTrue\fP the verify_env option requires WRITE access to the configuration directory (/etc/salt/). In certain situations such as mounting /etc/salt/ as read\-only for templating this will create a stack trace when \fBstate.apply\fP is called. .UNINDENT .UNINDENT .SS \fBcache_jobs\fP .sp Default: \fBFalse\fP .sp The minion can locally cache the return data from jobs sent to it, this can be a good way to keep track of the minion side of the jobs the minion has executed. By default this feature is disabled, to enable set cache_jobs to \fBTrue\fP\&. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C cache_jobs: False .ft P .fi .UNINDENT .UNINDENT .SS \fBgrains\fP .sp Default: (empty) .sp \fBSEE ALSO:\fP .INDENT 0.0 .INDENT 3.5 static\-custom\-grains .UNINDENT .UNINDENT .sp Statically assigns grains to the minion. .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 .SS \fBgrains_cache\fP .sp Default: \fBFalse\fP .sp The minion can locally cache grain data instead of refreshing the data each time the grain is referenced. By default this feature is disabled, to enable set grains_cache to \fBTrue\fP\&. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C grains_cache: False .ft P .fi .UNINDENT .UNINDENT .SS \fBgrains_deep_merge\fP .sp New in version 2016.3.0. .sp Default: \fBFalse\fP .sp The grains can be merged, instead of overridden, using this option. This allows custom grains to defined different subvalues of a dictionary grain. By default this feature is disabled, to enable set grains_deep_merge to \fBTrue\fP\&. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C grains_deep_merge: False .ft P .fi .UNINDENT .UNINDENT .sp For example, with these custom grains functions: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C def custom1_k1(): return {\(aqcustom1\(aq: {\(aqk1\(aq: \(aqv1\(aq}} def custom1_k2(): return {\(aqcustom1\(aq: {\(aqk2\(aq: \(aqv2\(aq}} .ft P .fi .UNINDENT .UNINDENT .sp Without \fBgrains_deep_merge\fP, the result would be: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C custom1: k1: v1 .ft P .fi .UNINDENT .UNINDENT .sp With \fBgrains_deep_merge\fP, the result will be: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C custom1: k1: v1 k2: v2 .ft P .fi .UNINDENT .UNINDENT .SS \fBmine_enabled\fP .sp New in version 2015.8.10. .sp Default: \fBTrue\fP .sp Determines whether or not the salt minion should run scheduled mine updates. If this is set to False then the mine update function will not get added to the scheduler for the minion. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C mine_enabled: True .ft P .fi .UNINDENT .UNINDENT .SS \fBmine_return_job\fP .sp New in version 2015.8.10. .sp Default: \fBFalse\fP .sp Determines whether or not scheduled mine updates should be accompanied by a job return for the job cache. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C mine_return_job: False .ft P .fi .UNINDENT .UNINDENT .SS \fBmine_functions\fP .sp Default: Empty .sp Designate which functions should be executed at mine_interval intervals on each minion. See this documentation on the Salt Mine for more information. Note these can be defined in the pillar for a minion as well. .INDENT 0.0 .INDENT 3.5 example minion configuration file .UNINDENT .UNINDENT .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C mine_functions: test.ping: [] network.ip_addrs: interface: eth0 cidr: \(aq10.0.0.0/8\(aq .ft P .fi .UNINDENT .UNINDENT .SS \fBsock_dir\fP .sp Default: \fB/var/run/salt/minion\fP .sp The directory where Unix sockets will be kept. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C sock_dir: /var/run/salt/minion .ft P .fi .UNINDENT .UNINDENT .SS \fBbackup_mode\fP .sp Default: \fB\(aq\(aq\fP .sp Make backups of files replaced by \fBfile.managed\fP and \fBfile.recurse\fP state modules under \fI\%cachedir\fP in \fBfile_backup\fP subdirectory preserving original paths. Refer to File State Backups documentation for more details. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C backup_mode: minion .ft P .fi .UNINDENT .UNINDENT .SS \fBacceptance_wait_time\fP .sp Default: \fB10\fP .sp The number of seconds to wait until attempting to re\-authenticate with the master. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C acceptance_wait_time: 10 .ft P .fi .UNINDENT .UNINDENT .SS \fBacceptance_wait_time_max\fP .sp Default: \fB0\fP .sp The maximum number of seconds to wait until attempting to re\-authenticate with the master. If set, the wait will increase by \fI\%acceptance_wait_time\fP seconds each iteration. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C acceptance_wait_time_max: 0 .ft P .fi .UNINDENT .UNINDENT .SS \fBrandom_reauth_delay\fP .sp Default: \fB10\fP .sp When the master key changes, the minion will try to re\-auth itself to receive the new master key. In larger environments this can cause a syn\-flood on the master because all minions try to re\-auth immediately. To prevent this and have a minion wait for a random amount of time, use this optional parameter. The wait\-time will be a random number of seconds between 0 and the defined value. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C random_reauth_delay: 60 .ft P .fi .UNINDENT .UNINDENT .SS \fBmaster_tries\fP .sp New in version 2016.3.0. .sp Default: \fB1\fP .sp The number of attempts to connect to a master before giving up. Set this to \fB\-1\fP for unlimited attempts. This allows for a master to have downtime and the minion to reconnect to it later when it comes back up. In \(aqfailover\(aq mode, which is set in the \fI\%master_type\fP configuration, this value is the number of attempts for each set of masters. In this mode, it will cycle through the list of masters for each attempt. .sp \fBmaster_tries\fP is different than \fBauth_tries\fP because \fBauth_tries\fP attempts to retry auth attempts with a single master. \fBauth_tries\fP is under the assumption that you can connect to the master but not gain authorization from it. \fBmaster_tries\fP will still cycle through all of the masters in a given try, so it is appropriate if you expect occasional downtime from the master(s). .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C master_tries: 1 .ft P .fi .UNINDENT .UNINDENT .SS \fBauth_tries\fP .sp New in version 2014.7.0. .sp Default: \fB7\fP .sp The number of attempts to authenticate to a master before giving up. Or, more technically, the number of consecutive SaltReqTimeoutErrors that are acceptable when trying to authenticate to the master. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C auth_tries: 7 .ft P .fi .UNINDENT .UNINDENT .SS \fBauth_timeout\fP .sp New in version 2014.7.0. .sp Default: \fB60\fP .sp When waiting for a master to accept the minion\(aqs public key, salt will continuously attempt to reconnect until successful. This is the timeout value, in seconds, for each individual attempt. After this timeout expires, the minion will wait for \fI\%acceptance_wait_time\fP seconds before trying again. Unless your master is under unusually heavy load, this should be left at the default. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C auth_timeout: 60 .ft P .fi .UNINDENT .UNINDENT .SS \fBauth_safemode\fP .sp New in version 2014.7.0. .sp Default: \fBFalse\fP .sp If authentication fails due to SaltReqTimeoutError during a ping_interval, this setting, when set to \fBTrue\fP, will cause a sub\-minion process to restart. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C auth_safemode: False .ft P .fi .UNINDENT .UNINDENT .SS \fBrecon_default\fP .sp Default: \fB1000\fP .sp The interval in milliseconds that the socket should wait before trying to reconnect to the master (1000ms = 1 second). .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C recon_default: 1000 .ft P .fi .UNINDENT .UNINDENT .SS \fBrecon_max\fP .sp Default: \fB10000\fP .sp The maximum time a socket should wait. Each interval the time to wait is calculated by doubling the previous time. If recon_max is reached, it starts again at the recon_default. .INDENT 0.0 .TP .B Short example: .INDENT 7.0 .IP \(bu 2 reconnect 1: the socket will wait \(aqrecon_default\(aq milliseconds .IP \(bu 2 reconnect 2: \(aqrecon_default\(aq * 2 .IP \(bu 2 reconnect 3: (\(aqrecon_default\(aq * 2) * 2 .IP \(bu 2 reconnect 4: value from previous interval * 2 .IP \(bu 2 reconnect 5: value from previous interval * 2 .IP \(bu 2 reconnect x: if value >= recon_max, it starts again with recon_default .UNINDENT .UNINDENT .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C recon_max: 10000 .ft P .fi .UNINDENT .UNINDENT .SS \fBrecon_randomize\fP .sp Default: \fBTrue\fP .sp Generate a random wait time on minion start. The wait time will be a random value between recon_default and recon_default + recon_max. Having all minions reconnect with the same recon_default and recon_max value kind of defeats the purpose of being able to change these settings. If all minions have the same values and the setup is quite large (several thousand minions), they will still flood the master. The desired behavior is to have time\-frame within all minions try to reconnect. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C recon_randomize: True .ft P .fi .UNINDENT .UNINDENT .SS \fBloop_interval\fP .sp Default: \fB1\fP .sp The loop_interval sets how long in seconds the minion will wait between evaluating the scheduler and running cleanup tasks. This defaults to 1 second on the minion scheduler. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C loop_interval: 1 .ft P .fi .UNINDENT .UNINDENT .SS \fBpub_ret\fP .sp Default: True .sp Some installations choose to start all job returns in a cache or a returner and forgo sending the results back to a master. In this workflow, jobs are most often executed with \-\-async from the Salt CLI and then results are evaluated by examining job caches on the minions or any configured returners. WARNING: Setting this to False will \fBdisable\fP returns back to the master. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C pub_ret: True .ft P .fi .UNINDENT .UNINDENT .SS \fBreturn_retry_timer\fP .sp Default: \fB5\fP .sp The default timeout for a minion return attempt. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C return_retry_timer: 5 .ft P .fi .UNINDENT .UNINDENT .SS \fBreturn_retry_timer_max\fP .sp Default: \fB10\fP .sp The maximum timeout for a minion return attempt. If non\-zero the minion return retry timeout will be a random int between \fBreturn_retry_timer\fP and \fBreturn_retry_timer_max\fP .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C return_retry_timer_max: 10 .ft P .fi .UNINDENT .UNINDENT .SS \fBcache_sreqs\fP .sp Default: \fBTrue\fP .sp The connection to the master ret_port is kept open. When set to False, the minion creates a new connection for every return to the master. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C cache_sreqs: True .ft P .fi .UNINDENT .UNINDENT .SS \fBipc_mode\fP .sp Default: \fBipc\fP .sp Windows platforms lack POSIX IPC and must rely on slower TCP based inter\- process communications. Set ipc_mode to \fBtcp\fP on such systems. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C ipc_mode: ipc .ft P .fi .UNINDENT .UNINDENT .SS \fBtcp_pub_port\fP .sp Default: \fB4510\fP .sp Publish port used when \fI\%ipc_mode\fP is set to \fBtcp\fP\&. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C tcp_pub_port: 4510 .ft P .fi .UNINDENT .UNINDENT .SS \fBtcp_pull_port\fP .sp Default: \fB4511\fP .sp Pull port used when \fI\%ipc_mode\fP is set to \fBtcp\fP\&. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C tcp_pull_port: 4511 .ft P .fi .UNINDENT .UNINDENT .SS \fBtransport\fP .sp Default: \fBzeromq\fP .sp Changes the underlying transport layer. ZeroMQ is the recommended transport while additional transport layers are under development. Supported values are \fBzeromq\fP, \fBraet\fP (experimental), and \fBtcp\fP (experimental). This setting has a significant impact on performance and should not be changed unless you know what you are doing! Transports are explained in Salt Transports\&. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C transport: zeromq .ft P .fi .UNINDENT .UNINDENT .SS \fBsyndic_finger\fP .sp Default: \fB\(aq\(aq\fP .sp The key fingerprint of the higher\-level master for the syndic to verify it is talking to the intended master. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C syndic_finger: \(aqab:30:65:2a:d6:9e:20:4f:d8:b2:f3:a7:d4:65:50:10\(aq .ft P .fi .UNINDENT .UNINDENT .SS \fBproxy_host\fP .sp Default: \fB\(aq\(aq\fP .sp The hostname used for HTTP proxy access. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C proxy_host: proxy.my\-domain .ft P .fi .UNINDENT .UNINDENT .SS \fBproxy_port\fP .sp Default: \fB0\fP .sp The port number used for HTTP proxy access. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C proxy_port: 31337 .ft P .fi .UNINDENT .UNINDENT .SS \fBproxy_username\fP .sp Default: \fB\(aq\(aq\fP .sp The username used for HTTP proxy access. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C proxy_username: charon .ft P .fi .UNINDENT .UNINDENT .SS \fBproxy_password\fP .sp Default: \fB\(aq\(aq\fP .sp The password used for HTTP proxy access. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C proxy_password: obolus .ft P .fi .UNINDENT .UNINDENT .SS Minion Module Management .SS \fBdisable_modules\fP .sp Default: \fB[]\fP (all modules are enabled by default) .sp The event may occur in which the administrator desires that a minion should not be able to execute a certain module. The \fBsys\fP module is built into the minion and cannot be disabled. .sp This setting can also tune the minion. Because all modules are loaded into system memory, disabling modules will lover the minion\(aqs memory footprint. .sp Modules should be specified according to their file name on the system and not by their virtual name. For example, to disable \fBcmd\fP, use the string \fBcmdmod\fP which corresponds to \fBsalt.modules.cmdmod\fP\&. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C disable_modules: \- test \- solr .ft P .fi .UNINDENT .UNINDENT .SS \fBdisable_returners\fP .sp Default: \fB[]\fP (all returners are enabled by default) .sp If certain returners should be disabled, this is the place .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C disable_returners: \- mongo_return .ft P .fi .UNINDENT .UNINDENT .SS \fBwhitelist_modules\fP .sp Default: \fB[]\fP (Module whitelisting is disabled. Adding anything to the config option will cause only the listed modules to be enabled. Modules not in the list will not be loaded.) .sp This option is the reverse of disable_modules. .sp Note that this is a very large hammer and it can be quite difficult to keep the minion working the way you think it should since Salt uses many modules internally itself. At a bare minimum you need the following enabled or else the minion won\(aqt start. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C whitelist_modules: \- cmdmod \- test \- config .ft P .fi .UNINDENT .UNINDENT .SS \fBmodule_dirs\fP .sp Default: \fB[]\fP .sp A list of extra directories to search for Salt modules .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C module_dirs: \- /var/lib/salt/modules .ft P .fi .UNINDENT .UNINDENT .SS \fBreturner_dirs\fP .sp Default: \fB[]\fP .sp A list of extra directories to search for Salt returners .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C returner_dirs: \- /var/lib/salt/returners .ft P .fi .UNINDENT .UNINDENT .SS \fBstates_dirs\fP .sp Default: \fB[]\fP .sp A list of extra directories to search for Salt states .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C states_dirs: \- /var/lib/salt/states .ft P .fi .UNINDENT .UNINDENT .SS \fBgrains_dirs\fP .sp Default: \fB[]\fP .sp A list of extra directories to search for Salt grains .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C grains_dirs: \- /var/lib/salt/grains .ft P .fi .UNINDENT .UNINDENT .SS \fBrender_dirs\fP .sp Default: \fB[]\fP .sp A list of extra directories to search for Salt renderers .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C render_dirs: \- /var/lib/salt/renderers .ft P .fi .UNINDENT .UNINDENT .SS \fBcython_enable\fP .sp Default: \fBFalse\fP .sp Set this value to true to enable auto\-loading and compiling of \fB\&.pyx\fP modules, This setting requires that \fBgcc\fP and \fBcython\fP are installed on the minion. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C cython_enable: False .ft P .fi .UNINDENT .UNINDENT .SS \fBenable_zip_modules\fP .sp New in version 2015.8.0. .sp Default: \fBFalse\fP .sp Set this value to true to enable loading of zip archives as extension modules. This allows for packing module code with specific dependencies to avoid conflicts and/or having to install specific modules\(aq dependencies in system libraries. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C enable_zip_modules: False .ft P .fi .UNINDENT .UNINDENT .SS \fBproviders\fP .sp Default: (empty) .sp A module provider can be statically overwritten or extended for the minion via the \fBproviders\fP option. This can be done on an individual basis in an SLS file, or globally here in the minion config, like below. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C providers: service: systemd .ft P .fi .UNINDENT .UNINDENT .SS State Management Settings .SS \fBrenderer\fP .sp Default: \fByaml_jinja\fP .sp The default renderer used for local state executions .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C renderer: yaml_jinja .ft P .fi .UNINDENT .UNINDENT .SS \fBtest\fP .sp Default: \fBFalse\fP .sp Set all state calls to only test if they are going to actually make changes or just post what changes are going to be made. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C test: False .ft P .fi .UNINDENT .UNINDENT .SS \fBstate_verbose\fP .sp Default: \fBTrue\fP .sp Controls the verbosity of state runs. By default, the results of all states are returned, but setting this value to \fBFalse\fP will cause salt to only display output for states that failed or states that have changes. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C state_verbose: True .ft P .fi .UNINDENT .UNINDENT .SS \fBstate_output\fP .sp Default: \fBfull\fP .sp The state_output setting changes if the output is the full multi line output for each changed state if set to \(aqfull\(aq, but if set to \(aqterse\(aq the output will be shortened to a single line. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C state_output: full .ft P .fi .UNINDENT .UNINDENT .SS \fBautoload_dynamic_modules\fP .sp Default: \fBTrue\fP .sp autoload_dynamic_modules turns on automatic loading of modules found in the environments on the master. This is turned on by default. To turn off auto\-loading modules when states run, set this value to \fBFalse\fP\&. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C autoload_dynamic_modules: True .ft P .fi .UNINDENT .UNINDENT .sp Default: \fBTrue\fP .sp clean_dynamic_modules keeps the dynamic modules on the minion in sync with the dynamic modules on the master. This means that if a dynamic module is not on the master it will be deleted from the minion. By default this is enabled and can be disabled by changing this value to \fBFalse\fP\&. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C clean_dynamic_modules: True .ft P .fi .UNINDENT .UNINDENT .SS \fBenvironment\fP .sp Normally the minion is not isolated to any single environment on the master when running states, but the environment can be isolated on the minion side by statically setting it. Remember that the recommended way to manage environments is to isolate via the top file. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C environment: dev .ft P .fi .UNINDENT .UNINDENT .SS \fBstate_top_saltenv\fP .sp This option has no default value. Set it to an environment name to ensure that \fIonly\fP the top file from that environment is considered during a highstate\&. .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 Using this value does not change the merging strategy. For instance, if \fI\%top_file_merging_strategy\fP is set to \fBmerge\fP, and \fI\%state_top_saltenv\fP is set to \fBfoo\fP, then any sections for environments other than \fBfoo\fP in the top file for the \fBfoo\fP environment will be ignored. With \fI\%state_top_saltenv\fP set to \fBbase\fP, all states from all environments in the \fBbase\fP top file will be applied, while all other top files are ignored. The only way to set \fI\%state_top_saltenv\fP to something other than \fBbase\fP and not have the other environments in the targeted top file ignored, would be to set \fI\%top_file_merging_strategy\fP to \fBmerge_all\fP\&. .UNINDENT .UNINDENT .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C state_top_saltenv: dev .ft P .fi .UNINDENT .UNINDENT .SS \fBtop_file_merging_strategy\fP .sp Changed in version 2016.11.0: A \fBmerge_all\fP strategy has been added. .sp Default: \fBmerge\fP .sp When no specific fileserver environment (a.k.a. \fBsaltenv\fP) has been specified for a highstate, all environments\(aq top files are inspected. This config option determines how the SLS targets in those top files are handled. .sp When set to \fBmerge\fP, the \fBbase\fP environment\(aqs top file is evaluated first, followed by the other environments\(aq top files. The first target expression (e.g. \fB\(aq*\(aq\fP) for a given environment is kept, and when the same target expression is used in a different top file evaluated later, it is ignored. Because \fBbase\fP is evaluated first, it is authoritative. For example, if there is a target for \fB\(aq*\(aq\fP for the \fBfoo\fP environment in both the \fBbase\fP and \fBfoo\fP environment\(aqs top files, the one in the \fBfoo\fP environment would be ignored. The environments will be evaluated in no specific order (aside from \fBbase\fP coming first). For greater control over the order in which the environments are evaluated, use \fI\%env_order\fP\&. .sp When set to \fBsame\fP, then for each environment, only that environment\(aqs top file is processed, with the others being ignored. For example, only the \fBdev\fP environment\(aqs top file will be processed for the \fBdev\fP environment, and any SLS targets defined for \fBdev\fP in the \fBbase\fP environment\(aqs (or any other environment\(aqs) top file will be ignored. If an environment does not have a top file, then the top file from the \fI\%default_top\fP config parameter will be used as a fallback. .sp When set to \fBmerge_all\fP, then all states in all environments in all top files will be applied. The order in which individual SLS files will be executed will depend on the order in which the top files were evaluated, and the environments will be evaluated in no specific order. For greater control over the order in which the environments are evaluated, use \fI\%env_order\fP\&. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C top_file_merging_strategy: same .ft P .fi .UNINDENT .UNINDENT .SS \fBenv_order\fP .sp Default: \fB[]\fP .sp When \fI\%top_file_merging_strategy\fP is set to \fBmerge\fP, and no environment is specified for a highstate, this config option allows for the order in which top files are evaluated to be explicitly defined. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C env_order: \- base \- dev \- qa .ft P .fi .UNINDENT .UNINDENT .SS \fBdefault_top\fP .sp Default: \fBbase\fP .sp When \fI\%top_file_merging_strategy\fP is set to \fBsame\fP, and no environment is specified for a highstate (i.e. \fI\%environment\fP is not set for the minion), this config option specifies a fallback environment in which to look for a top file if an environment lacks one. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C default_top: dev .ft P .fi .UNINDENT .UNINDENT .SS \fBsnapper_states\fP .sp Default: False .sp The \fIsnapper_states\fP value is used to enable taking snapper snapshots before and after salt state runs. This allows for state runs to be rolled back. .sp For snapper states to function properly snapper needs to be installed and enabled. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C snapper_states: True .ft P .fi .UNINDENT .UNINDENT .SS \fBsnapper_states_config\fP .sp Default: \fBroot\fP .sp Snapper can execute based on a snapper configuration. The configuration needs to be set up before snapper can use it. The default configuration is \fBroot\fP, this default makes snapper run on SUSE systems using the default configuration set up at install time. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C snapper_states_config: root .ft P .fi .UNINDENT .UNINDENT .SS File Directory Settings .SS \fBfile_client\fP .sp Default: \fBremote\fP .sp The client defaults to looking on the master server for files, but can be directed to look on the minion by setting this parameter to \fBlocal\fP\&. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C file_client: remote .ft P .fi .UNINDENT .UNINDENT .SS \fBuse_master_when_local\fP .sp Default: \fBFalse\fP .sp When using a local \fI\%file_client\fP, this parameter is used to allow the client to connect to a master for remote execution. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C use_master_when_local: False .ft P .fi .UNINDENT .UNINDENT .SS \fBfile_roots\fP .sp Default: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C base: \- /srv/salt .ft P .fi .UNINDENT .UNINDENT .sp When using a local \fI\%file_client\fP, this parameter is used to setup the fileserver\(aqs environments. This parameter operates identically to the \fBmaster config parameter\fP of the same name. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C file_roots: base: \- /srv/salt dev: \- /srv/salt/dev/services \- /srv/salt/dev/states prod: \- /srv/salt/prod/services \- /srv/salt/prod/states .ft P .fi .UNINDENT .UNINDENT .SS \fBfileserver_followsymlinks\fP .sp New in version 2014.1.0. .sp Default: \fBTrue\fP .sp By default, the file_server follows symlinks when walking the filesystem tree. Currently this only applies to the default roots fileserver_backend. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C fileserver_followsymlinks: True .ft P .fi .UNINDENT .UNINDENT .SS \fBfileserver_ignoresymlinks\fP .sp New in version 2014.1.0. .sp Default: \fBFalse\fP .sp If you do not want symlinks to be treated as the files they are pointing to, set \fBfileserver_ignoresymlinks\fP to \fBTrue\fP\&. By default this is set to False. When set to \fBTrue\fP, any detected symlink while listing files on the Master will not be returned to the Minion. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C fileserver_ignoresymlinks: False .ft P .fi .UNINDENT .UNINDENT .SS \fBfileserver_limit_traversal\fP .sp New in version 2014.1.0. .sp Default: \fBFalse\fP .sp By default, the Salt fileserver recurses fully into all defined environments to attempt to find files. To limit this behavior so that the fileserver only traverses directories with SLS files and special Salt directories like _modules, set \fBfileserver_limit_traversal\fP to \fBTrue\fP\&. This might be useful for installations where a file root has a very large number of files and performance is impacted. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C fileserver_limit_traversal: False .ft P .fi .UNINDENT .UNINDENT .SS \fBhash_type\fP .sp Default: \fBsha256\fP .sp The hash_type is the hash to use when discovering the hash of a file on the local fileserver. The default is sha256, but md5, sha1, sha224, sha384, and sha512 are also supported. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C hash_type: sha256 .ft P .fi .UNINDENT .UNINDENT .SS Pillar Configuration .SS \fBpillar_roots\fP .sp Default: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C base: \- /srv/pillar .ft P .fi .UNINDENT .UNINDENT .sp When using a local \fI\%file_client\fP, this parameter is used to setup the pillar environments. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C pillar_roots: base: \- /srv/pillar dev: \- /srv/pillar/dev prod: \- /srv/pillar/prod .ft P .fi .UNINDENT .UNINDENT .SS \fBpillarenv\fP .sp Default: \fBNone\fP .sp Isolates the pillar environment on the minion side. This functions the same as the environment setting, but for pillar instead of states. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C pillarenv: None .ft P .fi .UNINDENT .UNINDENT .SS \fBpillar_raise_on_missing\fP .sp New in version 2015.5.0. .sp Default: \fBFalse\fP .sp Set this option to \fBTrue\fP to force a \fBKeyError\fP to be raised whenever an attempt to retrieve a named value from pillar fails. When this option is set to \fBFalse\fP, the failed attempt returns an empty string. .SS \fBminion_pillar_cache\fP .sp New in version 2016.3.0. .sp Default: \fBFalse\fP .sp The minion can locally cache rendered pillar data under \fI\%cachedir\fP/pillar. This allows a temporarily disconnected minion to access previously cached pillar data by invoking salt\-call with the \-\-local and \-\-pillar_root=:conf_minion:\fIcachedir\fP/pillar options. Before enabling this setting consider that the rendered pillar may contain security sensitive data. Appropriate access restrictions should be in place. By default the saved pillar data will be readable only by the user account running salt. By default this feature is disabled, to enable set minion_pillar_cache to \fBTrue\fP\&. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C minion_pillar_cache: False .ft P .fi .UNINDENT .UNINDENT .SS \fBfile_recv_max_size\fP .sp New in version 2014.7.0. .sp Default: \fB100\fP .sp Set a hard\-limit on the size of the files that can be pushed to the master. It will be interpreted as megabytes. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C file_recv_max_size: 100 .ft P .fi .UNINDENT .UNINDENT .SS Security Settings .SS \fBopen_mode\fP .sp Default: \fBFalse\fP .sp Open mode can be used to clean out the PKI key received from the Salt master, turn on open mode, restart the minion, then turn off open mode and restart the minion to clean the keys. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C open_mode: False .ft P .fi .UNINDENT .UNINDENT .SS \fBmaster_finger\fP .sp Default: \fB\(aq\(aq\fP .sp Fingerprint of the master public key to validate the identity of your Salt master before the initial key exchange. The master fingerprint can be found by running "salt\-key \-F master" on the Salt master. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C master_finger: \(aqba:30:65:2a:d6:9e:20:4f:d8:b2:f3:a7:d4:65:11:13\(aq .ft P .fi .UNINDENT .UNINDENT .SS \fBverify_master_pubkey_sign\fP .sp Default: \fBFalse\fP .sp Enables verification of the master\-public\-signature returned by the master in auth\-replies. Please see the tutorial on how to configure this properly \fI\%Multimaster\-PKI with Failover Tutorial\fP .sp New in version 2014.7.0. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C verify_master_pubkey_sign: True .ft P .fi .UNINDENT .UNINDENT .sp If this is set to \fBTrue\fP, \fBmaster_sign_pubkey\fP must be also set to \fBTrue\fP in the master configuration file. .SS \fBmaster_sign_key_name\fP .sp Default: \fBmaster_sign\fP .sp The filename without the \fI\&.pub\fP suffix of the public key that should be used for verifying the signature from the master. The file must be located in the minion\(aqs pki directory. .sp New in version 2014.7.0. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C master_sign_key_name: .ft P .fi .UNINDENT .UNINDENT .SS \fBalways_verify_signature\fP .sp Default: \fBFalse\fP .sp If \fI\%verify_master_pubkey_sign\fP is enabled, the signature is only verified if the public\-key of the master changes. If the signature should always be verified, this can be set to \fBTrue\fP\&. .sp New in version 2014.7.0. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C always_verify_signature: True .ft P .fi .UNINDENT .UNINDENT .SS \fBcmd_blacklist_glob\fP .sp Default: \fB[]\fP .sp If \fI\%cmd_blacklist_glob\fP is enabled then any shell command called over remote execution or via salt\-call will be checked against the glob matches found in the \fIcmd_blacklist_glob\fP list and any matched shell command will be blocked. .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 This blacklist is only applied to direct executions made by the \fIsalt\fP and \fIsalt\-call\fP commands. This does NOT blacklist commands called from states or shell commands executed from other modules. .UNINDENT .UNINDENT .sp New in version 2016.11.0. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C cmd_blacklist_glob: \- \(aqrm * \(aq \- \(aqcat /etc/* \(aq .ft P .fi .UNINDENT .UNINDENT .SS \fBcmd_whitelist_glob\fP .sp Default: \fB[]\fP .sp If \fI\%cmd_whitelist_glob\fP is enabled then any shell command called over remote execution or via salt\-call will be checked against the glob matches found in the \fIcmd_whitelist_glob\fP list and any shell command NOT found in the list will be blocked. If \fIcmd_whitelist_glob\fP is NOT SET, then all shell commands are permitted. .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 This whitelist is only applied to direct executions made by the \fIsalt\fP and \fIsalt\-call\fP commands. This does NOT restrict commands called from states or shell commands executed from other modules. .UNINDENT .UNINDENT .sp New in version 2016.11.0. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C cmd_whitelist_glob: \- \(aqls * \(aq \- \(aqcat /etc/fstab\(aq .ft P .fi .UNINDENT .UNINDENT .SS \fBssl\fP .sp New in version 2016.11.0. .sp Default: \fBNone\fP .sp TLS/SSL connection options. This could be set to a dictionary containing arguments corresponding to python \fBssl.wrap_socket\fP method. For details see \fI\%Tornado\fP and \fI\%Python\fP documentation. .sp Note: to set enum arguments values like \fBcert_reqs\fP and \fBssl_version\fP use constant names without ssl module prefix: \fBCERT_REQUIRED\fP or \fBPROTOCOL_SSLv23\fP\&. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C ssl: keyfile: certfile: ssl_version: PROTOCOL_TLSv1_2 .ft P .fi .UNINDENT .UNINDENT .SS Thread Settings .sp Default: \fBTrue\fP .sp If \fImultiprocessing\fP is enabled when a minion receives a publication a new process is spawned and the command is executed therein. Conversely, if \fImultiprocessing\fP is disabled the new publication will be run executed in a thread. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C multiprocessing: True .ft P .fi .UNINDENT .UNINDENT .SS Minion Logging Settings .SS \fBlog_file\fP .sp Default: \fB/var/log/salt/minion\fP .sp The minion log can be sent to a regular file, local path name, or network location. See also \fBlog_file\fP\&. .sp Examples: .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 messages to send to the console. See also \fBlog_level\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: \fBinfo\fP .sp The level of messages to send to the log file. See also \fBlog_level_logfile\fP\&. When it is not set explicitly it will inherit the level set by \fBlog_level\fP option. .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. See also \fBlog_datefmt\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. See also \fBlog_datefmt_logfile\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. See also \fBlog_fmt_console\fP\&. .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 Log colors are enabled in \fBlog_fmt_console\fP rather than the \fBcolor\fP config since the logging system is loaded before the minion config. .sp Console log colors are specified by these additional formatters: .sp %(colorlevel)s %(colorname)s %(colorprocess)s %(colormsg)s .sp Since it is desirable to include the surrounding brackets, \(aq[\(aq and \(aq]\(aq, in the coloring of the messages, these color formatters also include padding as well. Color LogRecord attributes are only available for console logging. .UNINDENT .UNINDENT .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C log_fmt_console: \(aq%(colorlevel)s %(colormsg)s\(aq 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)03d [%(name)\-17s][%(levelname)\-8s] %(message)s\fP .sp The format of the log file logging messages. See also \fBlog_fmt_logfile\fP\&. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C log_fmt_logfile: \(aq%(asctime)s,%(msecs)03d [%(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. See also \fBlog_granular_levels\fP\&. .SS \fBzmq_monitor\fP .sp Default: \fBFalse\fP .sp To diagnose issues with minions disconnecting or missing returns, ZeroMQ supports the use of monitor sockets to log connection events. This feature requires ZeroMQ 4.0 or higher. .sp To enable ZeroMQ monitor sockets, set \(aqzmq_monitor\(aq to \(aqTrue\(aq and log at a debug level or higher. .sp A sample log event is as follows: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C [DEBUG ] ZeroMQ event: {\(aqendpoint\(aq: \(aqtcp://127.0.0.1:4505\(aq, \(aqevent\(aq: 512, \(aqvalue\(aq: 27, \(aqdescription\(aq: \(aqEVENT_DISCONNECTED\(aq} .ft P .fi .UNINDENT .UNINDENT .sp All events logged will include the string \fBZeroMQ event\fP\&. A connection event should be logged as the minion starts up and initially connects to the master. If not, check for debug log level and that the necessary version of ZeroMQ is installed. .SS \fBfailhard\fP .sp Default: \fBFalse\fP .sp Set the global failhard flag. This informs all states to stop running states at the moment a single state fails .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C failhard: False .ft P .fi .UNINDENT .UNINDENT .SS Include Configuration .SS \fBdefault_include\fP .sp Default: \fBminion.d/*.conf\fP .sp The minion can include configuration from other files. Per default the minion will automatically include all config files from \fIminion.d/*.conf\fP where minion.d is relative to the directory of the minion configuration file. .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 Salt creates files in the \fBminion.d\fP directory for its own use. These files are prefixed with an underscore. A common example of this is the \fB_schedule.conf\fP file. .UNINDENT .UNINDENT .SS \fBinclude\fP .sp Default: \fBnot defined\fP .sp The minion can include configuration from other files. To enable this, pass a list of paths to this option. The paths can be either relative or absolute; if relative, they are considered to be relative to the directory the main minion configuration file lives in. Paths can make use of shell\-style globbing. If no files are matched by a path passed to this option then the minion will log a warning message. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C # Include files from a minion.d directory in the same # directory as the minion config file include: minion.d/*.conf # Include a single extra file into the configuration include: /etc/roles/webserver # Include several files and the minion.d directory include: \- extra_config \- minion.d/* \- /etc/roles/webserver .ft P .fi .UNINDENT .UNINDENT .SS Frozen Build Update Settings .sp These options control how \fBsalt.modules.saltutil.update()\fP works with esky frozen apps. For more information look at \fI\%https://github.com/cloudmatrix/esky/\fP\&. .SS \fBupdate_url\fP .sp Default: \fBFalse\fP (Update feature is disabled) .sp The url to use when looking for application updates. Esky depends on directory listings to search for new versions. A webserver running on your Master is a good starting point for most setups. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C update_url: \(aqhttp://salt.example.com/minion\-updates\(aq .ft P .fi .UNINDENT .UNINDENT .SS \fBupdate_restart_services\fP .sp Default: \fB[]\fP (service restarting on update is disabled) .sp A list of services to restart when the minion software is updated. This would typically just be a list containing the minion\(aqs service name, but you may have other services that need to go with it. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C update_restart_services: [\(aqsalt\-minion\(aq] .ft P .fi .UNINDENT .UNINDENT .SS \fBwinrepo_cache_expire_min\fP .sp New in version 2016.11.0. .sp Default: \fB0\fP .sp If set to a nonzero integer, then passing \fBrefresh=True\fP to functions in the \fBwindows pkg module\fP will not refresh the windows repo metadata if the age of the metadata is less than this value. The exception to this is \fBpkg.refresh_db\fP, which will always refresh the metadata, regardless of age. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C winrepo_cache_expire_min: 1800 .ft P .fi .UNINDENT .UNINDENT .SS \fBwinrepo_cache_expire_max\fP .sp New in version 2016.11.0. .sp Default: \fB21600\fP .sp If the windows repo metadata is older than this value, and the metadata is needed by a function in the \fBwindows pkg module\fP, the metadata will be refreshed. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C winrepo_cache_expire_max: 86400 .ft P .fi .UNINDENT .UNINDENT .SS Standalone Minion Windows Software Repo Settings .sp \fBIMPORTANT:\fP .INDENT 0.0 .INDENT 3.5 To use these config options, the minion must be running in masterless mode (set \fI\%file_client\fP to \fBlocal\fP). .UNINDENT .UNINDENT .SS \fBwinrepo_dir\fP .sp Changed in version 2015.8.0: Renamed from \fBwin_repo\fP to \fBwinrepo_dir\fP\&. Also, this option did not have a default value until this version. .sp Default: \fBC:\esalt\esrv\esalt\ewin\erepo\fP .sp Location on the minion where the \fI\%winrepo_remotes\fP are checked out. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C winrepo_dir: \(aqD:\ewinrepo\(aq .ft P .fi .UNINDENT .UNINDENT .SS \fBwinrepo_cachefile\fP .sp Changed in version 2015.8.0: Renamed from \fBwin_repo_cachefile\fP to \fBwinrepo_cachefile\fP\&. Also, this option did not have a default value until this version. .sp Default: \fBwinrepo.p\fP .sp Path relative to \fI\%winrepo_dir\fP where the winrepo cache should be created. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C winrepo_cachefile: winrepo.p .ft P .fi .UNINDENT .UNINDENT .SS \fBwinrepo_remotes\fP .sp Changed in version 2015.8.0: Renamed from \fBwin_gitrepos\fP to \fBwinrepo_remotes\fP\&. Also, this option did not have a default value until this version. .sp New in version 2015.8.0. .sp Default: \fB[\(aqhttps://github.com/saltstack/salt\-winrepo.git\(aq]\fP .sp List of git repositories to checkout and include in the winrepo .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C winrepo_remotes: \- https://github.com/saltstack/salt\-winrepo.git .ft P .fi .UNINDENT .UNINDENT .sp To specify a specific revision of the repository, prepend a commit ID to the URL of the the repository: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C winrepo_remotes: \- \(aq https://github.com/saltstack/salt\-winrepo.git\(aq .ft P .fi .UNINDENT .UNINDENT .sp Replace \fB\fP with the SHA1 hash of a commit ID. Specifying a commit ID is useful in that it allows one to revert back to a previous version in the event that an error is introduced in the latest revision of the repo. .SS Configuration file examples .INDENT 0.0 .IP \(bu 2 \fI\%Example master configuration file\fP .IP \(bu 2 \fI\%Example minion configuration file\fP .UNINDENT .SS Example master configuration file .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C ##### Primary configuration settings ##### ########################################## # This configuration file is used to manage the behavior of the Salt Master. # Values that are commented out but have an empty line after the comment are # defaults that do not need to be set in the config. If there is no blank line # after the comment then the value is presented as an example and is not the # default. # Per default, the master will automatically include all config files # from master.d/*.conf (master.d is a directory in the same directory # as the main master config file). #default_include: master.d/*.conf # The address of the interface to bind to: #interface: 0.0.0.0 # Whether the master should listen for IPv6 connections. If this is set to True, # the interface option must be adjusted, too. (For example: "interface: \(aq::\(aq") #ipv6: False # The tcp port used by the publisher: #publish_port: 4505 # The user under which the salt master will run. Salt will update all # permissions to allow the specified user to run the master. The exception is # the job cache, which must be deleted if this user is changed. If the # modified files cause conflicts, set verify_env to False. #user: root # The port used by the communication interface. The ret (return) port is the # interface used for the file server, authentication, job returns, etc. #ret_port: 4506 # Specify the location of the daemon process ID file: #pidfile: /var/run/salt\-master.pid # The root directory prepended to these options: pki_dir, cachedir, # sock_dir, log_file, autosign_file, autoreject_file, extension_modules, # key_logfile, pidfile: #root_dir: / # The path to the master\(aqs configuration file. #conf_file: /etc/salt/master # Directory used to store public key data: #pki_dir: /etc/salt/pki/master # Key cache. Increases master speed for large numbers of accepted # keys. Available options: \(aqsched\(aq. (Updates on a fixed schedule.) # Note that enabling this feature means that minions will not be # available to target for up to the length of the maintanence loop # which by default is 60s. #key_cache: \(aq\(aq # Directory to store job and cache data: # This directory may contain sensitive data and should be protected accordingly. # #cachedir: /var/cache/salt/master # Directory for custom modules. This directory can contain subdirectories for # each of Salt\(aqs module types such as "runners", "output", "wheel", "modules", # "states", "returners", etc. #extension_modules: # Directory for custom modules. This directory can contain subdirectories for # each of Salt\(aqs module types such as "runners", "output", "wheel", "modules", # "states", "returners", "engines", etc. # Like \(aqextension_modules\(aq but can take an array of paths #module_dirs: # \- /var/cache/salt/minion/extmods # Verify and set permissions on configuration directories at startup: #verify_env: True # Set the number of hours to keep old job information in the job cache: #keep_jobs: 24 # The number of seconds to wait when the client is requesting information # about running jobs. #gather_job_timeout: 10 # Set the default timeout for the salt command and api. The default is 5 # seconds. #timeout: 5 # The loop_interval option controls the seconds for the master\(aqs maintenance # process check cycle. This process updates file server backends, cleans the # job cache and executes the scheduler. #loop_interval: 60 # Set the default outputter used by the salt command. The default is "nested". #output: nested # Set the default output file used by the salt command. Default is to output # to the CLI and not to a file. Functions the same way as the "\-\-out\-file" # CLI option, only sets this to a single file for all salt commands. #output_file: None # Return minions that timeout when running commands like test.ping #show_timeout: True # By default, output is colored. To disable colored output, set the color value # to False. #color: True # Do not strip off the colored output from nested results and state outputs # (true by default). # strip_colors: False # To display a summary of the number of minions targeted, the number of # minions returned, and the number of minions that did not return, set the # cli_summary value to True. (False by default.) # #cli_summary: False # Set the directory used to hold unix sockets: #sock_dir: /var/run/salt/master # The master can take a while to start up when lspci and/or dmidecode is used # to populate the grains for the master. Enable if you want to see GPU hardware # data for your master. # enable_gpu_grains: False # The master maintains a job cache. While this is a great addition, it can be # a burden on the master for larger deployments (over 5000 minions). # Disabling the job cache will make previously executed jobs unavailable to # the jobs system and is not generally recommended. #job_cache: True # Cache minion grains, pillar and mine data via the cache subsystem in the # cachedir or a database. #minion_data_cache: True # Cache subsystem module to use for minion data cache. #cache: localfs # Store all returns in the given returner. # Setting this option requires that any returner\-specific configuration also # be set. See various returners in salt/returners for details on required # configuration values. (See also, event_return_queue below.) # #event_return: mysql # On busy systems, enabling event_returns can cause a considerable load on # the storage system for returners. Events can be queued on the master and # stored in a batched fashion using a single transaction for multiple events. # By default, events are not queued. #event_return_queue: 0 # Only return events matching tags in a whitelist, supports glob matches. #event_return_whitelist: # \- salt/master/a_tag # \- salt/run/*/ret # Store all event returns **except** the tags in a blacklist, supports globs. #event_return_blacklist: # \- salt/master/not_this_tag # \- salt/wheel/*/ret # Passing very large events can cause the minion to consume large amounts of # memory. This value tunes the maximum size of a message allowed onto the # master event bus. The value is expressed in bytes. #max_event_size: 1048576 # By default, the master AES key rotates every 24 hours. The next command # following a key rotation will trigger a key refresh from the minion which may # result in minions which do not respond to the first command after a key refresh. # # To tell the master to ping all minions immediately after an AES key refresh, set # ping_on_rotate to True. This should mitigate the issue where a minion does not # appear to initially respond after a key is rotated. # # Note that ping_on_rotate may cause high load on the master immediately after # the key rotation event as minions reconnect. Consider this carefully if this # salt master is managing a large number of minions. # # If disabled, it is recommended to handle this event by listening for the # \(aqaes_key_rotate\(aq event with the \(aqkey\(aq tag and acting appropriately. # ping_on_rotate: False # By default, the master deletes its cache of minion data when the key for that # minion is removed. To preserve the cache after key deletion, set # \(aqpreserve_minion_cache\(aq to True. # # WARNING: This may have security implications if compromised minions auth with # a previous deleted minion ID. #preserve_minion_cache: False # If max_minions is used in large installations, the master might experience # high\-load situations because of having to check the number of connected # minions for every authentication. This cache provides the minion\-ids of # all connected minions to all MWorker\-processes and greatly improves the # performance of max_minions. # con_cache: False # The master can include configuration from other files. To enable this, # pass a list of paths to this option. The paths can be either relative or # absolute; if relative, they are considered to be relative to the directory # the main master configuration file lives in (this file). Paths can make use # of shell\-style globbing. If no files are matched by a path passed to this # option, then the master will log a warning message. # # Include a config file from some other path: # include: /etc/salt/extra_config # # Include config from several files and directories: # include: # \- /etc/salt/extra_config ##### Large\-scale tuning settings ##### ########################################## # Max open files # # Each minion connecting to the master uses AT LEAST one file descriptor, the # master subscription connection. If enough minions connect you might start # seeing on the console (and then salt\-master crashes): # Too many open files (tcp_listener.cpp:335) # Aborted (core dumped) # # By default this value will be the one of \(gaulimit \-Hn\(ga, ie, the hard limit for # max open files. # # If you wish to set a different value than the default one, uncomment and # configure this setting. Remember that this value CANNOT be higher than the # hard limit. Raising the hard limit depends on your OS and/or distribution, # a good way to find the limit is to search the internet. For example: # raise max open files hard limit debian # #max_open_files: 100000 # The number of worker threads to start. These threads are used to manage # return calls made from minions to the master. If the master seems to be # running slowly, increase the number of threads. This setting can not be # set lower than 3. #worker_threads: 5 # Set the ZeroMQ high water marks # http://api.zeromq.org/3\-2:zmq\-setsockopt # The listen queue size / backlog #zmq_backlog: 1000 # The publisher interface ZeroMQPubServerChannel #pub_hwm: 1000 # These two ZMQ HWM settings, salt_event_pub_hwm and event_publisher_pub_hwm # are significant for masters with thousands of minions. When these are # insufficiently high it will manifest in random responses missing in the CLI # and even missing from the job cache. Masters that have fast CPUs and many # cores with appropriate worker_threads will not need these set as high. # On deployment with 8,000 minions, 2.4GHz CPUs, 24 cores, 32GiB memory has # these settings: # # salt_event_pub_hwm: 128000 # event_publisher_pub_hwm: 64000 # ZMQ high\-water\-mark for SaltEvent pub socket #salt_event_pub_hwm: 20000 # ZMQ high\-water\-mark for EventPublisher pub socket #event_publisher_pub_hwm: 10000 # The master may allocate memory per\-event and not # reclaim it. # To set a high\-water mark for memory allocation, use # ipc_write_buffer to set a high\-water mark for message # buffering. # Value: In bytes. Set to \(aqdynamic\(aq to have Salt select # a value for you. Default is disabled. # ipc_write_buffer: \(aqdynamic\(aq ##### Security settings ##### ########################################## # Enable "open mode", this mode still maintains encryption, but turns off # authentication, this is only intended for highly secure environments or for # the situation where your keys end up in a bad state. If you run in open mode # you do so at your own risk! #open_mode: False # Enable auto_accept, this setting will automatically accept all incoming # public keys from the minions. Note that this is insecure. #auto_accept: False # Time in minutes that an incoming public key with a matching name found in # pki_dir/minion_autosign/keyid is automatically accepted. Expired autosign keys # are removed when the master checks the minion_autosign directory. # 0 equals no timeout # autosign_timeout: 120 # If the autosign_file is specified, incoming keys specified in the # autosign_file will be automatically accepted. This is insecure. Regular # expressions as well as globing lines are supported. #autosign_file: /etc/salt/autosign.conf # Works like autosign_file, but instead allows you to specify minion IDs for # which keys will automatically be rejected. Will override both membership in # the autosign_file and the auto_accept setting. #autoreject_file: /etc/salt/autoreject.conf # Enable permissive access to the salt keys. This allows you to run the # master or minion as root, but have a non\-root group be given access to # your pki_dir. To make the access explicit, root must belong to the group # you\(aqve given access to. This is potentially quite insecure. If an autosign_file # is specified, enabling permissive_pki_access will allow group access to that # specific file. #permissive_pki_access: False # Allow users on the master access to execute specific commands on minions. # This setting should be treated with care since it opens up execution # capabilities to non root users. By default this capability is completely # disabled. #publisher_acl: # larry: # \- test.ping # \- network.* # # Blacklist any of the following users or modules # # This example would blacklist all non sudo users, including root from # running any commands. It would also blacklist any use of the "cmd" # module. This is completely disabled by default. # # # Check the list of configured users in client ACL against users on the # system and throw errors if they do not exist. #client_acl_verify: True # #publisher_acl_blacklist: # users: # \- root # \- \(aq^(?!sudo_).*$\(aq # all non sudo users # modules: # \- cmd # # WARNING: client_acl and client_acl_blacklist options are deprecated and will # be removed in the future releases. Use publisher_acl and # publisher_acl_blacklist instead. # Enforce publisher_acl & publisher_acl_blacklist when users have sudo # access to the salt command. # #sudo_acl: False # The external auth system uses the Salt auth modules to authenticate and # validate users to access areas of the Salt system. #external_auth: # pam: # fred: # \- test.* # # Time (in seconds) for a newly generated token to live. Default: 12 hours #token_expire: 43200 # # Allow eauth users to specify the expiry time of the tokens they generate. # A boolean applies to all users or a dictionary of whitelisted eauth backends # and usernames may be given. # token_expire_user_override: # pam: # \- fred # \- tom # ldap: # \- gary # #token_expire_user_override: False # Allow minions to push files to the master. This is disabled by default, for # security purposes. #file_recv: False # Set a hard\-limit on the size of the files that can be pushed to the master. # It will be interpreted as megabytes. Default: 100 #file_recv_max_size: 100 # Signature verification on messages published from the master. # This causes the master to cryptographically sign all messages published to its event # bus, and minions then verify that signature before acting on the message. # # This is False by default. # # Note that to facilitate interoperability with masters and minions that are different # versions, if sign_pub_messages is True but a message is received by a minion with # no signature, it will still be accepted, and a warning message will be logged. # Conversely, if sign_pub_messages is False, but a minion receives a signed # message it will be accepted, the signature will not be checked, and a warning message # will be logged. This behavior went away in Salt 2014.1.0 and these two situations # will cause minion to throw an exception and drop the message. # sign_pub_messages: False # Use TLS/SSL encrypted connection between master and minion. # Can be set to a dictionary containing keyword arguments corresponding to Python\(aqs # \(aqssl.wrap_socket\(aq method. # Default is None. #ssl: # keyfile: # certfile: # ssl_version: PROTOCOL_TLSv1_2 ##### Salt\-SSH Configuration ##### ########################################## # Pass in an alternative location for the salt\-ssh roster file #roster_file: /etc/salt/roster # Define a location for roster files so they can be chosen when using Salt API. # An administrator can place roster files into these locations. Then when # calling Salt API, parameter \(aqroster_file\(aq should contain a relative path to # these locations. That is, "roster_file=/foo/roster" will be resolved as # "/etc/salt/roster.d/foo/roster" etc. This feature prevents passing insecure # custom rosters through the Salt API. # #rosters: # \- /etc/salt/roster.d # \- /opt/salt/some/more/rosters # The log file of the salt\-ssh command: #ssh_log_file: /var/log/salt/ssh # Pass in minion option overrides that will be inserted into the SHIM for # salt\-ssh calls. The local minion config is not used for salt\-ssh. Can be # overridden on a per\-minion basis in the roster (\(gaminion_opts\(ga) #ssh_minion_opts: # gpg_keydir: /root/gpg # Set this to True to default to using ~/.ssh/id_rsa for salt\-ssh # authentication with minions #ssh_use_home_key: False ##### Master Module Management ##### ########################################## # Manage how master side modules are loaded. # Add any additional locations to look for master runners: #runner_dirs: [] # Enable Cython for master side modules: #cython_enable: False ##### State System settings ##### ########################################## # The state system uses a "top" file to tell the minions what environment to # use and what modules to use. The state_top file is defined relative to the # root of the base environment as defined in "File Server settings" below. #state_top: top.sls # The master_tops option replaces the external_nodes option by creating # a plugable system for the generation of external top data. The external_nodes # option is deprecated by the master_tops option. # # To gain the capabilities of the classic external_nodes system, use the # following configuration: # master_tops: # ext_nodes: # #master_tops: {} # The external_nodes option allows Salt to gather data that would normally be # placed in a top file. The external_nodes option is the executable that will # return the ENC data. Remember that Salt will look for external nodes AND top # files and combine the results if both are enabled! #external_nodes: None # The renderer to use on the minions to render the state data #renderer: yaml_jinja # The Jinja renderer can strip extra carriage returns and whitespace # See http://jinja.pocoo.org/docs/api/#high\-level\-api # # If this is set to True the first newline after a Jinja block is removed # (block, not variable tag!). Defaults to False, corresponds to the Jinja # environment init variable "trim_blocks". #jinja_trim_blocks: False # # If this is set to True leading spaces and tabs are stripped from the start # of a line to a block. Defaults to False, corresponds to the Jinja # environment init variable "lstrip_blocks". #jinja_lstrip_blocks: False # The failhard option tells the minions to stop immediately after the first # failure detected in the state execution, defaults to False #failhard: False # The state_verbose and state_output settings can be used to change the way # state system data is printed to the display. By default all data is printed. # The state_verbose setting can be set to True or False, when set to False # all data that has a result of True and no changes will be suppressed. #state_verbose: True # The state_output setting changes if the output is the full multi line # output for each changed state if set to \(aqfull\(aq, but if set to \(aqterse\(aq # the output will be shortened to a single line. If set to \(aqmixed\(aq, the output # will be terse unless a state failed, in which case that output will be full. # If set to \(aqchanges\(aq, the output will be full unless the state didn\(aqt change. #state_output: full # Automatically aggregate all states that have support for mod_aggregate by # setting to \(aqTrue\(aq. Or pass a list of state module names to automatically # aggregate just those types. # # state_aggregate: # \- pkg # #state_aggregate: False # Send progress events as each function in a state run completes execution # by setting to \(aqTrue\(aq. Progress events are in the format # \(aqsalt/job//prog//\(aq. #state_events: False ##### File Server settings ##### ########################################## # Salt runs a lightweight file server written in zeromq to deliver files to # minions. This file server is built into the master daemon and does not # require a dedicated port. # The file server works on environments passed to the master, each environment # can have multiple root directories, the subdirectories in the multiple file # roots cannot match, otherwise the downloaded files will not be able to be # reliably ensured. A base environment is required to house the top file. # Example: # file_roots: # base: # \- /srv/salt/ # dev: # \- /srv/salt/dev/services # \- /srv/salt/dev/states # prod: # \- /srv/salt/prod/services # \- /srv/salt/prod/states # #file_roots: # base: # \- /srv/salt # # When using multiple environments, each with their own top file, the # default behaviour is an unordered merge. To prevent top files from # being merged together and instead to only use the top file from the # requested environment, set this value to \(aqsame\(aq. #top_file_merging_strategy: merge # To specify the order in which environments are merged, set the ordering # in the env_order option. Given a conflict, the last matching value will # win. #env_order: [\(aqbase\(aq, \(aqdev\(aq, \(aqprod\(aq] # If top_file_merging_strategy is set to \(aqsame\(aq and an environment does not # contain a top file, the top file in the environment specified by default_top # will be used instead. #default_top: base # The hash_type is the hash to use when discovering the hash of a file on # the master server. The default is md5 but sha1, sha224, sha256, sha384 # and sha512 are also supported. # # WARNING: While md5 is also supported, do not use it due to the high chance # of possible collisions and thus security breach. # # Prior to changing this value, the master should be stopped and all Salt # caches should be cleared. #hash_type: sha256 # The buffer size in the file server can be adjusted here: #file_buffer_size: 1048576 # A regular expression (or a list of expressions) that will be matched # against the file path before syncing the modules and states to the minions. # This includes files affected by the file.recurse state. # For example, if you manage your custom modules and states in subversion # and don\(aqt want all the \(aq.svn\(aq folders and content synced to your minions, # you could set this to \(aq/\e.svn($|/)\(aq. By default nothing is ignored. #file_ignore_regex: # \- \(aq/\e.svn($|/)\(aq # \- \(aq/\e.git($|/)\(aq # A file glob (or list of file globs) that will be matched against the file # path before syncing the modules and states to the minions. This is similar # to file_ignore_regex above, but works on globs instead of regex. By default # nothing is ignored. # file_ignore_glob: # \- \(aq*.pyc\(aq # \- \(aq*/somefolder/*.bak\(aq # \- \(aq*.swp\(aq # File Server Backend # # Salt supports a modular fileserver backend system, this system allows # the salt master to link directly to third party systems to gather and # manage the files available to minions. Multiple backends can be # configured and will be searched for the requested file in the order in which # they are defined here. The default setting only enables the standard backend # "roots" which uses the "file_roots" option. #fileserver_backend: # \- roots # # To use multiple backends list them in the order they are searched: #fileserver_backend: # \- git # \- roots # # Uncomment the line below if you do not want the file_server to follow # symlinks when walking the filesystem tree. This is set to True # by default. Currently this only applies to the default roots # fileserver_backend. #fileserver_followsymlinks: False # # Uncomment the line below if you do not want symlinks to be # treated as the files they are pointing to. By default this is set to # False. By uncommenting the line below, any detected symlink while listing # files on the Master will not be returned to the Minion. #fileserver_ignoresymlinks: True # # By default, the Salt fileserver recurses fully into all defined environments # to attempt to find files. To limit this behavior so that the fileserver only # traverses directories with SLS files and special Salt directories like _modules, # enable the option below. This might be useful for installations where a file root # has a very large number of files and performance is impacted. Default is False. # fileserver_limit_traversal: False # # The fileserver can fire events off every time the fileserver is updated, # these are disabled by default, but can be easily turned on by setting this # flag to True #fileserver_events: False # Git File Server Backend Configuration # # Optional parameter used to specify the provider to be used for gitfs. Must # be one of the following: pygit2, gitpython, or dulwich. If unset, then each # will be tried in that same order, and the first one with a compatible # version installed will be the provider that is used. #gitfs_provider: pygit2 # Along with gitfs_password, is used to authenticate to HTTPS remotes. # gitfs_user: \(aq\(aq # Along with gitfs_user, is used to authenticate to HTTPS remotes. # This parameter is not required if the repository does not use authentication. #gitfs_password: \(aq\(aq # By default, Salt will not authenticate to an HTTP (non\-HTTPS) remote. # This parameter enables authentication over HTTP. Enable this at your own risk. #gitfs_insecure_auth: False # Along with gitfs_privkey (and optionally gitfs_passphrase), is used to # authenticate to SSH remotes. This parameter (or its per\-remote counterpart) # is required for SSH remotes. #gitfs_pubkey: \(aq\(aq # Along with gitfs_pubkey (and optionally gitfs_passphrase), is used to # authenticate to SSH remotes. This parameter (or its per\-remote counterpart) # is required for SSH remotes. #gitfs_privkey: \(aq\(aq # This parameter is optional, required only when the SSH key being used to # authenticate is protected by a passphrase. #gitfs_passphrase: \(aq\(aq # When using the git fileserver backend at least one git remote needs to be # defined. The user running the salt master will need read access to the repo. # # The repos will be searched in order to find the file requested by a client # and the first repo to have the file will return it. # When using the git backend branches and tags are translated into salt # environments. # Note: file:// repos will be treated as a remote, so refs you want used must # exist in that repo as *local* refs. #gitfs_remotes: # \- git://github.com/saltstack/salt\-states.git # \- file:///var/git/saltmaster # # The gitfs_ssl_verify option specifies whether to ignore ssl certificate # errors when contacting the gitfs backend. You might want to set this to # false if you\(aqre using a git backend that uses a self\-signed certificate but # keep in mind that setting this flag to anything other than the default of True # is a security concern, you may want to try using the ssh transport. #gitfs_ssl_verify: True # # The gitfs_root option gives the ability to serve files from a subdirectory # within the repository. The path is defined relative to the root of the # repository and defaults to the repository root. #gitfs_root: somefolder/otherfolder # # ##### Pillar settings ##### ########################################## # Salt Pillars allow for the building of global data that can be made selectively # available to different minions based on minion grain filtering. The Salt # Pillar is laid out in the same fashion as the file server, with environments, # a top file and sls files. However, pillar data does not need to be in the # highstate format, and is generally just key/value pairs. #pillar_roots: # base: # \- /srv/pillar # #ext_pillar: # \- hiera: /etc/hiera.yaml # \- cmd_yaml: cat /etc/salt/yaml # The ext_pillar_first option allows for external pillar sources to populate # before file system pillar. This allows for targeting file system pillar from # ext_pillar. #ext_pillar_first: False # The pillar_gitfs_ssl_verify option specifies whether to ignore ssl certificate # errors when contacting the pillar gitfs backend. You might want to set this to # false if you\(aqre using a git backend that uses a self\-signed certificate but # keep in mind that setting this flag to anything other than the default of True # is a security concern, you may want to try using the ssh transport. #pillar_gitfs_ssl_verify: True # The pillar_opts option adds the master configuration file data to a dict in # the pillar called "master". This is used to set simple configurations in the # master config file that can then be used on minions. #pillar_opts: False # The pillar_safe_render_error option prevents the master from passing pillar # render errors to the minion. This is set on by default because the error could # contain templating data which would give that minion information it shouldn\(aqt # have, like a password! When set true the error message will only show: # Rendering SLS \(aqmy.sls\(aq failed. Please see master log for details. #pillar_safe_render_error: True # The pillar_source_merging_strategy option allows you to configure merging strategy # between different sources. It accepts five values: none, recurse, aggregate, overwrite, # or smart. None will not do any merging at all. Recurse will merge recursively mapping of data. # Aggregate instructs aggregation of elements between sources that use the #!yamlex renderer. Overwrite # will overwrite elements according the order in which they are processed. This is # behavior of the 2014.1 branch and earlier. Smart guesses the best strategy based # on the "renderer" setting and is the default value. #pillar_source_merging_strategy: smart # Recursively merge lists by aggregating them instead of replacing them. #pillar_merge_lists: False # Set this option to \(aqTrue\(aq to force a \(aqKeyError\(aq to be raised whenever an # attempt to retrieve a named value from pillar fails. When this option is set # to \(aqFalse\(aq, the failed attempt returns an empty string. Default is \(aqFalse\(aq. #pillar_raise_on_missing: False # Git External Pillar (git_pillar) Configuration Options # # Specify the provider to be used for git_pillar. Must be either pygit2 or # gitpython. If unset, then both will be tried in that same order, and the # first one with a compatible version installed will be the provider that # is used. #git_pillar_provider: pygit2 # If the desired branch matches this value, and the environment is omitted # from the git_pillar configuration, then the environment for that git_pillar # remote will be base. #git_pillar_base: master # If the branch is omitted from a git_pillar remote, then this branch will # be used instead #git_pillar_branch: master # Environment to use for git_pillar remotes. This is normally derived from # the branch/tag (or from a per\-remote env parameter), but if set this will # override the process of deriving the env from the branch/tag name. #git_pillar_env: \(aq\(aq # Path relative to the root of the repository where the git_pillar top file # and SLS files are located. #git_pillar_root: \(aq\(aq # Specifies whether or not to ignore SSL certificate errors when contacting # the remote repository. #git_pillar_ssl_verify: False # When set to False, if there is an update/checkout lock for a git_pillar # remote and the pid written to it is not running on the master, the lock # file will be automatically cleared and a new lock will be obtained. #git_pillar_global_lock: True # Git External Pillar Authentication Options # # Along with git_pillar_password, is used to authenticate to HTTPS remotes. #git_pillar_user: \(aq\(aq # Along with git_pillar_user, is used to authenticate to HTTPS remotes. # This parameter is not required if the repository does not use authentication. #git_pillar_password: \(aq\(aq # By default, Salt will not authenticate to an HTTP (non\-HTTPS) remote. # This parameter enables authentication over HTTP. #git_pillar_insecure_auth: False # Along with git_pillar_privkey (and optionally git_pillar_passphrase), # is used to authenticate to SSH remotes. #git_pillar_pubkey: \(aq\(aq # Along with git_pillar_pubkey (and optionally git_pillar_passphrase), # is used to authenticate to SSH remotes. #git_pillar_privkey: \(aq\(aq # This parameter is optional, required only when the SSH key being used # to authenticate is protected by a passphrase. #git_pillar_passphrase: \(aq\(aq # A master can cache pillars locally to bypass the expense of having to render them # for each minion on every request. This feature should only be enabled in cases # where pillar rendering time is known to be unsatisfactory and any attendant security # concerns about storing pillars in a master cache have been addressed. # # When enabling this feature, be certain to read through the additional \(ga\(gapillar_cache_*\(ga\(ga # configuration options to fully understand the tunable parameters and their implications. # # Note: setting \(ga\(gapillar_cache: True\(ga\(ga has no effect on targeting Minions with Pillars. # See https://docs.saltstack.com/en/latest/topics/targeting/pillar.html #pillar_cache: False # If and only if a master has set \(ga\(gapillar_cache: True\(ga\(ga, the cache TTL controls the amount # of time, in seconds, before the cache is considered invalid by a master and a fresh # pillar is recompiled and stored. #pillar_cache_ttl: 3600 # If and only if a master has set \(gapillar_cache: True\(ga, one of several storage providers # can be utililzed. # # \(gadisk\(ga: The default storage backend. This caches rendered pillars to the master cache. # Rendered pillars are serialized and deserialized as msgpack structures for speed. # Note that pillars are stored UNENCRYPTED. Ensure that the master cache # has permissions set appropriately. (Same defaults are provided.) # # memory: [EXPERIMENTAL] An optional backend for pillar caches which uses a pure\-Python # in\-memory data structure for maximal performance. There are several caveats, # however. First, because each master worker contains its own in\-memory cache, # there is no guarantee of cache consistency between minion requests. This # works best in situations where the pillar rarely if ever changes. Secondly, # and perhaps more importantly, this means that unencrypted pillars will # be accessible to any process which can examine the memory of the \(ga\(gasalt\-master\(ga\(ga! # This may represent a substantial security risk. # #pillar_cache_backend: disk ##### Syndic settings ##### ########################################## # The Salt syndic is used to pass commands through a master from a higher # master. Using the syndic is simple. If this is a master that will have # syndic servers(s) below it, then set the "order_masters" setting to True. # # If this is a master that will be running a syndic daemon for passthrough, then # the "syndic_master" setting needs to be set to the location of the master server # to receive commands from. # Set the order_masters setting to True if this master will command lower # masters\(aq syndic interfaces. #order_masters: False # If this master will be running a salt syndic daemon, syndic_master tells # this master where to receive commands from. #syndic_master: masterofmasters # This is the \(aqret_port\(aq of the MasterOfMaster: #syndic_master_port: 4506 # PID file of the syndic daemon: #syndic_pidfile: /var/run/salt\-syndic.pid # The log file of the salt\-syndic daemon: #syndic_log_file: /var/log/salt/syndic # The behaviour of the multi\-syndic when connection to a master of masters failed. # Can specify \(ga\(garandom\(ga\(ga (default) or \(ga\(gaordered\(ga\(ga. If set to \(ga\(garandom\(ga\(ga, masters # will be iterated in random order. If \(ga\(gaordered\(ga\(ga is specified, the configured # order will be used. #syndic_failover: random # The number of seconds for the salt client to wait for additional syndics to # check in with their lists of expected minions before giving up. #syndic_wait: 5 ##### Peer Publish settings ##### ########################################## # Salt minions can send commands to other minions, but only if the minion is # allowed to. By default "Peer Publication" is disabled, and when enabled it # is enabled for specific minions and specific commands. This allows secure # compartmentalization of commands based on individual minions. # The configuration uses regular expressions to match minions and then a list # of regular expressions to match functions. The following will allow the # minion authenticated as foo.example.com to execute functions from the test # and pkg modules. #peer: # foo.example.com: # \- test.* # \- pkg.* # # This will allow all minions to execute all commands: #peer: # .*: # \- .* # # This is not recommended, since it would allow anyone who gets root on any # single minion to instantly have root on all of the minions! # Minions can also be allowed to execute runners from the salt master. # Since executing a runner from the minion could be considered a security risk, # it needs to be enabled. This setting functions just like the peer setting # except that it opens up runners instead of module functions. # # All peer runner support is turned off by default and must be enabled before # using. This will enable all peer runners for all minions: #peer_run: # .*: # \- .* # # To enable just the manage.up runner for the minion foo.example.com: #peer_run: # foo.example.com: # \- manage.up # # ##### Mine settings ##### ##################################### # Restrict mine.get access from minions. By default any minion has a full access # to get all mine data from master cache. In acl definion below, only pcre matches # are allowed. # mine_get: # .*: # \- .* # # The example below enables minion foo.example.com to get \(aqnetwork.interfaces\(aq mine # data only, minions web* to get all network.* and disk.* mine data and all other # minions won\(aqt get any mine data. # mine_get: # foo.example.com: # \- network.interfaces # web.*: # \- network.* # \- disk.* ##### Logging settings ##### ########################################## # The location of the master log file # The master log 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.: # \(ga\(gafile:///dev/log\(ga\(ga), with rsyslogd(8) configured for network logging. The URI # format is: ://:/ #log_file: /var/log/salt/master #log_file: file:///dev/log #log_file: udp://loghost:10514 #log_file: /var/log/salt/master #key_logfile: /var/log/salt/key # The level of messages to send to the console. # One of \(aqgarbage\(aq, \(aqtrace\(aq, \(aqdebug\(aq, info\(aq, \(aqwarning\(aq, \(aqerror\(aq, \(aqcritical\(aq. # # The following log levels are considered INSECURE and may log sensitive data: # [\(aqgarbage\(aq, \(aqtrace\(aq, \(aqdebug\(aq] # #log_level: warning # The level of messages to send to the log file. # One of \(aqgarbage\(aq, \(aqtrace\(aq, \(aqdebug\(aq, info\(aq, \(aqwarning\(aq, \(aqerror\(aq, \(aqcritical\(aq. # If using \(aqlog_granular_levels\(aq this must be set to the highest desired level. #log_level_logfile: warning # The date and time format used in log messages. Allowed date/time formatting # can be seen here: http://docs.python.org/library/time.html#time.strftime #log_datefmt: \(aq%H:%M:%S\(aq #log_datefmt_logfile: \(aq%Y\-%m\-%d %H:%M:%S\(aq # The format of the console logging messages. Allowed formatting options can # be seen here: http://docs.python.org/library/logging.html#logrecord\-attributes # # Console log colors are specified by these additional formatters: # # %(colorlevel)s # %(colorname)s # %(colorprocess)s # %(colormsg)s # # Since it is desirable to include the surrounding brackets, \(aq[\(aq and \(aq]\(aq, in # the coloring of the messages, these color formatters also include padding as # well. Color LogRecord attributes are only available for console logging. # #log_fmt_console: \(aq%(colorlevel)s %(colormsg)s\(aq #log_fmt_console: \(aq[%(levelname)\-8s] %(message)s\(aq # #log_fmt_logfile: \(aq%(asctime)s,%(msecs)03d [%(name)\-17s][%(levelname)\-8s] %(message)s\(aq # This can be used to control logging levels more specificically. This # example sets the main salt library at the \(aqwarning\(aq level, but sets # \(aqsalt.modules\(aq to log at the \(aqdebug\(aq level: # log_granular_levels: # \(aqsalt\(aq: \(aqwarning\(aq # \(aqsalt.modules\(aq: \(aqdebug\(aq # #log_granular_levels: {} ##### Node Groups ###### ########################################## # Node groups allow for logical groupings of minion nodes. A group consists of # a group name and a compound target. Nodgroups can reference other nodegroups # with \(aqN@\(aq classifier. Ensure that you do not have circular references. # #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 # group3: \(aqG@os:Debian and N@group1\(aq # group4: # \- \(aqG@foo:bar\(aq # \- \(aqor\(aq # \- \(aqG@foo:baz\(aq ##### Range Cluster settings ##### ########################################## # The range server (and optional port) that serves your cluster information # https://github.com/ytoolshed/range/wiki/%22yamlfile%22\-module\-file\-spec # #range_server: range:80 ##### Windows Software Repo settings ##### ########################################### # Location of the repo on the master: #winrepo_dir_ng: \(aq/srv/salt/win/repo\-ng\(aq # # List of git repositories to include with the local repo: #winrepo_remotes_ng: # \- \(aqhttps://github.com/saltstack/salt\-winrepo\-ng.git\(aq ##### Windows Software Repo settings \- Pre 2015.8 ##### ######################################################## # Legacy repo settings for pre\-2015.8 Windows minions. # # Location of the repo on the master: #winrepo_dir: \(aq/srv/salt/win/repo\(aq # # Location of the master\(aqs repo cache file: #winrepo_mastercachefile: \(aq/srv/salt/win/repo/winrepo.p\(aq # # List of git repositories to include with the local repo: #winrepo_remotes: # \- \(aqhttps://github.com/saltstack/salt\-winrepo.git\(aq ##### Returner settings ###### ############################################ # Which returner(s) will be used for minion\(aqs result: #return: mysql ###### Miscellaneous settings ###### ############################################ # Default match type for filtering events tags: startswith, endswith, find, regex, fnmatch #event_match_type: startswith # Save runner returns to the job cache #runner_returns: True # Permanently include any available Python 3rd party modules into Salt Thin # when they are generated for Salt\-SSH or other purposes. # The modules should be named by the names they are actually imported inside the Python. # The value of the parameters can be either one module or a comma separated list of them. #thin_extra_mods: foo,bar .ft P .fi .UNINDENT .UNINDENT .SS Example minion configuration file .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C ##### Primary configuration settings ##### ########################################## # This configuration file is used to manage the behavior of the Salt Minion. # With the exception of the location of the Salt Master Server, values that are # commented out but have an empty line after the comment are defaults that need # not be set in the config. If there is no blank line after the comment, the # value is presented as an example and is not the default. # Per default the minion will automatically include all config files # from minion.d/*.conf (minion.d is a directory in the same directory # as the main minion config file). #default_include: minion.d/*.conf # Set the location of the salt master server. If the master server cannot be # resolved, then the minion will fail to start. #master: salt # Set http proxy information for the minion when doing requests #proxy_host: #proxy_port: #proxy_username: #proxy_password: # If multiple masters are specified in the \(aqmaster\(aq setting, the default behavior # is to always try to connect to them in the order they are listed. If random_master is # set to True, the order will be randomized instead. This can be helpful in distributing # the load of many minions executing salt\-call requests, for example, from a cron job. # If only one master is listed, this setting is ignored and a warning will be logged. # NOTE: If master_type is set to failover, use master_shuffle instead. #random_master: False # Use if master_type is set to failover. #master_shuffle: False # Minions can connect to multiple masters simultaneously (all masters # are "hot"), or can be configured to failover if a master becomes # unavailable. Multiple hot masters are configured by setting this # value to "str". Failover masters can be requested by setting # to "failover". MAKE SURE TO SET master_alive_interval if you are # using failover. # Setting master_type to \(aqdisable\(aq let\(aqs you have a running minion (with engines and # beacons) without a master connection # master_type: str # Poll interval in seconds for checking if the master is still there. Only # respected if master_type above is "failover". To disable the interval entirely, # set the value to \-1. (This may be necessary on machines which have high numbers # of TCP connections, such as load balancers.) # master_alive_interval: 30 # If the minion is in multi\-master mode and the master_type configuration option # is set to "failover", this setting can be set to "True" to force the minion # to fail back to the first master in the list if the first master is back online. #master_failback: False # If the minion is in multi\-master mode, the "master_type" configuration is set to # "failover", and the "master_failback" option is enabled, the master failback # interval can be set to ping the top master with this interval, in seconds. #master_failback_interval: 0 # Set whether the minion should connect to the master via IPv6: #ipv6: False # Set the number of seconds to wait before attempting to resolve # the master hostname if name resolution fails. Defaults to 30 seconds. # Set to zero if the minion should shutdown and not retry. # retry_dns: 30 # Set the port used by the master reply and authentication server. #master_port: 4506 # The user to run salt. #user: root # The user to run salt remote execution commands as via sudo. If this option is # enabled then sudo will be used to change the active user executing the remote # command. If enabled the user will need to be allowed access via the sudoers # file for the user that the salt minion is configured to run as. The most # common option would be to use the root user. If this option is set the user # option should also be set to a non\-root user. If migrating from a root minion # to a non root minion the minion cache should be cleared and the minion pki # directory will need to be changed to the ownership of the new user. #sudo_user: root # Specify the location of the daemon process ID file. #pidfile: /var/run/salt\-minion.pid # The root directory prepended to these options: pki_dir, cachedir, log_file, # sock_dir, pidfile. #root_dir: / # The path to the minion\(aqs configuration file. #conf_file: /etc/salt/minion # The directory to store the pki information in #pki_dir: /etc/salt/pki/minion # Explicitly declare the id for this minion to use, if left commented the id # will be the hostname as returned by the python call: socket.getfqdn() # Since salt uses detached ids it is possible to run multiple minions on the # same machine but with different ids, this can be useful for salt compute # clusters. #id: # Cache the minion id to a file when the minion\(aqs id is not statically defined # in the minion config. Defaults to "True". This setting prevents potential # problems when automatic minion id resolution changes, which can cause the # minion to lose connection with the master. To turn off minion id caching, # set this config to \(ga\(gaFalse\(ga\(ga. #minion_id_caching: True # Append a domain to a hostname in the event that it does not exist. This is # useful for systems where socket.getfqdn() does not actually result in a # FQDN (for instance, Solaris). #append_domain: # Custom static grains for this minion can be specified here and used in SLS # files just like all other grains. This example sets 4 custom grains, with # the \(aqroles\(aq grain having two values that can be matched against. #grains: # roles: # \- webserver # \- memcache # deployment: datacenter4 # cabinet: 13 # cab_u: 14\-15 # # Where cache data goes. # This data may contain sensitive data and should be protected accordingly. #cachedir: /var/cache/salt/minion # Append minion_id to these directories. Helps with # multiple proxies and minions running on the same machine. # Allowed elements in the list: pki_dir, cachedir, extension_modules # Normally not needed unless running several proxies and/or minions on the same machine # Defaults to [\(aqcachedir\(aq] for proxies, [] (empty list) for regular minions #append_minionid_config_dirs: # Verify and set permissions on configuration directories at startup. #verify_env: True # The minion can locally cache the return data from jobs sent to it, this # can be a good way to keep track of jobs the minion has executed # (on the minion side). By default this feature is disabled, to enable, set # cache_jobs to True. #cache_jobs: False # Set the directory used to hold unix sockets. #sock_dir: /var/run/salt/minion # Set the default outputter used by the salt\-call command. The default is # "nested". #output: nested # # By default output is colored. To disable colored output, set the color value # to False. #color: True # Do not strip off the colored output from nested results and state outputs # (true by default). # strip_colors: False # Backup files that are replaced by file.managed and file.recurse under # \(aqcachedir\(aq/file_backups relative to their original location and appended # with a timestamp. The only valid setting is "minion". Disabled by default. # # Alternatively this can be specified for each file in state files: # /etc/ssh/sshd_config: # file.managed: # \- source: salt://ssh/sshd_config # \- backup: minion # #backup_mode: minion # When waiting for a master to accept the minion\(aqs public key, salt will # continuously attempt to reconnect until successful. This is the time, in # seconds, between those reconnection attempts. #acceptance_wait_time: 10 # If this is nonzero, the time between reconnection attempts will increase by # acceptance_wait_time seconds per iteration, up to this maximum. If this is # set to zero, the time between reconnection attempts will stay constant. #acceptance_wait_time_max: 0 # If the master rejects the minion\(aqs public key, retry instead of exiting. # Rejected keys will be handled the same as waiting on acceptance. #rejected_retry: False # When the master key changes, the minion will try to re\-auth itself to receive # the new master key. In larger environments this can cause a SYN flood on the # master because all minions try to re\-auth immediately. To prevent this and # have a minion wait for a random amount of time, use this optional parameter. # The wait\-time will be a random number of seconds between 0 and the defined value. #random_reauth_delay: 60 # When waiting for a master to accept the minion\(aqs public key, salt will # continuously attempt to reconnect until successful. This is the timeout value, # in seconds, for each individual attempt. After this timeout expires, the minion # will wait for acceptance_wait_time seconds before trying again. Unless your master # is under unusually heavy load, this should be left at the default. #auth_timeout: 60 # Number of consecutive SaltReqTimeoutError that are acceptable when trying to # authenticate. #auth_tries: 7 # The number of attempts to connect to a master before giving up. # Set this to \-1 for unlimited attempts. This allows for a master to have # downtime and the minion to reconnect to it later when it comes back up. # In \(aqfailover\(aq mode, it is the number of attempts for each set of masters. # In this mode, it will cycle through the list of masters for each attempt. # # This is different than auth_tries because auth_tries attempts to # retry auth attempts with a single master. auth_tries is under the # assumption that you can connect to the master but not gain # authorization from it. master_tries will still cycle through all # the masters in a given try, so it is appropriate if you expect # occasional downtime from the master(s). #master_tries: 1 # If authentication fails due to SaltReqTimeoutError during a ping_interval, # cause sub minion process to restart. #auth_safemode: False # Ping Master to ensure connection is alive (minutes). #ping_interval: 0 # To auto recover minions if master changes IP address (DDNS) # auth_tries: 10 # auth_safemode: False # ping_interval: 90 # # Minions won\(aqt know master is missing until a ping fails. After the ping fail, # the minion will attempt authentication and likely fails out and cause a restart. # When the minion restarts it will resolve the masters IP and attempt to reconnect. # If you don\(aqt have any problems with syn\-floods, don\(aqt bother with the # three recon_* settings described below, just leave the defaults! # # The ZeroMQ pull\-socket that binds to the masters publishing interface tries # to reconnect immediately, if the socket is disconnected (for example if # the master processes are restarted). In large setups this will have all # minions reconnect immediately which might flood the master (the ZeroMQ\-default # is usually a 100ms delay). To prevent this, these three recon_* settings # can be used. # recon_default: the interval in milliseconds that the socket should wait before # trying to reconnect to the master (1000ms = 1 second) # # recon_max: the maximum time a socket should wait. each interval the time to wait # is calculated by doubling the previous time. if recon_max is reached, # it starts again at recon_default. Short example: # # reconnect 1: the socket will wait \(aqrecon_default\(aq milliseconds # reconnect 2: \(aqrecon_default\(aq * 2 # reconnect 3: (\(aqrecon_default\(aq * 2) * 2 # reconnect 4: value from previous interval * 2 # reconnect 5: value from previous interval * 2 # reconnect x: if value >= recon_max, it starts again with recon_default # # recon_randomize: generate a random wait time on minion start. The wait time will # be a random value between recon_default and recon_default + # recon_max. Having all minions reconnect with the same recon_default # and recon_max value kind of defeats the purpose of being able to # change these settings. If all minions have the same values and your # setup is quite large (several thousand minions), they will still # flood the master. The desired behavior is to have timeframe within # all minions try to reconnect. # # Example on how to use these settings. The goal: have all minions reconnect within a # 60 second timeframe on a disconnect. # recon_default: 1000 # recon_max: 59000 # recon_randomize: True # # Each minion will have a randomized reconnect value between \(aqrecon_default\(aq # and \(aqrecon_default + recon_max\(aq, which in this example means between 1000ms # 60000ms (or between 1 and 60 seconds). The generated random\-value will be # doubled after each attempt to reconnect. Lets say the generated random # value is 11 seconds (or 11000ms). # reconnect 1: wait 11 seconds # reconnect 2: wait 22 seconds # reconnect 3: wait 33 seconds # reconnect 4: wait 44 seconds # reconnect 5: wait 55 seconds # reconnect 6: wait time is bigger than 60 seconds (recon_default + recon_max) # reconnect 7: wait 11 seconds # reconnect 8: wait 22 seconds # reconnect 9: wait 33 seconds # reconnect x: etc. # # In a setup with ~6000 thousand hosts these settings would average the reconnects # to about 100 per second and all hosts would be reconnected within 60 seconds. # recon_default: 100 # recon_max: 5000 # recon_randomize: False # # # The loop_interval sets how long in seconds the minion will wait between # evaluating the scheduler and running cleanup tasks. This defaults to 1 # second on the minion scheduler. #loop_interval: 1 # Some installations choose to start all job returns in a cache or a returner # and forgo sending the results back to a master. In this workflow, jobs # are most often executed with \-\-async from the Salt CLI and then results # are evaluated by examining job caches on the minions or any configured returners. # WARNING: Setting this to False will **disable** returns back to the master. #pub_ret: True # The grains can be merged, instead of overridden, using this option. # This allows custom grains to defined different subvalues of a dictionary # grain. By default this feature is disabled, to enable set grains_deep_merge # to \(ga\(gaTrue\(ga\(ga. #grains_deep_merge: False # The grains_refresh_every setting allows for a minion to periodically check # its grains to see if they have changed and, if so, to inform the master # of the new grains. This operation is moderately expensive, therefore # care should be taken not to set this value too low. # # Note: This value is expressed in __minutes__! # # A value of 10 minutes is a reasonable default. # # If the value is set to zero, this check is disabled. #grains_refresh_every: 1 # Cache grains on the minion. Default is False. #grains_cache: False # Cache rendered pillar data on the minion. Default is False. # This may cause \(aqcachedir\(aq/pillar to contain sensitive data that should be # protected accordingly. #minion_pillar_cache: False # Grains cache expiration, in seconds. If the cache file is older than this # number of seconds then the grains cache will be dumped and fully re\-populated # with fresh data. Defaults to 5 minutes. Will have no effect if \(aqgrains_cache\(aq # is not enabled. # grains_cache_expiration: 300 # Determines whether or not the salt minion should run scheduled mine updates. # Defaults to "True". Set to "False" to disable the scheduled mine updates # (this essentially just does not add the mine update function to the minion\(aqs # scheduler). #mine_enabled: True # Determines whether or not scheduled mine updates should be accompanied by a job # return for the job cache. Defaults to "False". Set to "True" to include job # returns in the job cache for mine updates. #mine_return_job: False # Example functions that can be run via the mine facility # NO mine functions are established by default. # Note these can be defined in the minion\(aqs pillar as well. #mine_functions: # test.ping: [] # network.ip_addrs: # interface: eth0 # cidr: \(aq10.0.0.0/8\(aq # Windows platforms lack posix IPC and must rely on slower TCP based inter\- # process communications. Set ipc_mode to \(aqtcp\(aq on such systems #ipc_mode: ipc # Overwrite the default tcp ports used by the minion when in tcp mode #tcp_pub_port: 4510 #tcp_pull_port: 4511 # Passing very large events can cause the minion to consume large amounts of # memory. This value tunes the maximum size of a message allowed onto the # minion event bus. The value is expressed in bytes. #max_event_size: 1048576 # To detect failed master(s) and fire events on connect/disconnect, set # master_alive_interval to the number of seconds to poll the masters for # connection events. # #master_alive_interval: 30 # The minion can include configuration from other files. To enable this, # pass a list of paths to this option. The paths can be either relative or # absolute; if relative, they are considered to be relative to the directory # the main minion configuration file lives in (this file). Paths can make use # of shell\-style globbing. If no files are matched by a path passed to this # option then the minion will log a warning message. # # Include a config file from some other path: # include: /etc/salt/extra_config # # Include config from several files and directories: #include: # \- /etc/salt/extra_config # \- /etc/roles/webserver # The syndic minion can verify that it is talking to the correct master via the # key fingerprint of the higher\-level master with the "syndic_finger" config. #syndic_finger: \(aq\(aq # # # ##### Minion module management ##### ########################################## # Disable specific modules. This allows the admin to limit the level of # access the master has to the minion. The default here is the empty list, # below is an example of how this needs to be formatted in the config file #disable_modules: # \- cmdmod # \- test #disable_returners: [] # This is the reverse of disable_modules. The default, like disable_modules, is the empty list, # but if this option is set to *anything* then *only* those modules will load. # Note that this is a very large hammer and it can be quite difficult to keep the minion working # the way you think it should since Salt uses many modules internally itself. At a bare minimum # you need the following enabled or else the minion won\(aqt start. #whitelist_modules: # \- cmdmod # \- test # \- config # Modules can be loaded from arbitrary paths. This enables the easy deployment # of third party modules. Modules for returners and minions can be loaded. # Specify a list of extra directories to search for minion modules and # returners. These paths must be fully qualified! #module_dirs: [] #returner_dirs: [] #states_dirs: [] #render_dirs: [] #utils_dirs: [] # # A module provider can be statically overwritten or extended for the minion # via the providers option, in this case the default module will be # overwritten by the specified module. In this example the pkg module will # be provided by the yumpkg5 module instead of the system default. #providers: # pkg: yumpkg5 # # Enable Cython modules searching and loading. (Default: False) #cython_enable: False # # Specify a max size (in bytes) for modules on import. This feature is currently # only supported on *nix operating systems and requires psutil. # modules_max_memory: \-1 ##### State Management Settings ##### ########################################### # The state management system executes all of the state templates on the minion # to enable more granular control of system state management. The type of # template and serialization used for state management needs to be configured # on the minion, the default renderer is yaml_jinja. This is a yaml file # rendered from a jinja template, the available options are: # yaml_jinja # yaml_mako # yaml_wempy # json_jinja # json_mako # json_wempy # #renderer: yaml_jinja # # The failhard option tells the minions to stop immediately after the first # failure detected in the state execution. Defaults to False. #failhard: False # # Reload the modules prior to a highstate run. #autoload_dynamic_modules: True # # clean_dynamic_modules keeps the dynamic modules on the minion in sync with # the dynamic modules on the master, this means that if a dynamic module is # not on the master it will be deleted from the minion. By default, this is # enabled and can be disabled by changing this value to False. #clean_dynamic_modules: True # # Normally, the minion is not isolated to any single environment on the master # when running states, but the environment can be isolated on the minion side # by statically setting it. Remember that the recommended way to manage # environments is to isolate via the top file. #environment: None # # Isolates the pillar environment on the minion side. This functions the same # as the environment setting, but for pillar instead of states. #pillarenv: None # # Set this option to \(aqTrue\(aq to force a \(aqKeyError\(aq to be raised whenever an # attempt to retrieve a named value from pillar fails. When this option is set # to \(aqFalse\(aq, the failed attempt returns an empty string. Default is \(aqFalse\(aq. #pillar_raise_on_missing: False # # If using the local file directory, then the state top file name needs to be # defined, by default this is top.sls. #state_top: top.sls # # Run states when the minion daemon starts. To enable, set startup_states to: # \(aqhighstate\(aq \-\- Execute state.highstate # \(aqsls\(aq \-\- Read in the sls_list option and execute the named sls files # \(aqtop\(aq \-\- Read top_file option and execute based on that file on the Master #startup_states: \(aq\(aq # # List of states to run when the minion starts up if startup_states is \(aqsls\(aq: #sls_list: # \- edit.vim # \- hyper # # Top file to execute if startup_states is \(aqtop\(aq: #top_file: \(aq\(aq # Automatically aggregate all states that have support for mod_aggregate by # setting to True. Or pass a list of state module names to automatically # aggregate just those types. # # state_aggregate: # \- pkg # #state_aggregate: False ##### File Directory Settings ##### ########################################## # The Salt Minion can redirect all file server operations to a local directory, # this allows for the same state tree that is on the master to be used if # copied completely onto the minion. This is a literal copy of the settings on # the master but used to reference a local directory on the minion. # Set the file client. The client defaults to looking on the master server for # files, but can be directed to look at the local file directory setting # defined below by setting it to "local". Setting a local file_client runs the # minion in masterless mode. #file_client: remote # The file directory works on environments passed to the minion, each environment # can have multiple root directories, the subdirectories in the multiple file # roots cannot match, otherwise the downloaded files will not be able to be # reliably ensured. A base environment is required to house the top file. # Example: # file_roots: # base: # \- /srv/salt/ # dev: # \- /srv/salt/dev/services # \- /srv/salt/dev/states # prod: # \- /srv/salt/prod/services # \- /srv/salt/prod/states # #file_roots: # base: # \- /srv/salt # Uncomment the line below if you do not want the file_server to follow # symlinks when walking the filesystem tree. This is set to True # by default. Currently this only applies to the default roots # fileserver_backend. #fileserver_followsymlinks: False # # Uncomment the line below if you do not want symlinks to be # treated as the files they are pointing to. By default this is set to # False. By uncommenting the line below, any detected symlink while listing # files on the Master will not be returned to the Minion. #fileserver_ignoresymlinks: True # # By default, the Salt fileserver recurses fully into all defined environments # to attempt to find files. To limit this behavior so that the fileserver only # traverses directories with SLS files and special Salt directories like _modules, # enable the option below. This might be useful for installations where a file root # has a very large number of files and performance is negatively impacted. Default # is False. #fileserver_limit_traversal: False # The hash_type is the hash to use when discovering the hash of a file on # the local fileserver. The default is md5, but sha1, sha224, sha256, sha384 # and sha512 are also supported. # # WARNING: While md5 and sha1 are also supported, do not use it due to the high chance # of possible collisions and thus security breach. # # WARNING: While md5 is also supported, do not use it due to the high chance # of possible collisions and thus security breach. # # Warning: Prior to changing this value, the minion should be stopped and all # Salt caches should be cleared. #hash_type: sha256 # The Salt pillar is searched for locally if file_client is set to local. If # this is the case, and pillar data is defined, then the pillar_roots need to # also be configured on the minion: #pillar_roots: # base: # \- /srv/pillar # Set a hard\-limit on the size of the files that can be pushed to the master. # It will be interpreted as megabytes. Default: 100 #file_recv_max_size: 100 # # ###### Security settings ##### ########################################### # Enable "open mode", this mode still maintains encryption, but turns off # authentication, this is only intended for highly secure environments or for # the situation where your keys end up in a bad state. If you run in open mode # you do so at your own risk! #open_mode: False # Enable permissive access to the salt keys. This allows you to run the # master or minion as root, but have a non\-root group be given access to # your pki_dir. To make the access explicit, root must belong to the group # you\(aqve given access to. This is potentially quite insecure. #permissive_pki_access: False # The state_verbose and state_output settings can be used to change the way # state system data is printed to the display. By default all data is printed. # The state_verbose setting can be set to True or False, when set to False # all data that has a result of True and no changes will be suppressed. #state_verbose: True # The state_output setting changes if the output is the full multi line # output for each changed state if set to \(aqfull\(aq, but if set to \(aqterse\(aq # the output will be shortened to a single line. #state_output: full # The state_output_diff setting changes whether or not the output from # successful states is returned. Useful when even the terse output of these # states is cluttering the logs. Set it to True to ignore them. #state_output_diff: False # The state_output_profile setting changes whether profile information # will be shown for each state run. #state_output_profile: True # Fingerprint of the master public key to validate the identity of your Salt master # before the initial key exchange. The master fingerprint can be found by running # "salt\-key \-f master.pub" on the Salt master. #master_finger: \(aq\(aq # Use TLS/SSL encrypted connection between master and minion. # Can be set to a dictionary containing keyword arguments corresponding to Python\(aqs # \(aqssl.wrap_socket\(aq method. # Default is None. #ssl: # keyfile: # certfile: # ssl_version: PROTOCOL_TLSv1_2 ###### Thread settings ##### ########################################### # Disable multiprocessing support, by default when a minion receives a # publication a new process is spawned and the command is executed therein. #multiprocessing: True ##### Logging settings ##### ########################################## # The location of the minion log file # The minion log 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.: # \(ga\(gafile:///dev/log\(ga\(ga), with rsyslogd(8) configured for network logging. The URI # format is: ://:/ #log_file: /var/log/salt/minion #log_file: file:///dev/log #log_file: udp://loghost:10514 # #log_file: /var/log/salt/minion #key_logfile: /var/log/salt/key # The level of messages to send to the console. # One of \(aqgarbage\(aq, \(aqtrace\(aq, \(aqdebug\(aq, info\(aq, \(aqwarning\(aq, \(aqerror\(aq, \(aqcritical\(aq. # # The following log levels are considered INSECURE and may log sensitive data: # [\(aqgarbage\(aq, \(aqtrace\(aq, \(aqdebug\(aq] # # Default: \(aqwarning\(aq #log_level: warning # The level of messages to send to the log file. # One of \(aqgarbage\(aq, \(aqtrace\(aq, \(aqdebug\(aq, info\(aq, \(aqwarning\(aq, \(aqerror\(aq, \(aqcritical\(aq. # If using \(aqlog_granular_levels\(aq this must be set to the highest desired level. # Default: \(aqwarning\(aq #log_level_logfile: # The date and time format used in log messages. Allowed date/time formatting # can be seen here: http://docs.python.org/library/time.html#time.strftime #log_datefmt: \(aq%H:%M:%S\(aq #log_datefmt_logfile: \(aq%Y\-%m\-%d %H:%M:%S\(aq # The format of the console logging messages. Allowed formatting options can # be seen here: http://docs.python.org/library/logging.html#logrecord\-attributes # # Console log colors are specified by these additional formatters: # # %(colorlevel)s # %(colorname)s # %(colorprocess)s # %(colormsg)s # # Since it is desirable to include the surrounding brackets, \(aq[\(aq and \(aq]\(aq, in # the coloring of the messages, these color formatters also include padding as # well. Color LogRecord attributes are only available for console logging. # #log_fmt_console: \(aq%(colorlevel)s %(colormsg)s\(aq #log_fmt_console: \(aq[%(levelname)\-8s] %(message)s\(aq # #log_fmt_logfile: \(aq%(asctime)s,%(msecs)03d [%(name)\-17s][%(levelname)\-8s] %(message)s\(aq # This can be used to control logging levels more specificically. This # example sets the main salt library at the \(aqwarning\(aq level, but sets # \(aqsalt.modules\(aq to log at the \(aqdebug\(aq level: # log_granular_levels: # \(aqsalt\(aq: \(aqwarning\(aq # \(aqsalt.modules\(aq: \(aqdebug\(aq # #log_granular_levels: {} # To diagnose issues with minions disconnecting or missing returns, ZeroMQ # supports the use of monitor sockets to log connection events. This # feature requires ZeroMQ 4.0 or higher. # # To enable ZeroMQ monitor sockets, set \(aqzmq_monitor\(aq to \(aqTrue\(aq and log at a # debug level or higher. # # A sample log event is as follows: # # [DEBUG ] ZeroMQ event: {\(aqendpoint\(aq: \(aqtcp://127.0.0.1:4505\(aq, \(aqevent\(aq: 512, # \(aqvalue\(aq: 27, \(aqdescription\(aq: \(aqEVENT_DISCONNECTED\(aq} # # All events logged will include the string \(aqZeroMQ event\(aq. A connection event # should be logged as the minion starts up and initially connects to the # master. If not, check for debug log level and that the necessary version of # ZeroMQ is installed. # #zmq_monitor: False ###### Module configuration ##### ########################################### # Salt allows for modules to be passed arbitrary configuration data, any data # passed here in valid yaml format will be passed on to the salt minion modules # for use. It is STRONGLY recommended that a naming convention be used in which # the module name is followed by a . and then the value. Also, all top level # data must be applied via the yaml dict construct, some examples: # # You can specify that all modules should run in test mode: #test: True # # A simple value for the test module: #test.foo: foo # # A list for the test module: #test.bar: [baz,quo] # # A dict for the test module: #test.baz: {spam: sausage, cheese: bread} # # ###### Update settings ###### ########################################### # Using the features in Esky, a salt minion can both run as a frozen app and # be updated on the fly. These options control how the update process # (saltutil.update()) behaves. # # The url for finding and downloading updates. Disabled by default. #update_url: False # # The list of services to restart after a successful update. Empty by default. #update_restart_services: [] ###### Keepalive settings ###### ############################################ # ZeroMQ now includes support for configuring SO_KEEPALIVE if supported by # the OS. If connections between the minion and the master pass through # a state tracking device such as a firewall or VPN gateway, there is # the risk that it could tear down the connection the master and minion # without informing either party that their connection has been taken away. # Enabling TCP Keepalives prevents this from happening. # Overall state of TCP Keepalives, enable (1 or True), disable (0 or False) # or leave to the OS defaults (\-1), on Linux, typically disabled. Default True, enabled. #tcp_keepalive: True # How long before the first keepalive should be sent in seconds. Default 300 # to send the first keepalive after 5 minutes, OS default (\-1) is typically 7200 seconds # on Linux see /proc/sys/net/ipv4/tcp_keepalive_time. #tcp_keepalive_idle: 300 # How many lost probes are needed to consider the connection lost. Default \-1 # to use OS defaults, typically 9 on Linux, see /proc/sys/net/ipv4/tcp_keepalive_probes. #tcp_keepalive_cnt: \-1 # How often, in seconds, to send keepalives after the first one. Default \-1 to # use OS defaults, typically 75 seconds on Linux, see # /proc/sys/net/ipv4/tcp_keepalive_intvl. #tcp_keepalive_intvl: \-1 ###### Windows Software settings ###### ############################################ # Location of the repository cache file on the master: #win_repo_cachefile: \(aqsalt://win/repo/winrepo.p\(aq ###### Returner settings ###### ############################################ # Default Minion returners. Can be a comma delimited string or a list: # #return: mysql # #return: mysql,slack,redis # #return: # \- mysql # \- hipchat # \- slack ###### Miscellaneous settings ###### ############################################ # Default match type for filtering events tags: startswith, endswith, find, regex, fnmatch #event_match_type: startswith .ft P .fi .UNINDENT .UNINDENT .SS Minion Blackout Configuration .sp New in version 2016.3.0. .sp Salt supports minion blackouts. When a minion is in blackout mode, all remote execution commands are disabled. This allows production minions to be put "on hold", eliminating the risk of an untimely configuration change. .sp Minion blackouts are configured via a special pillar key, \fBminion_blackout\fP\&. If this key is set to \fBTrue\fP, then the minion will reject all incoming commands, except for \fBsaltutil.refresh_pillar\fP\&. (The exception is important, so minions can be brought out of blackout mode) .sp Salt also supports an explicit whitelist of additional functions that will be allowed during blackout. This is configured with the special pillar key \fBminion_blackout_whitelist\fP, which is formed as a list: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C minion_blackout_whitelist: \- test.ping \- pillar.get .ft P .fi .UNINDENT .UNINDENT .SS 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. .sp These interfaces include, the \fBpeer\fP system, the \fBexternal auth\fP system and the \fBpublisher 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 publisher ACLs, and for specific minions in the case of the peer system. .SS Publisher ACL system .sp The salt publisher ACL system is a means to allow system users other than root to have access to execute select salt commands on minions from the master. .sp The publisher ACL system is configured in the master configuration file via the \fBpublisher_acl\fP configuration option. Under the \fBpublisher_acl\fP configuration option the users open to send commands are specified and then a list of regular expressions which specify the minion functions which will be made available to specified user. This configuration is much like the \fBpeer\fP configuration: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C publisher_acl: # Allow thatch to execute anything. thatch: \- .* # Allow fred to use test and pkg, but only on "web*" minions. fred: \- web*: \- test.* \- pkg.* .ft P .fi .UNINDENT .UNINDENT .sp WARNING: client_acl and client_acl_blacklist options are deprecated and will be removed in the future releases. Use publisher_acl and publisher_acl_blacklist instead. .SS Permission Issues .sp Directories required for \fBpublisher_acl\fP must be modified to be readable by the users specified: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C chmod 755 /var/cache/salt /var/cache/salt/master /var/cache/salt/master/jobs /var/run/salt /var/run/salt/master .ft P .fi .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 In addition to the changes above you will also need to modify the permissions of /var/log/salt and the existing log file to be writable by the user(s) which will be running the commands. If you do not wish to do this then you must disable logging or Salt will generate errors as it cannot write to the logs as the system users. .UNINDENT .UNINDENT .sp If you are upgrading from earlier versions of salt you must also remove any existing user keys and re\-start the Salt master: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C rm /var/cache/salt/.*key service salt\-master restart .ft P .fi .UNINDENT .UNINDENT .SS Whitelist and Blacklist .sp Salt\(aqs authentication systems can be configured by specifying what is allowed using a whitelist, or by specifying what is disallowed using a blacklist. If you specify a whitelist, only specified operations are allowed. If you specify a blacklist, all operations are allowed except those that are blacklisted. .sp See \fBpublisher_acl\fP and \fBpublisher_acl_blacklist\fP\&. .SS External Authentication System .sp Salt\(aqs External Authentication System (eAuth) allows for Salt to pass through command authorization to any external authentication system, such as PAM or LDAP. .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 eAuth using the PAM external auth system requires salt\-master to be run as root as this system needs root access to check authentication. .UNINDENT .UNINDENT .SS External Authentication System Configuration .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 access control system: .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 The above configuration allows the user \fBthatch\fP to execute functions in the test and network modules on the minions that match the web* target. User \fBsteve\fP is given unrestricted access to minion commands. .sp Salt respects the current PAM configuration in place, and uses the \(aqlogin\(aq service to authenticate. .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 The PAM module does not allow authenticating as \fBroot\fP\&. .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 state.sls and state.highstate will return "Failed to authenticate!" if the request timeout is reached. Use \-t flag to increase the timeout .UNINDENT .UNINDENT .sp To allow access to wheel modules or runner modules 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 # to allow access to all wheel modules \- \(aq@runner\(aq # to allow access to all runner modules \- \(aq@jobs\(aq # to allow access to the jobs runner and/or wheel module .ft P .fi .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 The runner/wheel markup is different, since there are no minions to scope the acl to. .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 Globs will not match wheel or runners! They must be explicitly allowed with @wheel or @runner. .UNINDENT .UNINDENT .sp \fBWARNING:\fP .INDENT 0.0 .INDENT 3.5 All users that have external authentication privileges are allowed to run \fBsaltutil.findjob\fP\&. Be aware that this could inadvertently expose some data such as minion IDs. .UNINDENT .UNINDENT .SS Matching syntax .sp The structure of the \fBexternal_auth\fP dictionary can take the following shapes. Function matches are regular expressions; minion matches are compound targets. .sp By user: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C external_auth: : : \- .ft P .fi .UNINDENT .UNINDENT .sp By user, by minion: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C external_auth: : : : \- .ft P .fi .UNINDENT .UNINDENT .SS Groups .sp To apply permissions to a group of users in an external authentication system, append a \fB%\fP to the ID: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C external_auth: pam: admins%: \- \(aq*\(aq: \- \(aqpkg.*\(aq .ft P .fi .UNINDENT .UNINDENT .SS Limiting by function arguments .sp Positional arguments or keyword arguments to functions can also be whitelisted. .sp New in version 2016.3.0. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C external_auth: pam: my_user: \- \(aq*\(aq: \- \(aqmy_mod.*\(aq: args: \- \(aqa.*\(aq \- \(aqb.*\(aq kwargs: \(aqkwa\(aq: \(aqkwa.*\(aq \(aqkwb\(aq: \(aqkwb\(aq .ft P .fi .UNINDENT .UNINDENT .sp The rules: .INDENT 0.0 .IP 1. 3 The arguments values are matched as regexp. .IP 2. 3 If arguments restrictions are specified the only matched are allowed. .IP 3. 3 If an argument isn\(aqt specified any value is allowed. .IP 4. 3 To skip an arg use "everything" regexp \fB\&.*\fP\&. I.e. if \fBarg0\fP and \fBarg2\fP should be limited but \fBarg1\fP and other arguments could have any value use: .INDENT 3.0 .INDENT 3.5 .sp .nf .ft C args: \- \(aqvalue0\(aq \- \(aq.*\(aq \- \(aqvalue2\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS Usage .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 \fB\-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 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 an expiration of 12 hours (by default). This token is stored in a file named \fBsalt_token\fP in the active user\(aqs home directory. .sp Once the token is created, it is sent with all subsequent communications. User authentication does not need to be entered again until the token expires. .sp Token expiration time can be set in the Salt master config file. .SS LDAP and Active Directory .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 LDAP usage requires that you have installed python\-ldap. .UNINDENT .UNINDENT .sp Salt supports both user and group authentication for LDAP (and Active Directory accessed via its LDAP interface) .SS OpenLDAP and similar systems .sp LDAP configuration happens in the Salt master configuration file. .sp Server configuration values and their defaults: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C # Server to auth against auth.ldap.server: localhost # Port to connect via auth.ldap.port: 389 # Use TLS when connecting auth.ldap.tls: False # LDAP scope level, almost always 2 auth.ldap.scope: 2 # Server specified in URI format auth.ldap.uri: \(aq\(aq # Overrides .ldap.server, .ldap.port, .ldap.tls above # Verify server\(aqs TLS certificate auth.ldap.no_verify: False # Bind to LDAP anonymously to determine group membership # Active Directory does not allow anonymous binds without special configuration auth.ldap.anonymous: False # FOR TESTING ONLY, this is a VERY insecure setting. # If this is True, the LDAP bind password will be ignored and # access will be determined by group membership alone with # the group memberships being retrieved via anonymous bind auth.ldap.auth_by_group_membership_only: False # Require authenticating user to be part of this Organizational Unit # This can be blank if your LDAP schema does not use this kind of OU auth.ldap.groupou: \(aqGroups\(aq # Object Class for groups. An LDAP search will be done to find all groups of this # class to which the authenticating user belongs. auth.ldap.groupclass: \(aqposixGroup\(aq # Unique ID attribute name for the user auth.ldap.accountattributename: \(aqmemberUid\(aq # These are only for Active Directory auth.ldap.activedirectory: False auth.ldap.persontype: \(aqperson\(aq auth.ldap.minion_stripdomains: [] .ft P .fi .UNINDENT .UNINDENT .sp There are two phases to LDAP authentication. First, Salt authenticates to search for a users\(aq Distinguished Name and group membership. The user it authenticates as in this phase is often a special LDAP system user with read\-only access to the LDAP directory. After Salt searches the directory to determine the actual user\(aqs DN and groups, it re\-authenticates as the user running the Salt commands. .sp If you are already aware of the structure of your DNs and permissions in your LDAP store are set such that users can look up their own group memberships, then the first and second users can be the same. To tell Salt this is the case, omit the \fBauth.ldap.bindpw\fP parameter. You can template the \fBbinddn\fP like this: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C auth.ldap.basedn: dc=saltstack,dc=com auth.ldap.binddn: uid={{ username }},cn=users,cn=accounts,dc=saltstack,dc=com .ft P .fi .UNINDENT .UNINDENT .sp Salt will use the password entered on the salt command line in place of the bindpw. .sp To use two separate users, specify the LDAP lookup user in the binddn directive, and include a bindpw like so .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C auth.ldap.binddn: uid=ldaplookup,cn=sysaccounts,cn=etc,dc=saltstack,dc=com auth.ldap.bindpw: mypassword .ft P .fi .UNINDENT .UNINDENT .sp As mentioned before, Salt uses a filter to find the DN associated with a user. Salt substitutes the \fB{{ username }}\fP value for the username when querying LDAP .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C auth.ldap.filter: uid={{ username }} .ft P .fi .UNINDENT .UNINDENT .sp For OpenLDAP, to determine group membership, one can specify an OU that contains group data. This is prepended to the basedn to create a search path. Then the results are filtered against \fBauth.ldap.groupclass\fP, default \fBposixGroup\fP, and the account\(aqs \(aqname\(aq attribute, \fBmemberUid\fP by default. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C auth.ldap.groupou: Groups .ft P .fi .UNINDENT .UNINDENT .sp When using the \fIldap(\(aqDC=domain,DC=com\(aq)\fP eauth operator, sometimes the records returned from LDAP or Active Directory have fully\-qualified domain names attached, while minion IDs instead are simple hostnames. The parameter below allows the administrator to strip off a certain set of domain names so the hostnames looked up in the directory service can match the minion IDs. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C auth.ldap.minion_stripdomains: [\(aq.external.bigcorp.com\(aq, \(aq.internal.bigcorp.com\(aq] .ft P .fi .UNINDENT .UNINDENT .SS Active Directory .sp Active Directory handles group membership differently, and does not utilize the \fBgroupou\fP configuration variable. AD needs the following options in the master config: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C auth.ldap.activedirectory: True auth.ldap.filter: sAMAccountName={{username}} auth.ldap.accountattributename: sAMAccountName auth.ldap.groupclass: group auth.ldap.persontype: person .ft P .fi .UNINDENT .UNINDENT .sp To determine group membership in AD, the username and password that is entered when LDAP is requested as the eAuth mechanism on the command line is used to bind to AD\(aqs LDAP interface. If this fails, then it doesn\(aqt matter what groups the user belongs to, he or she is denied access. Next, the \fBdistinguishedName\fP of the user is looked up with the following LDAP search: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C (&(={{username}}) (objectClass=) ) .ft P .fi .UNINDENT .UNINDENT .sp This should return a distinguishedName that we can use to filter for group membership. Then the following LDAP query is executed: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C (&(member=) (objectClass=) ) .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C external_auth: ldap: test_ldap_user: \- \(aq*\(aq: \- test.ping .ft P .fi .UNINDENT .UNINDENT .sp To configure a LDAP group, append a \fB%\fP to the ID: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C external_auth: ldap: test_ldap_group%: \- \(aq*\(aq: \- test.echo .ft P .fi .UNINDENT .UNINDENT .sp In addition, if there are a set of computers in the directory service that should be part of the eAuth definition, they can be specified like this: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C external_auth: ldap: test_ldap_group%: \- ldap(\(aqDC=corp,DC=example,DC=com\(aq): \- test.echo .ft P .fi .UNINDENT .UNINDENT .sp The string inside \fIldap()\fP above is any valid LDAP/AD tree limiter. \fIOU=\fP in particular is permitted as long as it would return a list of computer objects. .SS Peer Communication .sp Salt 0.9.0 introduced the capability for Salt minions to publish commands. The intent of this feature is not for Salt minions to act as independent brokers one with another, but to allow Salt minions to pass commands to each other. .sp In Salt 0.10.0 the ability to execute runners from the master was added. This allows for the master to return collective data from runners back to the minions via the peer interface. .sp The peer interface is configured through two options in the master configuration file. For minions to send commands from the master the \fBpeer\fP configuration is used. To allow for minions to execute runners from the master the \fBpeer_run\fP configuration is used. .sp Since this presents a viable security risk by allowing minions access to the master publisher the capability is turned off by default. The minions can be allowed access to the master publisher on a per minion basis based on regular expressions. Minions with specific ids can be allowed access to certain Salt modules and functions. .SS Peer Configuration .sp The configuration is done under the \fBpeer\fP setting in the Salt master configuration file, here are a number of configuration possibilities. .sp The simplest approach is to enable all communication for all minions, this is only recommended for very secure environments. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C peer: .*: \- .* .ft P .fi .UNINDENT .UNINDENT .sp This configuration will allow minions with IDs ending in example.com access to the test, ps, and pkg module functions. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C peer: .*example.com: \- test.* \- ps.* \- pkg.* .ft P .fi .UNINDENT .UNINDENT .sp The configuration logic is simple, a regular expression is passed for matching minion ids, and then a list of expressions matching minion functions is associated with the named minion. For instance, this configuration will also allow minions ending with foo.org access to the publisher. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C peer: .*example.com: \- test.* \- ps.* \- pkg.* .*foo.org: \- test.* \- ps.* \- pkg.* .ft P .fi .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 Functions are matched using regular expressions. .UNINDENT .UNINDENT .SS Peer Runner Communication .sp Configuration to allow minions to execute runners from the master is done via the \fBpeer_run\fP option on the master. The \fBpeer_run\fP configuration follows the same logic as the \fBpeer\fP option. The only difference is that access is granted to runner modules. .sp To open up access to all minions to all runners: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C peer_run: .*: \- .* .ft P .fi .UNINDENT .UNINDENT .sp This configuration will allow minions with IDs ending in example.com access to the manage and jobs runner functions. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C peer_run: .*example.com: \- manage.* \- jobs.* .ft P .fi .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 Functions are matched using regular expressions. .UNINDENT .UNINDENT .SS Using Peer Communication .sp The publish module was created to manage peer communication. The publish module comes with a number of functions to execute peer communication in different ways. Currently there are three functions in the publish module. These examples will show how to test the peer system via the salt\-call command. .sp To execute test.ping on all minions: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C # salt\-call publish.publish \e* test.ping .ft P .fi .UNINDENT .UNINDENT .sp To execute the manage.up runner: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C # salt\-call publish.runner manage.up .ft P .fi .UNINDENT .UNINDENT .sp To match minions using other matchers, use \fBexpr_form\fP: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C # salt\-call publish.publish \(aqwebserv* and not G@os:Ubuntu\(aq test.ping expr_form=\(aqcompound\(aq .ft P .fi .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 The expr_form argument will be renamed to \fBtgt_type\fP in the Nitrogen release of Salt. .UNINDENT .UNINDENT .SS When to Use Each Authentication System .sp \fBpublisher_acl\fP is useful for allowing local system users to run Salt commands without giving them root access. If you can log into the Salt master directly, then \fBpublisher_acl\fP allows you to use Salt without root privileges. If the local system is configured to authenticate against a remote system, like LDAP or Active Directory, then \fBpublisher_acl\fP will interact with the remote system transparently. .sp \fBexternal_auth\fP is useful for \fBsalt\-api\fP or for making your own scripts that use Salt\(aqs Python API. It can be used at the CLI (with the \fB\-a\fP flag) but it is more cumbersome as there are more steps involved. The only time it is useful at the CLI is when the local system is \fInot\fP configured to authenticate against an external service \fIbut\fP you still want Salt to authenticate against an external service. .SS Examples .sp The access controls are manifested using matchers in these configurations: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C publisher_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 (all matchers are supported except the compound one). .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. .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 Functions are matched using regular expressions. .UNINDENT .UNINDENT .SS 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. .SS The Minion proc System .sp Salt Minions maintain a \fIproc\fP directory in the Salt \fBcachedir\fP\&. 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 \fB/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 it 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. \fBlist_jobs\fP 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 .SS Scheduling Jobs .sp Salt\(aqs 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 can be enabled by multiple methods: .INDENT 0.0 .IP \(bu 2 \fBschedule\fP option in either the master or minion config files. These require the master or minion application to be restarted in order for the schedule to be implemented. .IP \(bu 2 Minion pillar data. Schedule is implemented by refreshing the minion\(aqs pillar data, for example by using \fBsaltutil.refresh_pillar\fP\&. .IP \(bu 2 The \fBschedule state\fP or \fBschedule module\fP .UNINDENT .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 A scheduled run has no output on the minion unless the config is set to info level or higher. Refer to \fBminion\-logging\-settings\fP\&. .sp States are executed on the minion, as all states are. You can pass positional arguments and provide a YAML dict of named arguments. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C schedule: job1: function: state.sls seconds: 3600 args: \- httpd kwargs: test: True .ft P .fi .UNINDENT .UNINDENT .sp This will schedule the command: \fBstate.sls httpd test=True\fP every 3600 seconds (every hour). .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C schedule: job1: function: state.sls seconds: 3600 args: \- httpd kwargs: test: True splay: 15 .ft P .fi .UNINDENT .UNINDENT .sp This will schedule the command: \fBstate.sls httpd test=True\fP every 3600 seconds (every hour) splaying the time between 0 and 15 seconds. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C schedule: job1: function: state.sls seconds: 3600 args: \- httpd kwargs: test: True splay: start: 10 end: 15 .ft P .fi .UNINDENT .UNINDENT .sp This will schedule the command: \fBstate.sls httpd test=True\fP every 3600 seconds (every hour) splaying the time between 10 and 15 seconds. .SS Schedule by Date and Time .sp New in version 2014.7.0. .sp Frequency of jobs can also be specified using date strings supported by the Python \fBdateutil\fP library. This requires the Python \fBdateutil\fP library to be installed. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C schedule: job1: function: state.sls args: \- httpd kwargs: test: True when: 5:00pm .ft P .fi .UNINDENT .UNINDENT .sp This will schedule the command: \fBstate.sls httpd test=True\fP at 5:00 PM minion localtime. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C schedule: job1: function: state.sls args: \- httpd kwargs: test: True when: \- Monday 5:00pm \- Tuesday 3:00pm \- Wednesday 5:00pm \- Thursday 3:00pm \- Friday 5:00pm .ft P .fi .UNINDENT .UNINDENT .sp This will schedule the command: \fBstate.sls httpd test=True\fP at 5:00 PM on Monday, Wednesday and Friday, and 3:00 PM on Tuesday and Thursday. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C schedule: job1: function: state.sls seconds: 3600 args: \- httpd kwargs: test: True range: start: 8:00am end: 5:00pm .ft P .fi .UNINDENT .UNINDENT .sp This will schedule the command: \fBstate.sls httpd test=True\fP every 3600 seconds (every hour) between the hours of 8:00 AM and 5:00 PM. The range parameter must be a dictionary with the date strings using the \fBdateutil\fP format. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C schedule: job1: function: state.sls seconds: 3600 args: \- httpd kwargs: test: True range: invert: True start: 8:00am end: 5:00pm .ft P .fi .UNINDENT .UNINDENT .sp Using the invert option for range, this will schedule the command \fBstate.sls httpd test=True\fP every 3600 seconds (every hour) until the current time is between the hours of 8:00 AM and 5:00 PM. The range parameter must be a dictionary with the date strings using the \fBdateutil\fP format. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C schedule: job1: function: pkg.install kwargs: pkgs: [{\(aqbar\(aq: \(aq>1.2.3\(aq}] refresh: true once: \(aq2016\-01\-07T14:30:00\(aq .ft P .fi .UNINDENT .UNINDENT .sp This will schedule the function \fBpkg.install\fP to be executed once at the specified time. The schedule entry \fBjob1\fP will not be removed after the job completes, therefore use \fBschedule.delete\fP to manually remove it afterwards. .sp The default date format is ISO 8601 but can be overridden by also specifying the \fBonce_fmt\fP option, like this: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C schedule: job1: function: test.ping once: 2015\-04\-22T20:21:00 once_fmt: \(aq%Y\-%m\-%dT%H:%M:%S\(aq .ft P .fi .UNINDENT .UNINDENT .SS Maximum Parallel Jobs Running .sp New in version 2014.7.0. .sp The scheduler also supports ensuring 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 pile up in case of infrastructure outage. .sp The default for \fBmaxrunning\fP is 1. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C schedule: long_running_job: function: big_file_transfer jid_include: True maxrunning: 1 .ft P .fi .UNINDENT .UNINDENT .SS Cron\-like Schedule .sp New in version 2014.7.0. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C schedule: job1: function: state.sls cron: \(aq*/15 * * * *\(aq args: \- httpd kwargs: test: True .ft P .fi .UNINDENT .UNINDENT .sp The scheduler also supports scheduling jobs using a cron like format. This requires the Python \fBcroniter\fP library. .SS Job Data Return .sp New in version 2015.5.0. .sp By default, data about jobs runs from the Salt scheduler is returned to the master. Setting the \fBreturn_job\fP parameter to False will prevent the data from being sent back to the Salt master. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C schedule: job1: function: scheduled_job_function return_job: False .ft P .fi .UNINDENT .UNINDENT .SS Job Metadata .sp New in version 2015.5.0. .sp It can be useful to include specific data to differentiate a job from other jobs. Using the metadata parameter special values can be associated with a scheduled job. These values are not used in the execution of the job, but can be used to search for specific jobs later if combined with the \fBreturn_job\fP parameter. The metadata parameter must be specified as a dictionary, othewise it will be ignored. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C schedule: job1: function: scheduled_job_function metadata: foo: bar .ft P .fi .UNINDENT .UNINDENT .SS Run on Start .sp New in version 2015.5.0. .sp By default, any job scheduled based on the startup time of the minion will run the scheduled job when the minion starts up. Sometimes this is not the desired situation. Using the \fBrun_on_start\fP parameter set to \fBFalse\fP will cause the scheduler to skip this first run and wait until the next scheduled run: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C schedule: job1: function: state.sls seconds: 3600 run_on_start: False args: \- httpd kwargs: test: True .ft P .fi .UNINDENT .UNINDENT .SS Until and After .sp New in version 2015.8.0. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C schedule: job1: function: state.sls seconds: 15 until: \(aq12/31/2015 11:59pm\(aq args: \- httpd kwargs: test: True .ft P .fi .UNINDENT .UNINDENT .sp Using the until argument, the Salt scheduler allows you to specify an end time for a scheduled job. If this argument is specified, jobs will not run once the specified time has passed. Time should be specified in a format supported by the \fBdateutil\fP library. This requires the Python \fBdateutil\fP library to be installed. .sp New in version 2015.8.0. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C schedule: job1: function: state.sls seconds: 15 after: \(aq12/31/2015 11:59pm\(aq args: \- httpd kwargs: test: True .ft P .fi .UNINDENT .UNINDENT .sp Using the after argument, the Salt scheduler allows you to specify an start time for a scheduled job. If this argument is specified, jobs will not run until the specified time has passed. Time should be specified in a format supported by the \fBdateutil\fP library. This requires the Python \fBdateutil\fP library to be installed. .SS Scheduling 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: /bin/sh .ft P .fi .UNINDENT .UNINDENT .SS Scheduling 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 Scheduling 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: run_my_orch: function: state.orchestrate hours: 6 splay: 600 args: \- orchestration.my_orch .ft P .fi .UNINDENT .UNINDENT .sp The above configuration is analogous to running \fBsalt\-run state.orch orchestration.my_orch\fP every 6 hours. .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. .SS Managing the Job Cache .sp The Salt Master maintains a job cache of all job executions which can be queried via the jobs runner. This job cache is called the Default Job Cache. .SS Default Job Cache .sp A number of options are available when configuring the job cache. The default caching system uses local storage on the Salt Master and can be found in the job cache directory (on Linux systems this is typically \fB/var/cache/salt/master/jobs\fP). The default caching system is suitable for most deployments as it does not typically require any further configuration or management. .sp The default job cache is a temporary cache and jobs will be stored for 24 hours. If the default cache needs to store jobs for a different period the time can be easily adjusted by changing the \fIkeep_jobs\fP parameter in the Salt Master configuration file. The value passed in is measured via hours: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C keep_jobs: 24 .ft P .fi .UNINDENT .UNINDENT .SS Reducing the Size of the Default Job Cache .sp The Default Job Cache can sometimes be a burden on larger deployments (over 5000 minions). Disabling the job cache will make previously executed jobs unavailable to the jobs system and is not generally recommended. Normally it is wise to make sure the master has access to a faster IO system or a tmpfs is mounted to the jobs dir. .sp However, you can disable the \fBjob_cache\fP by setting it to \fBFalse\fP in the Salt Master configuration file. Setting this value to \fBFalse\fP means that the Salt Master will no longer cache minion returns, but a JID directory and \fBjid\fP file for each job will still be created. This JID directory is necessary for checking for and preventing JID collisions. .sp The default location for the job cache is in the \fB/var/cache/salt/master/jobs/\fP directory. .sp Setting the \fBjob_cache\(ga\fP to \fBFalse\fP in addition to setting the \fBkeep_jobs\fP option to a smaller value, such as \fB1\fP, in the Salt Master configuration file will reduce the size of the Default Job Cache, and thus the burden on the Salt Master. .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 Changing the \fBkeep_jobs\fP option sets the number of hours to keep old job information and defaults to \fB24\fP hours. Do not set this value to \fB0\fP when trying to make the cache cleaner run more frequently, as this means the cache cleaner will never run. .UNINDENT .UNINDENT .SS Additional Job Cache Options .sp Many deployments may wish to use an external database to maintain a long term register of executed jobs. Salt comes with two main mechanisms to do this, the master job cache and the external job cache. .sp See Storing Job Results in an External System\&. .SS Storing Job Results in an External System .sp After a job executes, job results are returned to the Salt Master by each Salt Minion. These results are stored in the Default Job Cache\&. .sp In addition to the Default Job Cache, Salt provides two additional mechanisms to send job results to other systems (databases, local syslog, and others): .INDENT 0.0 .IP \(bu 2 External Job Cache .IP \(bu 2 Master Job Cache .UNINDENT .sp The major difference between these two mechanism is from where results are returned (from the Salt Master or Salt Minion). .SS External Job Cache \- Minion\-Side Returner .sp When an External Job Cache is configured, data is returned to the Default Job Cache on the Salt Master like usual, and then results are also sent to an External Job Cache using a Salt returner module running on the Salt Minion. [image] .INDENT 0.0 .IP \(bu 2 Advantages: Data is stored without placing additional load on the Salt Master. .IP \(bu 2 Disadvantages: Each Salt Minion connects to the external job cache, which can result in a large number of connections. Also requires additional configuration to get returner module settings on all Salt Minions. .UNINDENT .SS Master Job Cache \- Master\-Side Returner .sp New in version 2014.7.0. .sp Instead of configuring an External Job Cache on each Salt Minion, you can configure the Master Job Cache to send job results from the Salt Master instead. In this configuration, Salt Minions send data to the Default Job Cache as usual, and then the Salt Master sends the data to the external system using a Salt returner module running on the Salt Master. [image] .INDENT 0.0 .IP \(bu 2 Advantages: A single connection is required to the external system. This is preferred for databases and similar systems. .IP \(bu 2 Disadvantages: Places additional load on your Salt Master. .UNINDENT .SS Configure an External or Master Job Cache .SS Step 1: Understand Salt Returners .sp Before you configure a job cache, it is essential to understand Salt returner modules ("returners"). Returners are pluggable Salt Modules that take the data returned by jobs, and then perform any necessary steps to send the data to an external system. For example, a returner might establish a connection, authenticate, and then format and transfer data. .sp The Salt Returner system provides the core functionality used by the External and Master Job Cache systems, and the same returners are used by both systems. .sp Salt currently provides many different returners that let you connect to a wide variety of systems. A complete list is available at all Salt returners\&. Each returner is configured differently, so make sure you read and follow the instructions linked from that page. .sp For example, the MySQL returner requires: .INDENT 0.0 .IP \(bu 2 A database created using provided schema (structure is available at \fBMySQL returner\fP) .IP \(bu 2 A user created with with privileges to the database .IP \(bu 2 Optional SSL configuration .UNINDENT .sp A simpler returner, such as Slack or HipChat, requires: .INDENT 0.0 .IP \(bu 2 An API key/version .IP \(bu 2 The target channel/room .IP \(bu 2 The username that should be used to send the message .UNINDENT .SS Step 2: Configure the Returner .sp After you understand the configuration and have the external system ready, add the returner configuration settings to the Salt Minion configuration file for the External Job Cache, or to the Salt Master configuration file for the Master Job Cache. .sp For example, MySQL requires: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C mysql.host: \(aqsalt\(aq mysql.user: \(aqsalt\(aq mysql.pass: \(aqsalt\(aq mysql.db: \(aqsalt\(aq mysql.port: 3306 .ft P .fi .UNINDENT .UNINDENT .sp Slack requires: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C slack.channel: \(aqchannel\(aq slack.api_key: \(aqkey\(aq slack.from_name: \(aqname\(aq .ft P .fi .UNINDENT .UNINDENT .sp After you have configured the returner and added settings to the configuration file, you can enable the External or Master Job Cache. .SS Step 3: Enable the External or Master Job Cache .sp Configuration is a single line that specifies an already\-configured returner to use to send all job data to an external system. .SS External Job Cache .sp To enable a returner as the External Job Cache (Minion\-side), add the following line to the Salt Master configuration file: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C ext_job_cache: .ft P .fi .UNINDENT .UNINDENT .sp For example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C ext_job_cache: mysql .ft P .fi .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 When configuring an External Job Cache (Minion\-side), the returner settings are added to the Minion configuration file, but the External Job Cache setting is configured in the Master configuration file. .UNINDENT .UNINDENT .SS Master Job Cache .sp To enable a returner as a Master Job Cache (Master\-side), add the following line to the Salt Master configuration file: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C master_job_cache: .ft P .fi .UNINDENT .UNINDENT .sp For example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C master_job_cache: mysql .ft P .fi .UNINDENT .UNINDENT .sp Verify that the returner configuration settings are in the Master configuration file, and be sure to restart the salt\-master service after you make configuration changes. (\fBservice salt\-master restart\fP). .SS 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 logging development document, if all you\(aqre after is salt\(aqs logging configurations, please continue reading. .SS Log Levels .sp The log levels are ordered numerically such that setting the log level to a specific level will record all log statements at that level and higher. For example, setting \fBlog_level: error\fP will log statements at \fBerror\fP, \fBcritical\fP, and \fBquiet\fP levels, although nothing \fIshould\fP be logged at \fBquiet\fP level. .sp Most of the logging levels are defined by default in Python\(aqs logging library and can be found in the official \fI\%Python documentation\fP\&. Salt uses some more levels in addition to the standard levels. All levels available in salt are shown in the table below. .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 Python dependencies used by salt may define and use additional logging levels. For example, the Python 2 version of the \fBmultiprocessing\fP standard Python library \fI\%uses the levels\fP \fBsubwarning\fP, 25 and \fBsubdebug\fP, 5. .UNINDENT .UNINDENT .TS center; |l|l|l|. _ T{ Level T} T{ Numeric value T} T{ Description T} _ T{ quiet T} T{ 1000 T} T{ Nothing should be logged at this level T} _ T{ critical T} T{ 50 T} T{ Critical errors T} _ T{ error T} T{ 40 T} T{ Errors T} _ T{ warning T} T{ 30 T} T{ Warnings T} _ T{ info T} T{ 20 T} T{ Normal log information T} _ T{ profile T} T{ 15 T} T{ Profiling information on salt performance T} _ T{ debug T} T{ 10 T} T{ Information useful for debugging both salt implementations and salt code T} _ T{ trace T} T{ 5 T} T{ More detailed code debugging information T} _ T{ garbage T} T{ 1 T} T{ Even more debugging information T} _ T{ all T} T{ 0 T} T{ Everything T} _ .TE .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\&. Where \fBlog\-facility\fP is the symbolic name of a syslog facility as defined in the SysLogHandler documentation . It defaults to \fBLOG_USER\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: file:///dev/log/LOG_DAEMON .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, \fBprofile\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 .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 Add \fBlog_level: quiet\fP in salt configuration file to completely disable logging. In case of running salt in command line use \fB\-\-log\-level=quiet\fP instead. .UNINDENT .UNINDENT .SS \fBlog_level_logfile\fP .sp Default: \fBinfo\fP .sp The level of messages to send to the log file. One of \fBall\fP, \fBgarbage\fP, \fBtrace\fP, \fBdebug\fP, \fBprofile\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. All standard python logging \fI\%LogRecord attributes\fP can be used. Salt also provides these custom LogRecord attributes to colorize console log output: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C \(aq%(colorlevel)s\(aq # log level name colorized by level \(aq%(colorname)s\(aq # colorized module name \(aq%(colorprocess)s\(aq # colorized process number \(aq%(colormsg)s\(aq # log message colorized by level .ft P .fi .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 The \fB%(colorlevel)s\fP, \fB%(colorname)s\fP, and \fB%(colorprocess)\fP LogRecord attributes also include padding and enclosing brackets, \fB[\fP and \fB]\fP to match the default values of their collateral non\-colorized LogRecord attributes. .UNINDENT .UNINDENT .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)03d [%(name)\-17s][%(levelname)\-8s] %(message)s\fP .sp The format of the log file logging messages. All standard python logging \fI\%LogRecord attributes\fP can be used. Salt also provides these custom LogRecord attributes that include padding and enclosing brackets \fB[\fP and \fB]\fP: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C \(aq%(bracketlevel)s\(aq # equivalent to [%(levelname)\-8s] \(aq%(bracketname)s\(aq # equivalent to [%(name)\-17s] \(aq%(bracketprocess)s\(aq # equivalent to [%(process)5s] .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C log_fmt_logfile: \(aq%(asctime)s,%(msecs)03d [%(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 external logging handlers document. .SS Salt File Server .sp Salt comes with a simple file server suitable for distributing files to the Salt minions. The file server is a stateless ZeroMQ server that is built into the Salt master. .sp The main intent of the Salt file server is to present files for use in the Salt state system. With this said, the Salt file server can be used for any general file transfer from the master to the minions. .SS File Server Backends .sp In Salt 0.12.0, the modular fileserver was introduced. This feature added the ability for the Salt Master to integrate different file server backends. File server backends allow the Salt file server to act as a transparent bridge to external resources. A good example of this is the \fBgit\fP backend, which allows Salt to serve files sourced from one or more git repositories, but there are several others as well. Click here for a full list of Salt\(aqs fileserver backends. .SS Enabling a Fileserver Backend .sp Fileserver backends can be enabled with the \fBfileserver_backend\fP option. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C fileserver_backend: \- git .ft P .fi .UNINDENT .UNINDENT .sp See the documentation for each backend to find the correct value to add to \fBfileserver_backend\fP in order to enable them. .SS Using Multiple Backends .sp If \fBfileserver_backend\fP is not defined in the Master config file, Salt will use the \fBroots\fP backend, but the \fBfileserver_backend\fP option supports multiple backends. When more than one backend is in use, the files from the enabled backends are merged into a single virtual filesystem. When a file is requested, the backends will be searched in order for that file, and the first backend to match will be the one which returns the file. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C fileserver_backend: \- roots \- git .ft P .fi .UNINDENT .UNINDENT .sp With this configuration, the environments and files defined in the \fBfile_roots\fP parameter will be searched first, and if the file is not found then the git repositories defined in \fBgitfs_remotes\fP will be searched. .SS Defining Environments .sp Just as the order of the values in \fBfileserver_backend\fP matters, so too does the order in which different sources are defined within a fileserver environment. For example, given the below \fBfile_roots\fP configuration, if both \fB/srv/salt/dev/foo.txt\fP and \fB/srv/salt/prod/foo.txt\fP exist on the Master, then \fBsalt://foo.txt\fP would point to \fB/srv/salt/dev/foo.txt\fP in the \fBdev\fP environment, but it would point to \fB/srv/salt/prod/foo.txt\fP in the \fBbase\fP environment. .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 Similarly, when using the \fBgit\fP backend, if both repositories defined below have a \fBhotfix23\fP branch/tag, and both of them also contain the file \fBbar.txt\fP in the root of the repository at that branch/tag, then \fBsalt://bar.txt\fP in the \fBhotfix23\fP environment would be served from the \fBfirst\fP repository. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C gitfs_remotes: \- https://mydomain.tld/repos/first.git \- https://mydomain.tld/repos/second.git .ft P .fi .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 Environments map differently based on the fileserver backend. For instance, the mappings are explicitly defined in \fBroots\fP backend, while in the VCS backends (\fBgit\fP, \fBhg\fP, \fBsvn\fP) the environments are created from branches/tags/bookmarks/etc. For the \fBminion\fP backend, the files are all in a single environment, which is specified by the \fBminionfs_env\fP option. .sp See the documentation for each backend for a more detailed explanation of how environments are mapped. .UNINDENT .UNINDENT .SS Dynamic Module Distribution .sp New in version 0.9.5. .sp Custom Salt execution, state, and other modules can be distributed to Salt minions using the Salt file server. .sp Under the root of any environment defined via the \fBfile_roots\fP option on the master server directories corresponding to the type of module can be used. .sp The directories are prepended with an underscore: .INDENT 0.0 .IP \(bu 2 \fB_beacons\fP .IP \(bu 2 \fB_engines\fP .IP \(bu 2 \fB_grains\fP .IP \(bu 2 \fB_modules\fP .IP \(bu 2 \fB_output\fP .IP \(bu 2 \fB_proxy\fP .IP \(bu 2 \fB_renderers\fP .IP \(bu 2 \fB_returners\fP .IP \(bu 2 \fB_states\fP .IP \(bu 2 \fB_utils\fP .UNINDENT .sp The contents of these directories need to be synced over to the minions after Python modules have been created in them. There are a number of ways to sync the modules. .SS Sync Via States .sp The minion configuration contains an option \fBautoload_dynamic_modules\fP which defaults to \fBTrue\fP\&. This option makes the state system refresh all dynamic modules when states are run. To disable this behavior set \fBautoload_dynamic_modules\fP to \fBFalse\fP in the minion config. .sp When dynamic modules are autoloaded via states, modules only pertinent to the environments matched in the master\(aqs top file are downloaded. .sp This is important to remember, because modules can be manually loaded from any specific environment that environment specific modules will be loaded when a state run is executed. .SS Sync Via the saltutil Module .sp The saltutil module has a number of functions that can be used to sync all or specific dynamic modules. The saltutil module function \fBsaltutil.sync_all\fP will sync all module types over to a minion. For more information see: \fBsalt.modules.saltutil\fP .SS Requesting Files from Specific Environments .sp The Salt fileserver supports multiple environments, allowing for SLS files and other files to be isolated for better organization. .sp For the default backend (called \fBroots\fP), environments are defined using the \fBroots\fP option. Other backends (such as \fBgitfs\fP) define environments in their own ways. For a list of available fileserver backends, see here\&. .SS Querystring Syntax .sp Any \fBsalt://\fP file URL can specify its fileserver environment using a querystring syntax, like so: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt://path/to/file?saltenv=foo .ft P .fi .UNINDENT .UNINDENT .sp In Reactor configurations, this method must be used to pull files from an environment other than \fBbase\fP\&. .SS In States .sp Minions can be instructed which environment to use both globally, and for a single state, and multiple methods for each are available: .SS Globally .sp A minion can be pinned to an environment using the \fBenvironment\fP option in the minion config file. .sp Additionally, the environment can be set for a single call to the following functions: .INDENT 0.0 .IP \(bu 2 \fBstate.apply\fP .IP \(bu 2 \fBstate.highstate\fP .IP \(bu 2 \fBstate.sls\fP .IP \(bu 2 \fBstate.top\fP .UNINDENT .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 When the \fBsaltenv\fP parameter is used to trigger a highstate using either \fBstate.apply\fP or \fBstate.highstate\fP, only states from that environment will be applied. .UNINDENT .UNINDENT .SS On a Per\-State Basis .sp Within an individual state, there are two ways of specifying the environment. The first is to add a \fBsaltenv\fP argument to the state. This example will pull the file from the \fBconfig\fP environment: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C /etc/foo/bar.conf: file.managed: \- source: salt://foo/bar.conf \- user: foo \- mode: 600 \- saltenv: config .ft P .fi .UNINDENT .UNINDENT .sp Another way of doing the same thing is to use the \fI\%querystring syntax\fP described above: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C /etc/foo/bar.conf: file.managed: \- source: salt://foo/bar.conf?saltenv=config \- user: foo \- mode: 600 .ft P .fi .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 Specifying the environment using either of the above methods is only necessary in cases where a state from one environment needs to access files from another environment. If the SLS file containing this state was in the \fBconfig\fP environment, then it would look in that environment by default. .UNINDENT .UNINDENT .SS File Server Configuration .sp The Salt file server is a high performance file server written in ZeroMQ. It manages large files quickly and with little overhead, and has been optimized to handle small files in an extremely efficient manner. .sp The Salt file server is an environment aware file server. This means that files can be allocated within many root directories and accessed by specifying both the file path and the environment to search. The individual environments can span across multiple directory roots to create overlays and to allow for files to be organized in many flexible ways. .SS Environments .sp The Salt file server defaults to the mandatory \fBbase\fP environment. This environment \fBMUST\fP be defined and is used to download files when no environment is specified. .sp Environments allow for files and sls data to be logically separated, but environments are not isolated from each other. This allows for logical isolation of environments by the engineer using Salt, but also allows for information to be used in multiple environments. .SS Directory Overlay .sp The \fBenvironment\fP setting is a list of directories to publish files from. These directories are searched in order to find the specified file and the first file found is returned. .sp This means that directory data is prioritized based on the order in which they are listed. In the case of this \fBfile_roots\fP configuration: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C file_roots: base: \- /srv/salt/base \- /srv/salt/failover .ft P .fi .UNINDENT .UNINDENT .sp If a file\(aqs URI is \fBsalt://httpd/httpd.conf\fP, it will first search for the file at \fB/srv/salt/base/httpd/httpd.conf\fP\&. If the file is found there it will be returned. If the file is not found there, then \fB/srv/salt/failover/httpd/httpd.conf\fP will be used for the source. .sp This allows for directories to be overlaid and prioritized based on the order they are defined in the configuration. .sp It is also possible to have \fBfile_roots\fP which supports multiple environments: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C file_roots: base: \- /srv/salt/base dev: \- /srv/salt/dev \- /srv/salt/base prod: \- /srv/salt/prod \- /srv/salt/base .ft P .fi .UNINDENT .UNINDENT .sp This example ensures that each environment will check the associated environment directory for files first. If a file is not found in the appropriate directory, the system will default to using the base directory. .SS Local File Server .sp New in version 0.9.8. .sp The file server can be rerouted to run from the minion. This is primarily to enable running Salt states without a Salt master. To use the local file server interface, copy the file server data to the minion and set the file_roots option on the minion to point to the directories copied from the master. Once the minion \fBfile_roots\fP option has been set, change the \fBfile_client\fP option to local to make sure that the local file server interface is used. .SS The cp Module .sp The cp module is the home of minion side file server operations. The cp module is used by the Salt state system, salt\-cp, and can be used to distribute files presented by the Salt file server. .SS Escaping Special Characters .sp The \fBsalt://\fP url format can potentially contain a query string, for example \fBsalt://dir/file.txt?saltenv=base\fP\&. You can prevent the fileclient/fileserver from interpreting \fB?\fP as the initial token of a query string by referencing the file with \fBsalt://|\fP rather than \fBsalt://\fP\&. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C /etc/marathon/conf/?checkpoint: file.managed: \- source: salt://|hw/config/?checkpoint \- makedirs: True .ft P .fi .UNINDENT .UNINDENT .SS Environments .sp Since the file server is made to work with the Salt state system, it supports environments. The environments are defined in the master config file and when referencing an environment the file specified will be based on the root directory of the environment. .SS get_file .sp The cp.get_file function can be used on the minion to download a file from the master, the syntax looks like this: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C # salt \(aq*\(aq cp.get_file salt://vimrc /etc/vimrc .ft P .fi .UNINDENT .UNINDENT .sp This will instruct all Salt minions to download the vimrc file and copy it to /etc/vimrc .sp Template rendering can be enabled on both the source and destination file names like so: .INDENT 0.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 To use compression, use the \fBgzip\fP named argument. Valid values are integers from 1 to 9, where 1 is the lightest compression and 9 the heaviest. In other words, 1 uses the least CPU on the master (and minion), while 9 uses the most. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C # salt \(aq*\(aq cp.get_file salt://vimrc /etc/vimrc gzip=5 .ft P .fi .UNINDENT .UNINDENT .sp Finally, note that by default cp.get_file does \fInot\fP create new destination directories if they do not exist. To change this, use the \fBmakedirs\fP argument: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C # salt \(aq*\(aq cp.get_file salt://vimrc /etc/vim/vimrc makedirs=True .ft P .fi .UNINDENT .UNINDENT .sp In this example, /etc/vim/ would be created if it didn\(aqt already exist. .SS get_dir .sp The cp.get_dir function can be used on the minion to download an entire directory from the master. The syntax is very similar to get_file: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C # salt \(aq*\(aq cp.get_dir salt://etc/apache2 /etc .ft P .fi .UNINDENT .UNINDENT .sp cp.get_dir supports template rendering and gzip compression arguments just like get_file: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C # salt \(aq*\(aq cp.get_dir salt://etc/{{pillar.webserver}} /etc gzip=5 template=jinja .ft P .fi .UNINDENT .UNINDENT .SS File Server Client Instance .sp A client instance is available which allows for modules and applications to be written which make use of the Salt file server. .sp The file server uses the same authentication and encryption used by the rest of the Salt system for network communication. .SS fileclient Module .sp The \fBsalt/fileclient.py\fP module is used to set up the communication from the minion to the master. When creating a client instance using the fileclient module, the minion configuration needs to be passed in. When using the fileclient module from within a minion module the built in \fB__opts__\fP data can be passed: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C import salt.minion import salt.fileclient def get_file(path, dest, saltenv=\(aqbase\(aq): \(aq\(aq\(aq Used to get a single file from the Salt master CLI Example: salt \(aq*\(aq cp.get_file salt://vimrc /etc/vimrc \(aq\(aq\(aq # Get the fileclient object client = salt.fileclient.get_file_client(__opts__) # Call get_file return client.get_file(path, dest, False, saltenv) .ft P .fi .UNINDENT .UNINDENT .sp Creating a fileclient instance outside of a minion module where the \fB__opts__\fP data is not available, it needs to be generated: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C import salt.fileclient import salt.config def get_file(path, dest, saltenv=\(aqbase\(aq): \(aq\(aq\(aq Used to get a single file from the Salt master \(aq\(aq\(aq # Get the configuration data opts = salt.config.minion_config(\(aq/etc/salt/minion\(aq) # Get the fileclient object client = salt.fileclient.get_file_client(opts) # Call get_file return client.get_file(path, dest, False, saltenv) .ft P .fi .UNINDENT .UNINDENT .SS Git Fileserver Backend Walkthrough .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 This walkthrough assumes basic knowledge of Salt. To get up to speed, check out the Salt Walkthrough\&. .UNINDENT .UNINDENT .sp The gitfs backend allows Salt to serve files from git repositories. It can be enabled by adding \fBgit\fP to the \fBfileserver_backend\fP list, and configuring one or more repositories in \fBgitfs_remotes\fP\&. .sp Branches and tags become Salt fileserver environments. .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 Branching and tagging can result in a lot of potentially\-conflicting top files, for this reason it may be useful to set \fBtop_file_merging_strategy\fP to \fBsame\fP in the minions\(aq config files if the top files are being managed in a GitFS repo. .UNINDENT .UNINDENT .SS Installing Dependencies .sp Beginning with version 2014.7.0, both \fI\%pygit2\fP and \fI\%Dulwich\fP are supported as alternatives to \fI\%GitPython\fP\&. The desired provider can be configured using the \fBgitfs_provider\fP parameter in the master config file. .sp If \fBgitfs_provider\fP is not configured, then Salt will prefer \fI\%pygit2\fP if a suitable version is available, followed by \fI\%GitPython\fP and \fI\%Dulwich\fP\&. .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 It is recommended to always run the most recent version of any the below dependencies. Certain features of gitfs may not be available without the most recent version of the chosen library. .UNINDENT .UNINDENT .SS pygit2 .sp The minimum supported version of \fI\%pygit2\fP is 0.20.3. Availability for this version of \fI\%pygit2\fP is still limited, though the SaltStack team is working to get compatible versions available for as many platforms as possible. .sp For the Fedora/EPEL versions which have a new enough version packaged, the following command would be used to install \fI\%pygit2\fP: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C # yum install python\-pygit2 .ft P .fi .UNINDENT .UNINDENT .sp Provided a valid version is packaged for Debian/Ubuntu (which is not currently the case), the package name would be the same, and the following command would be used to install it: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C # apt\-get install python\-pygit2 .ft P .fi .UNINDENT .UNINDENT .sp If \fI\%pygit2\fP is not packaged for the platform on which the Master is running, the \fI\%pygit2\fP website has installation instructions \fI\%here\fP\&. Keep in mind however that following these instructions will install \fI\%libgit2\fP and \fI\%pygit2\fP without system packages. Additionally, keep in mind that \fI\%SSH authentication in pygit2\fP requires \fI\%libssh2\fP (\fInot\fP libssh) development libraries to be present before \fI\%libgit2\fP is built. On some Debian\-based distros \fBpkg\-config\fP is also required to link \fI\%libgit2\fP with libssh2. .sp Additionally, version 0.21.0 of pygit2 introduced a dependency on \fI\%python\-cffi\fP, which in turn depends on newer releases of \fI\%libffi\fP\&. Upgrading \fI\%libffi\fP is not advisable as several other applications depend on it, so on older LTS linux releases \fI\%pygit2\fP 0.20.3 and \fI\%libgit2\fP 0.20.0 is the recommended combination. While these are not packaged in the official repositories for Debian and Ubuntu, SaltStack is actively working on adding packages for these to our \fI\%repositories\fP\&. The progress of this effort can be tracked \fI\%here\fP\&. .sp \fBWARNING:\fP .INDENT 0.0 .INDENT 3.5 \fI\%pygit2\fP is actively developed and frequently makes non\-backwards\-compatible API changes, even in minor releases. It is not uncommon for \fI\%pygit2\fP upgrades to result in errors in Salt. Please take care when upgrading \fI\%pygit2\fP, and pay close attention to the \fI\%changelog\fP, keeping an eye out for API changes. Errors can be reported on the SaltStack issue tracker\&. .UNINDENT .UNINDENT .SS GitPython .sp \fI\%GitPython\fP 0.3.0 or newer is required to use GitPython for gitfs. For RHEL\-based Linux distros, a compatible version is available in EPEL, and can be easily installed on the master using yum: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C # yum install GitPython .ft P .fi .UNINDENT .UNINDENT .sp Ubuntu 14.04 LTS and Debian Wheezy (7.x) also have a compatible version packaged: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C # apt\-get install python\-git .ft P .fi .UNINDENT .UNINDENT .sp If your master is running an older version (such as Ubuntu 12.04 LTS or Debian Squeeze), then you will need to install GitPython using either \fI\%pip\fP or easy_install (it is recommended to use pip). Version 0.3.2.RC1 is now marked as the stable release in PyPI, so it should be a simple matter of running \fBpip install GitPython\fP (or \fBeasy_install GitPython\fP) as root. .sp \fBWARNING:\fP .INDENT 0.0 .INDENT 3.5 Keep in mind that if GitPython has been previously installed on the master using pip (even if it was subsequently uninstalled), then it may still exist in the build cache (typically \fB/tmp/pip\-build\-root/GitPython\fP) if the cache is not cleared after installation. The package in the build cache will override any requirement specifiers, so if you try upgrading to version 0.3.2.RC1 by running \fBpip install \(aqGitPython==0.3.2.RC1\(aq\fP then it will ignore this and simply install the version from the cache directory. Therefore, it may be necessary to delete the GitPython directory from the build cache in order to ensure that the specified version is installed. .UNINDENT .UNINDENT .sp \fBWARNING:\fP .INDENT 0.0 .INDENT 3.5 \fI\%GitPython\fP 2.0.9 and newer is not compatible with Python 2.6. If installing \fI\%GitPython\fP using pip on a machine running Python 2.6, make sure that a version earlier than 2.0.9 is installed. This can be done on the CLI by running \fBpip install \(aqGitPython<2.0.9\(aq\fP, or in a \fBpip.installed\fP state using the following SLS: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C GitPython: pip.installed: \- name: \(aqGitPython < 2.0.9\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .UNINDENT .SS Dulwich .sp Dulwich 0.9.4 or newer is required to use Dulwich as backend for gitfs. .sp Dulwich is available in EPEL, and can be easily installed on the master using yum: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C # yum install python\-dulwich .ft P .fi .UNINDENT .UNINDENT .sp For APT\-based distros such as Ubuntu and Debian: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C # apt\-get install python\-dulwich .ft P .fi .UNINDENT .UNINDENT .sp \fBIMPORTANT:\fP .INDENT 0.0 .INDENT 3.5 If switching to Dulwich from GitPython/pygit2, or switching from GitPython/pygit2 to Dulwich, it is necessary to clear the gitfs cache to avoid unpredictable behavior. This is probably a good idea whenever switching to a new \fBgitfs_provider\fP, but it is less important when switching between GitPython and pygit2. .sp Beginning in version 2015.5.0, the gitfs cache can be easily cleared using the \fBfileserver.clear_cache\fP runner. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt\-run fileserver.clear_cache backend=git .ft P .fi .UNINDENT .UNINDENT .sp If the Master is running an earlier version, then the cache can be cleared by removing the \fBgitfs\fP and \fBfile_lists/gitfs\fP directories (both paths relative to the master cache directory, usually \fB/var/cache/salt/master\fP). .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C rm \-rf /var/cache/salt/master{,/file_lists}/gitfs .ft P .fi .UNINDENT .UNINDENT .UNINDENT .UNINDENT .SS Simple Configuration .sp To use the gitfs backend, only two configuration changes are required on the master: .INDENT 0.0 .IP 1. 3 Include \fBgit\fP in the \fBfileserver_backend\fP list in the master config file: .INDENT 3.0 .INDENT 3.5 .sp .nf .ft C fileserver_backend: \- git .ft P .fi .UNINDENT .UNINDENT .IP 2. 3 Specify one or more \fBgit://\fP, \fBhttps://\fP, \fBfile://\fP, or \fBssh://\fP URLs in \fBgitfs_remotes\fP to configure which repositories to cache and search for requested files: .INDENT 3.0 .INDENT 3.5 .sp .nf .ft C gitfs_remotes: \- https://github.com/saltstack\-formulas/salt\-formula.git .ft P .fi .UNINDENT .UNINDENT .sp SSH remotes can also be configured using scp\-like syntax: .INDENT 3.0 .INDENT 3.5 .sp .nf .ft C gitfs_remotes: \- git@github.com:user/repo.git \- ssh://user@domain.tld/path/to/repo.git .ft P .fi .UNINDENT .UNINDENT .sp Information on how to authenticate to SSH remotes can be found \fI\%here\fP\&. .sp \fBNOTE:\fP .INDENT 3.0 .INDENT 3.5 Dulwich does not recognize \fBssh://\fP URLs, \fBgit+ssh://\fP must be used instead. Salt version 2015.5.0 and later will automatically add the \fBgit+\fP to the beginning of these URLs before fetching, but earlier Salt versions will fail to fetch unless the URL is specified using \fBgit+ssh://\fP\&. .UNINDENT .UNINDENT .IP 3. 3 Restart the master to load the new configuration. .UNINDENT .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 In a master/minion setup, files from a gitfs remote are cached once by the master, so minions do not need direct access to the git repository. .UNINDENT .UNINDENT .SS Multiple Remotes .sp The \fBgitfs_remotes\fP option accepts an ordered list of git remotes to cache and search, in listed order, for requested files. .sp A simple scenario illustrates this cascading lookup behavior: .sp If 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 \- https://github.com/example/second.git \- file:///root/third .ft P .fi .UNINDENT .UNINDENT .sp And 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 Salt will attempt to lookup the requested file from each gitfs remote repository in the order in which they are defined in the configuration. The \fBgit://github.com/example/first.git\fP remote will be searched first. If the requested file is found, then it is served and no further searching is executed. For example: .INDENT 0.0 .IP \(bu 2 A request for the file \fBsalt://haproxy/init.sls\fP will be served from the \fBhttps://github.com/example/second.git\fP git repo. .IP \(bu 2 A request for the file \fBsalt://haproxy/haproxy.conf\fP will be served from the \fBfile:///root/third\fP repo. .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. .sp 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 \fBWARNING:\fP .INDENT 0.0 .INDENT 3.5 Salt versions prior to 2014.1.0 are not tolerant of changing the order of remotes or modifying the URI of existing remotes. In those versions, when modifying remotes it is a good idea to remove the gitfs cache directory (\fB/var/cache/salt/master/gitfs\fP) before restarting the salt\-master service. .UNINDENT .UNINDENT .SS Per\-remote Configuration Parameters .sp New in version 2014.7.0. .sp The following master config parameters are global (that is, they apply to all configured gitfs remotes): .INDENT 0.0 .IP \(bu 2 \fBgitfs_base\fP .IP \(bu 2 \fBgitfs_root\fP .IP \(bu 2 \fBgitfs_mountpoint\fP (new in 2014.7.0) .IP \(bu 2 \fBgitfs_user\fP (\fBpygit2 only\fP, new in 2014.7.0) .IP \(bu 2 \fBgitfs_password\fP (\fBpygit2 only\fP, new in 2014.7.0) .IP \(bu 2 \fBgitfs_insecure_auth\fP (\fBpygit2 only\fP, new in 2014.7.0) .IP \(bu 2 \fBgitfs_pubkey\fP (\fBpygit2 only\fP, new in 2014.7.0) .IP \(bu 2 \fBgitfs_privkey\fP (\fBpygit2 only\fP, new in 2014.7.0) .IP \(bu 2 \fBgitfs_passphrase\fP (\fBpygit2 only\fP, new in 2014.7.0) .UNINDENT .sp These parameters can now be overridden on a per\-remote basis. This allows for a tremendous amount of customization. Here\(aqs some example usage: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C gitfs_provider: pygit2 gitfs_base: develop gitfs_remotes: \- https://foo.com/foo.git \- https://foo.com/bar.git: \- root: salt \- mountpoint: salt://bar \- base: salt\-base \- https://foo.com/bar.git: \- name: second_bar_repo \- root: other/salt \- mountpoint: salt://other/bar \- base: salt\-base \- http://foo.com/baz.git: \- root: salt/states \- user: joe \- password: mysupersecretpassword \- insecure_auth: True .ft P .fi .UNINDENT .UNINDENT .sp \fBIMPORTANT:\fP .INDENT 0.0 .INDENT 3.5 There are two important distinctions which should be noted for per\-remote configuration: .INDENT 0.0 .IP 1. 3 The URL of a remote which has per\-remote configuration must be suffixed with a colon. .IP 2. 3 Per\-remote configuration parameters are named like the global versions, with the \fBgitfs_\fP removed from the beginning. The exception being the \fBname\fP parameter which is only available to per\-remote configurations. .UNINDENT .UNINDENT .UNINDENT .sp In the example configuration above, the following is true: .INDENT 0.0 .IP 1. 3 The first and fourth gitfs remotes will use the \fBdevelop\fP branch/tag as the \fBbase\fP environment, while the second and third will use the \fBsalt\-base\fP branch/tag as the \fBbase\fP environment. .IP 2. 3 The first remote will serve all files in the repository. The second remote will only serve files from the \fBsalt\fP directory (and its subdirectories). The third remote will only server files from the \fBother/salt\fP directory (and its subdirectories), while the fourth remote will only serve files from the \fBsalt/states\fP directory (and its subdirectories). .IP 3. 3 The first and fourth remotes will have files located under the root of the Salt fileserver namespace (\fBsalt://\fP). The files from the second remote will be located under \fBsalt://bar\fP, while the files from the third remote will be located under \fBsalt://other/bar\fP\&. .IP 4. 3 The second and third remotes reference the same repository and unique names need to be declared for duplicate gitfs remotes. .IP 5. 3 The fourth remote overrides the default behavior of \fI\%not authenticating to insecure (non\-HTTPS) remotes\fP\&. .UNINDENT .SS Per\-Saltenv Configuration Parameters .sp New in version 2016.11.0. .sp For more granular control, Salt allows the following three things to be overridden for individual saltenvs within a given repo: .INDENT 0.0 .IP \(bu 2 The \fI\%mountpoint\fP .IP \(bu 2 The \fI\%root\fP .IP \(bu 2 The branch/tag to be used for a given saltenv .UNINDENT .sp Here is an example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C gitfs_root: salt gitfs_saltenv: \- dev: \- mountpoint: salt://gitfs\-dev \- ref: develop gitfs_remotes: \- https://foo.com/bar.git: \- saltenv: \- staging: \- ref: qa \- mountpoint: salt://bar\-staging \- dev: \- ref: development \- https://foo.com/baz.git: \- saltenv: \- staging: \- mountpoint: salt://baz\-staging .ft P .fi .UNINDENT .UNINDENT .sp Given the above configuration, the following is true: .INDENT 0.0 .IP 1. 3 For all gitfs remotes, files for the \fBdev\fP saltenv will be located under \fBsalt://gitfs\-dev\fP\&. .IP 2. 3 For the \fBdev\fP saltenv, files from the first remote will be sourced from the \fBdevelopment\fP branch, while files from the second remote will be sourced from the \fBdevelop\fP branch. .IP 3. 3 For the \fBstaging\fP saltenv, files from the first remote will be located under \fBsalt://bar\-staging\fP, while files from the second remote will be located under \fBsalt://baz\-staging\fP\&. .IP 4. 3 For all gitfs remotes, and in all saltenvs, files will be served from the \fBsalt\fP directory (and its subdirectories). .UNINDENT .SS Configuration Order of Precedence .sp The order of precedence for gitfs configuration is as follows (each level overrides all levels below it): .INDENT 0.0 .IP 1. 3 Per\-saltenv configuration (defined under a per\-remote \fBsaltenv\fP param) .INDENT 3.0 .INDENT 3.5 .sp .nf .ft C gitfs_remotes: \- https://foo.com/bar.git: \- saltenv: \- dev: \- mountpoint: salt://bar .ft P .fi .UNINDENT .UNINDENT .IP 2. 3 Global per\-saltenv configuration (defined in \fBgitfs_saltenv\fP) .INDENT 3.0 .INDENT 3.5 .sp .nf .ft C gitfs_saltenv: \- saltenv: \- dev: \- mountpoint: salt://bar .ft P .fi .UNINDENT .UNINDENT .IP 3. 3 Per\-remote configuration parameter .INDENT 3.0 .INDENT 3.5 .sp .nf .ft C gitfs_remotes: \- https://foo.com/bar.git: \- mountpoint: salt://bar .ft P .fi .UNINDENT .UNINDENT .IP 4. 3 Global configuration parameter .INDENT 3.0 .INDENT 3.5 .sp .nf .ft C gitfs_mountpoint: salt://bar .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS Serving from a Subdirectory .sp The \fBgitfs_root\fP parameter allows files to be served from a subdirectory within the repository. This allows for only part of a repository to be exposed to the Salt fileserver. .sp Assume the below layout: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C \&.gitignore README.txt foo/ foo/bar/ foo/bar/one.txt foo/bar/two.txt foo/bar/three.txt foo/baz/ foo/baz/top.sls foo/baz/edit/vim.sls foo/baz/edit/vimrc foo/baz/nginx/init.sls .ft P .fi .UNINDENT .UNINDENT .sp The below configuration would serve only the files under \fBfoo/baz\fP, ignoring the other files in the repository: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C gitfs_remotes: \- git://mydomain.com/stuff.git gitfs_root: foo/baz .ft P .fi .UNINDENT .UNINDENT .sp The root can also be configured on a \fI\%per\-remote basis\fP\&. .SS Mountpoints .sp New in version 2014.7.0. .sp The \fBgitfs_mountpoint\fP parameter will prepend the specified path to the files served from gitfs. This allows an existing repository to be used, rather than needing to reorganize a repository or design it around the layout of the Salt fileserver. .sp Before the addition of this feature, if a file being served up via gitfs was deeply nested within the root directory (for example, \fBsalt://webapps/foo/files/foo.conf\fP, it would be necessary to ensure that the file was properly located in the remote repository, and that all of the the parent directories were present (for example, the directories \fBwebapps/foo/files/\fP would need to exist at the root of the repository). .sp The below example would allow for a file \fBfoo.conf\fP at the root of the repository to be served up from the Salt fileserver path \fBsalt://webapps/foo/files/foo.conf\fP\&. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C gitfs_remotes: \- https://mydomain.com/stuff.git gitfs_mountpoint: salt://webapps/foo/files .ft P .fi .UNINDENT .UNINDENT .sp Mountpoints can also be configured on a \fI\%per\-remote basis\fP\&. .SS Using gitfs Alongside Other Backends .sp Sometimes it may make sense to use multiple backends; for instance, if \fBsls\fP files are stored in git but larger files are stored directly on the master. .sp The cascading lookup logic used for multiple remotes is also used with 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, each configured git remote will be searched. .SS Branches, Environments, and Top Files .sp When using the gitfs backend, branches, and tags will be mapped to environments using the branch/tag name as an identifier. .sp There is one exception to this rule: the \fBmaster\fP branch is implicitly mapped to the \fBbase\fP environment. .sp So, for a typical \fBbase\fP, \fBqa\fP, \fBdev\fP setup, the following branches could be used: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C master qa dev .ft P .fi .UNINDENT .UNINDENT .sp \fBtop.sls\fP files from different branches will be merged into one at runtime. Since this can lead to overly complex configurations, the recommended setup is to have a separate repository, containing only the \fBtop.sls\fP file with just one single \fBmaster\fP branch. .sp To map a branch other than \fBmaster\fP as the \fBbase\fP environment, use the \fBgitfs_base\fP parameter. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C gitfs_base: salt\-base .ft P .fi .UNINDENT .UNINDENT .sp The base can also be configured on a \fI\%per\-remote basis\fP\&. .SS Environment Whitelist/Blacklist .sp New in version 2014.7.0. .sp The \fBgitfs_env_whitelist\fP and \fBgitfs_env_blacklist\fP parameters allow for greater control over which branches/tags are exposed as fileserver environments. Exact matches, globs, and regular expressions are supported, and are evaluated in that order. If using a regular expression, \fB^\fP and \fB$\fP must be omitted, and the expression must match the entire branch/tag. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C gitfs_env_whitelist: \- base \- v1.* \- \(aqmybranch\ed+\(aq .ft P .fi .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 \fBv1.*\fP, in this example, will match as both a glob and a regular expression (though it will have been matched as a glob, since globs are evaluated before regular expressions). .UNINDENT .UNINDENT .sp The behavior of the blacklist/whitelist will differ depending on which combination of the two options is used: .INDENT 0.0 .IP \(bu 2 If only \fBgitfs_env_whitelist\fP is used, then \fBonly\fP branches/tags which match the whitelist will be available as environments .IP \(bu 2 If only \fBgitfs_env_blacklist\fP is used, then the branches/tags which match the blacklist will \fBnot\fP be available as environments .IP \(bu 2 If both are used, then the branches/tags which match the whitelist, but do \fBnot\fP match the blacklist, will be available as environments. .UNINDENT .SS Authentication .SS pygit2 .sp New in version 2014.7.0. .sp Both HTTPS and SSH authentication are supported as of version 0.20.3, which is the earliest version of \fI\%pygit2\fP supported by Salt for gitfs. .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 The examples below make use of per\-remote configuration parameters, a feature new to Salt 2014.7.0. More information on these can be found \fI\%here\fP\&. .UNINDENT .UNINDENT .SS HTTPS .sp For HTTPS repositories which require authentication, the username and password can be provided like so: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C gitfs_remotes: \- https://domain.tld/myrepo.git: \- user: git \- password: mypassword .ft P .fi .UNINDENT .UNINDENT .sp If the repository is served over HTTP instead of HTTPS, then Salt will by default refuse to authenticate to it. This behavior can be overridden by adding an \fBinsecure_auth\fP parameter: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C gitfs_remotes: \- http://domain.tld/insecure_repo.git: \- user: git \- password: mypassword \- insecure_auth: True .ft P .fi .UNINDENT .UNINDENT .SS SSH .sp SSH repositories can be configured using the \fBssh://\fP protocol designation, or using scp\-like syntax. So, the following two configurations are equivalent: .INDENT 0.0 .IP \(bu 2 \fBssh://git@github.com/user/repo.git\fP .IP \(bu 2 \fBgit@github.com:user/repo.git\fP .UNINDENT .sp Both \fBgitfs_pubkey\fP and \fBgitfs_privkey\fP (or their \fI\%per\-remote counterparts\fP) must be configured in order to authenticate to SSH\-based repos. If the private key is protected with a passphrase, it can be configured using \fBgitfs_passphrase\fP (or simply \fBpassphrase\fP if being configured \fI\%per\-remote\fP). For example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C gitfs_remotes: \- git@github.com:user/repo.git: \- pubkey: /root/.ssh/id_rsa.pub \- privkey: /root/.ssh/id_rsa \- passphrase: myawesomepassphrase .ft P .fi .UNINDENT .UNINDENT .sp Finally, the SSH host key must be \fI\%added to the known_hosts file\fP\&. .SS GitPython .sp With \fI\%GitPython\fP, only passphrase\-less SSH public key authentication is supported. \fBThe auth parameters (pubkey, privkey, etc.) shown in the pygit2 authentication examples above do not work with GitPython.\fP .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C gitfs_remotes: \- ssh://git@github.com/example/salt\-states.git .ft P .fi .UNINDENT .UNINDENT .sp Since \fI\%GitPython\fP wraps the git CLI, the private key must be located in \fB~/.ssh/id_rsa\fP for the user under which the Master is running, and should have permissions of \fB0600\fP\&. Also, in the absence of a user in the repo URL, \fI\%GitPython\fP will (just as SSH does) attempt to login as the current user (in other words, the user under which the Master is running, usually \fBroot\fP). .sp If a key needs to be used, then \fB~/.ssh/config\fP can be configured to use the desired key. Information on how to do this can be found by viewing the manpage for \fBssh_config\fP\&. Here\(aqs an example entry which can be added to the \fB~/.ssh/config\fP to use an alternate key for gitfs: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C Host github.com IdentityFile /root/.ssh/id_rsa_gitfs .ft P .fi .UNINDENT .UNINDENT .sp The \fBHost\fP parameter should be a hostname (or hostname glob) that matches the domain name of the git repository. .sp It is also necessary to \fI\%add the SSH host key to the known_hosts file\fP\&. The exception to this would be if strict host key checking is disabled, which can be done by adding \fBStrictHostKeyChecking no\fP to the entry in \fB~/.ssh/config\fP .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C Host github.com IdentityFile /root/.ssh/id_rsa_gitfs StrictHostKeyChecking no .ft P .fi .UNINDENT .UNINDENT .sp However, this is generally regarded as insecure, and is not recommended. .SS Adding the SSH Host Key to the known_hosts File .sp To use SSH authentication, it is necessary to have the remote repository\(aqs SSH host key in the \fB~/.ssh/known_hosts\fP file. If the master is also a minion, this can be done using the \fBssh.set_known_host\fP function: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C # salt mymaster ssh.set_known_host user=root hostname=github.com mymaster: \-\-\-\-\-\-\-\-\-\- new: \-\-\-\-\-\-\-\-\-\- enc: ssh\-rsa fingerprint: 16:27:ac:a5:76:28:2d:36:63:1b:56:4d:eb:df:a6:48 hostname: |1|OiefWWqOD4kwO3BhoIGa0loR5AA=|BIXVtmcTbPER+68HvXmceodDcfI= key: AAAAB3NzaC1yc2EAAAABIwAAAQEAq2A7hRGmdnm9tUDbO9IDSwBK6TbQa+PXYPCPy6rbTrTtw7PHkccKrpp0yVhp5HdEIcKr6pLlVDBfOLX9QUsyCOV0wzfjIJNlGEYsdlLJizHhbn2mUjvSAHQqZETYP81eFzLQNnPHt4EVVUh7VfDESU84KezmD5QlWpXLmvU31/yMf+Se8xhHTvKSCZIFImWwoG6mbUoWf9nzpIoaSjB+weqqUUmpaaasXVal72J+UX2B+2RPW3RcT0eOzQgqlJL3RKrTJvdsjE3JEAvGq3lGHSZXy28G3skua2SmVi/w4yCE6gbODqnTWlg7+wC604ydGXA8VJiS5ap43JXiUFFAaQ== old: None status: updated .ft P .fi .UNINDENT .UNINDENT .sp If not, then the easiest way to add the key is to su to the user (usually \fBroot\fP) under which the salt\-master runs and attempt to login to the server via SSH: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C $ su \- Password: # ssh github.com The authenticity of host \(aqgithub.com (192.30.252.128)\(aq can\(aqt be established. RSA key fingerprint is 16:27:ac:a5:76:28:2d:36:63:1b:56:4d:eb:df:a6:48. Are you sure you want to continue connecting (yes/no)? yes Warning: Permanently added \(aqgithub.com,192.30.252.128\(aq (RSA) to the list of known hosts. Permission denied (publickey). .ft P .fi .UNINDENT .UNINDENT .sp It doesn\(aqt matter if the login was successful, as answering \fByes\fP will write the fingerprint to the known_hosts file. .SS Verifying the Fingerprint .sp To verify that the correct fingerprint was added, it is a good idea to look it up. One way to do this is to use \fBnmap\fP: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C $ nmap \-p 22 github.com \-\-script ssh\-hostkey Starting Nmap 5.51 ( http://nmap.org ) at 2014\-08\-18 17:47 CDT Nmap scan report for github.com (192.30.252.129) Host is up (0.17s latency). Not shown: 996 filtered ports PORT STATE SERVICE 22/tcp open ssh | ssh\-hostkey: 1024 ad:1c:08:a4:40:e3:6f:9c:f5:66:26:5d:4b:33:5d:8c (DSA) |_2048 16:27:ac:a5:76:28:2d:36:63:1b:56:4d:eb:df:a6:48 (RSA) 80/tcp open http 443/tcp open https 9418/tcp open git Nmap done: 1 IP address (1 host up) scanned in 28.78 seconds .ft P .fi .UNINDENT .UNINDENT .sp Another way is to check one\(aqs own \fBknown_hosts\fP file, using this one\-liner: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C $ ssh\-keygen \-l \-f /dev/stdin <<<\(gassh\-keyscan github.com 2>/dev/null\(ga | awk \(aq{print $2}\(aq 16:27:ac:a5:76:28:2d:36:63:1b:56:4d:eb:df:a6:48 .ft P .fi .UNINDENT .UNINDENT .sp \fBWARNING:\fP .INDENT 0.0 .INDENT 3.5 AWS tracks usage of nmap and may flag it as abuse. On AWS hosts, the \fBssh\-keygen\fP method is recommended for host key verification. .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 As of \fI\%OpenSSH 6.8\fP the SSH fingerprint is now shown as a base64\-encoded SHA256 checksum of the host key. So, instead of the fingerprint looking like \fB16:27:ac:a5:76:28:2d:36:63:1b:56:4d:eb:df:a6:48\fP, it would look like \fBSHA256:nThbg6kXUpJWGl7E1IGOCspRomTxdCARLviKw6E5SY8\fP\&. .UNINDENT .UNINDENT .SS Refreshing gitfs Upon Push .sp By default, Salt updates the remote fileserver backends every 60 seconds. However, if it is desirable to refresh quicker than that, the Reactor System can be used to signal the master to update the fileserver on each push, provided that the git server is also a Salt minion. There are three steps to this process: .INDENT 0.0 .IP 1. 3 On the master, create a file \fB/srv/reactor/update_fileserver.sls\fP, with the following contents: .INDENT 3.0 .INDENT 3.5 .sp .nf .ft C update_fileserver: runner.fileserver.update .ft P .fi .UNINDENT .UNINDENT .IP 2. 3 Add the following reactor configuration to the master config file: .INDENT 3.0 .INDENT 3.5 .sp .nf .ft C reactor: \- \(aqsalt/fileserver/gitfs/update\(aq: \- /srv/reactor/update_fileserver.sls .ft P .fi .UNINDENT .UNINDENT .IP 3. 3 On the git server, add a \fI\%post\-receive hook\fP .INDENT 3.0 .IP a. 3 If the user executing \fIgit push\fP is the same as the minion user, use the following hook: .UNINDENT .INDENT 3.0 .INDENT 3.5 .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C #!/usr/bin/env sh salt\-call event.fire_master update salt/fileserver/gitfs/update .ft P .fi .UNINDENT .UNINDENT .UNINDENT .UNINDENT .INDENT 3.0 .IP b. 3 To enable other git users to run the hook after a \fIpush\fP, use sudo in the hook script: .UNINDENT .INDENT 3.0 .INDENT 3.5 .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C #!/usr/bin/env sh sudo \-u root salt\-call event.fire_master update salt/fileserver/gitfs/update .ft P .fi .UNINDENT .UNINDENT .UNINDENT .UNINDENT .IP 4. 3 If using sudo in the git hook (above), the policy must be changed to permit all users to fire the event. Add the following policy to the sudoers file on the git server. .INDENT 3.0 .INDENT 3.5 .sp .nf .ft C Cmnd_Alias SALT_GIT_HOOK = /bin/salt\-call event.fire_master update salt/fileserver/gitfs/update Defaults!SALT_GIT_HOOK !requiretty ALL ALL=(root) NOPASSWD: SALT_GIT_HOOK .ft P .fi .UNINDENT .UNINDENT .UNINDENT .sp The \fBupdate\fP argument right after \fBevent.fire_master\fP in this example can really be anything, as it represents the data being passed in the event, and the passed data is ignored by this reactor. .sp Similarly, the tag name \fBsalt/fileserver/gitfs/update\fP can be replaced by anything, so long as the usage is consistent. .sp The \fBroot\fP user name in the hook script and sudo policy should be changed to match the user under which the minion is running. .SS Using Git as an External Pillar Source .sp The git external pillar (a.k.a. git_pillar) has been rewritten for the 2015.8.0 release. This rewrite brings with it \fI\%pygit2\fP support (allowing for access to authenticated repositories), as well as more granular support for per\-remote configuration. .sp To make use of the new features, changes to the git ext_pillar configuration must be made. The new configuration schema is detailed here\&. .sp For Salt releases before 2015.8.0, click here for documentation. .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 MinionFS Backend Walkthrough .sp New in version 2014.1.0. .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 Salt Walkthrough\&. .UNINDENT .UNINDENT .sp Sometimes it is desirable to deploy a file located on one minion to one or more other minions. This is supported in Salt, and can be accomplished in two parts: .INDENT 0.0 .IP 1. 3 Minion support for pushing files to the master (using \fBcp.push\fP) .IP 2. 3 The \fBminionfs\fP fileserver backend .UNINDENT .sp This walkthrough will show how to use both of these features. .SS Enabling File Push .sp To set the master to accept files pushed from minions, the \fBfile_recv\fP option in the master config file must be set to \fBTrue\fP (the default is \fBFalse\fP). .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C file_recv: True .ft P .fi .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 This change requires a restart of the salt\-master service. .UNINDENT .UNINDENT .SS Pushing Files .sp Once this has been done, files can be pushed to the master using the \fBcp.push\fP function: .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 in a subdirectory named \fBminions\fP under the master\(aqs \fBcachedir\fP\&. On most masters, this path will be \fB/var/cache/salt/master/minions\fP\&. Within this directory will be one directory for each minion which has pushed a file to the master, and underneath that the full path to the file on the minion. So, for example, if a minion with an ID of \fBdev1\fP pushed a file \fB/var/log/myapp.log\fP to the master, it would be saved to \fB/var/cache/salt/master/minions/dev1/var/log/myapp.log\fP\&. .SS Serving Pushed Files Using MinionFS .sp While it is certainly possible to add \fB/var/cache/salt/master/minions\fP to the master\(aqs \fBfile_roots\fP and serve these files, it may only be desirable to expose files pushed from certain minions. Adding \fB/var/cache/salt/master/minions/\fP for each minion that needs to be exposed can be cumbersome and prone to errors. .sp Enter \fBminionfs\fP\&. This fileserver backend will make files pushed using \fBcp.push\fP available to the Salt fileserver, and provides an easy mechanism to restrict which minions\(aq pushed files are made available. .SS Simple Configuration .sp To use the \fBminionfs\fP backend, add \fBminion\fP to the list of backends in the \fBfileserver_backend\fP configuration option on the master: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C file_recv: True fileserver_backend: \- roots \- minion .ft P .fi .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 As described earlier, \fBfile_recv: True\fP is also needed to enable the master to receive files pushed from minions. As always, changes to the master configuration require a restart of the \fBsalt\-master\fP service. .UNINDENT .UNINDENT .sp Files made available via \fBminionfs\fP are by default located at \fBsalt:///path/to/file\fP\&. Think back to the earlier example, in which \fBdev1\fP pushed a file \fB/var/log/myapp.log\fP to the master. With \fBminionfs\fP enabled, this file would be addressable in Salt at \fBsalt://dev1/var/log/myapp.log\fP\&. .sp If many minions have pushed to the master, this will result in many directories in the root of the Salt fileserver. For this reason, it is recommended to use the \fBminionfs_mountpoint\fP config option to organize these files underneath a subdirectory: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C minionfs_mountpoint: salt://minionfs .ft P .fi .UNINDENT .UNINDENT .sp Using the above mountpoint, the file in the example would be located at \fBsalt://minionfs/dev1/var/log/myapp.log\fP\&. .SS Restricting Certain Minions\(aq Files from Being Available Via MinionFS .sp A whitelist and blacklist can be used to restrict the minions whose pushed files are available via \fBminionfs\fP\&. These lists can be managed using the \fBminionfs_whitelist\fP and \fBminionfs_blacklist\fP config options. Click the links for both of them for a detailed explanation of how to use them. .sp A more complex configuration example, which uses both a whitelist and blacklist, can be found below: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C file_recv: True fileserver_backend: \- roots \- minion minionfs_mountpoint: salt://minionfs minionfs_whitelist: \- host04 \- web* \- \(aqmail\ed+\e.domain\e.tld\(aq minionfs_whitelist: \- web21 .ft P .fi .UNINDENT .UNINDENT .SS Potential Concerns .INDENT 0.0 .IP \(bu 2 There is no access control in place to restrict which minions have access to files served up by \fBminionfs\fP\&. All minions will have access to these files. .IP \(bu 2 Unless the \fBminionfs_whitelist\fP and/or \fBminionfs_blacklist\fP config options are used, all minions which push files to the master will have their files made available via \fBminionfs\fP\&. .UNINDENT .SS Salt Package Manager .sp The Salt Package Manager, or SPM, enables Salt formulas to be packaged to simplify distribution to Salt masters. The design of SPM was influenced by other existing packaging systems including RPM, Yum, and Pacman. [image] .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 The previous diagram shows each SPM component as a different system, but this is not required. You can build packages and host the SPM repo on a single Salt master if you\(aqd like. .UNINDENT .UNINDENT .sp \fBPackaging System\fP .sp The packaging system is used to package the state, pillar, file templates, and other files used by your formula into a single file. After a formula package is created, it is copied to the Repository System where it is made available to Salt masters. .sp See Building SPM Packages .sp \fBRepo System\fP .sp The Repo system stores the SPM package and metadata files and makes them available to Salt masters via http(s), ftp, or file URLs. SPM repositories can be hosted on a Salt Master, a Salt Minion, or on another system. .sp See Distributing SPM Packages .sp \fBSalt Master\fP .sp SPM provides Salt master settings that let you configure the URL of one or more SPM repos. You can then quickly install packages that contain entire formulas to your Salt masters using SPM. .sp See Installing SPM Packages .sp \fBContents\fP .SS Building SPM Packages .sp The first step when using Salt Package Manager is to build packages for each of of the formulas that you want to distribute. Packages can be built on any system where you can install Salt. .SS Package Build Overview .sp To build a package, all state, pillar, jinja, and file templates used by your formula are assembled into a folder on the build system. These files can be cloned from a Git repository, such as those found at the \fI\%saltstack\-formulas\fP organization on GitHub, or copied directly to the folder. .sp The following diagram demonstrates a typical formula layout on the build system: [image] .sp In this example, all formula files are placed in a \fBmyapp\-formula\fP folder. This is the folder that is targeted by the \fBspm build\fP command when this package is built. .sp Within this folder, pillar data is placed in a \fBpillar.example\fP file at the root, and all state, jinja, and template files are placed within a subfolder that is named after the application being packaged. State files are typically contained within a subfolder, similar to how state files are organized in the state tree. Any non\-pillar files in your package that are not contained in a subfolder are placed at the root of the spm state tree. .sp Additionally, a FORMULA file is created and placed in the root of the folder. This file contains package metadata that is used by SPM. .SS Package Installation Overview .sp When building packages, it is useful to know where files are installed on the Salt master. During installation, all files except \fBpillar.example\fP and \fBFORMULA\fP are copied directly to the spm state tree on the Salt master (located at \fB\esrv\espm\esalt\fP). .sp If a \fBpillar.example\fP file is present in the root, it is renamed to \fB.sls.orig\fP and placed in the \fBpillar_path\fP\&. [image] .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 Even though the pillar data file is copied to the pillar root, you still need to manually assign this pillar data to systems using the pillar top file. This file can also be duplicated and renamed so the \fB\&.orig\fP version is left intact in case you need to restore it later. .UNINDENT .UNINDENT .SS Building an SPM Formula Package .INDENT 0.0 .IP 1. 3 Assemble formula files in a folder on the build system. .IP 2. 3 Create a FORMULA file and place it in the root of the package folder. .IP 3. 3 Run \fBspm build \fP\&. The package is built and placed in the \fB/srv/spm_build\fP folder. .INDENT 3.0 .INDENT 3.5 .sp .nf .ft C spm build /path/to/salt\-packages\-source/myapp\-formula .ft P .fi .UNINDENT .UNINDENT .IP 4. 3 Copy the \fB\&.spm\fP file to a folder on the repository system\&. .UNINDENT .SS Types of Packages .sp SPM supports different types of packages. The function of each package is denoted by its name. For instance, packages which end in \fB\-formula\fP are considered to be Salt States (the most common type of formula). Packages which end in \fB\-conf\fP contain configuration which is to be placed in the \fB/etc/salt/\fP directory. Packages which do not contain one of these names are treated as if they have a \fB\-formula\fP name. .SS formula .sp By default, most files from this type of package live in the \fB/srv/spm/salt/\fP directory. The exception is the \fBpillar.example\fP file, which will be renamed to \fB.sls\fP and placed in the pillar directory (\fB/srv/spm/pillar/\fP by default). .SS reactor .sp By default, files from this type of package live in the \fB/srv/spm/reactor/\fP directory. .SS conf .sp The files in this type of package are configuration files for Salt, which normally live in the \fB/etc/salt/\fP directory. Configuration files for packages other than Salt can and should be handled with a Salt State (using a \fBformula\fP type of package). .SS Technical Information .sp Packages are built using BZ2\-compressed tarballs. By default, the package database is stored using the \fBsqlite3\fP driver (see Loader Modules below). .sp Support for these are built into Python, and so no external dependencies are needed. .sp All other files belonging to SPM use YAML, for portability and ease of use and maintainability. .SS SPM\-Specific Loader Modules .sp SPM was designed to behave like traditional package managers, which apply files to the filesystem and store package metadata in a local database. However, because modern infrastructures often extend beyond those use cases, certain parts of SPM have been broken out into their own set of modules. .SS Package Database .sp By default, the package database is stored using the \fBsqlite3\fP module. This module was chosen because support for SQLite3 is built into Python itself. .sp Please see the SPM Development Guide for information on creating new modules for package database management. .SS Package Files .sp By default, package files are installed using the \fBlocal\fP module. This module applies files to the local filesystem, on the machine that the package is installed on. .sp Please see the SPM Development Guide for information on creating new modules for package file management. .SS Distributing SPM Packages .sp SPM packages can be distributed to Salt masters over HTTP(S), FTP, or through the file system. The SPM repo can be hosted on any system where you can install Salt. Salt is installed so you can run the \fBspm create_repo\fP command when you update or add a package to the repo. SPM repos do not require the salt\-master, salt\-minion, or any other process running on the system. .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 If you are hosting the SPM repo on a system where you can not or do not want to install Salt, you can run the \fBspm create_repo\fP command on the build system and then copy the packages and the generated \fBSPM\-METADATA\fP file to the repo. You can also install SPM files directly on a Salt master, bypassing the repository completely. .UNINDENT .UNINDENT .SS Setting up a Package Repository .sp After packages are built, the generated SPM files are placed in the \fBsrv/spm_build\fP folder. .sp Where you place the built SPM files on your repository server depends on how you plan to make them available to your Salt masters. .sp You can share the \fBsrv/spm_build\fP folder on the network, or copy the files to your FTP or Web server. .SS Adding a Package to the repository .sp New packages are added by simply copying the SPM file to the repo folder, and then generating repo metadata. .SS Generate Repo Metadata .sp Each time you update or add an SPM package to your repository, issue an \fBspm create_repo\fP command: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C spm create_repo /srv/spm_build .ft P .fi .UNINDENT .UNINDENT .sp SPM generates the repository metadata for all of the packages in that directory and places it in an \fBSPM\-METADATA\fP file at the folder root. This command is used even if repository metadata already exists in that directory. .SS Installing SPM Packages .sp SPM packages are installed to your Salt master, where they are available to Salt minions using all of Salt\(aqs package management functions. .SS Configuring Remote Repositories .sp Before SPM can use a repository, two things need to happen. First, the Salt master needs to know where the repository is through a configuration process. Then it needs to pull down the repository metadata. .SS Repository Configuration Files .sp Repositories are configured by adding each of them to the \fB/etc/salt/spm.repos.d/spm.repo\fP file on each Salt master. This file contains the name of the repository, and the link to the repository: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C my_repo: url: https://spm.example.com/ .ft P .fi .UNINDENT .UNINDENT .sp The URL can use \fBhttp\fP, \fBhttps\fP, \fBftp\fP, or \fBfile\fP\&. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C my_repo: url: file:///srv/spm_build .ft P .fi .UNINDENT .UNINDENT .SS Updating Local Repository Metadata .sp After the repository is configured on the Salt master, repository metadata is downloaded using the \fBspm update_repo\fP command: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C spm update_repo .ft P .fi .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 A file for each repo is placed in \fB/var/cache/salt/spm\fP on the Salt master after you run the \fIupdate_repo\fP command. If you add a repository and it does not seem to be showing up, check this path to verify that the repository was found. .UNINDENT .UNINDENT .SS Update File Roots .sp SPM packages are installed to the \fBsrv/spm/salt\fP folder on your Salt master. This path needs to be added to the file roots on your Salt master manually. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C file_roots: base: 1. /srv/salt 2. /srv/spm/salt .ft P .fi .UNINDENT .UNINDENT .sp Restart the salt\-master service after updating the \fBfile_roots\fP setting. .SS Installing Packages .sp To install a package, use the \fBspm install\fP command: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C spm install apache .ft P .fi .UNINDENT .UNINDENT .sp \fBWARNING:\fP .INDENT 0.0 .INDENT 3.5 Currently, SPM does not check to see if files are already in place before installing them. That means that existing files will be overwritten without warning. .UNINDENT .UNINDENT .SS Installing directly from an SPM file .sp You can also install SPM packages using a local SPM file using the \fBspm local install\fP command: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C spm local install /srv/spm/apache\-201506\-1.spm .ft P .fi .UNINDENT .UNINDENT .sp An SPM repository is not required when using \fIspm local install\fP\&. .SS Pillars .sp If an installed package includes Pillar data, be sure to target the installed pillar to the necessary systems using the pillar Top file. .SS Removing Packages .sp Packages may be removed after they are installed using the \fBspm remove\fP command. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C spm remove apache .ft P .fi .UNINDENT .UNINDENT .sp If files have been modified, they will not be removed. Empty directories will also be removed. .SS SPM Configuration .sp There are a number of options that are specific to SPM. They may be configured in the \fBmaster\fP configuration file, or in SPM\(aqs own \fBspm\fP configuration file (normally located at \fB/etc/salt/spm\fP). If configured in both places, the \fBspm\fP file takes precedence. In general, these values will not need to be changed from the defaults. .SS spm_logfile .sp Default: \fB/var/log/salt/spm\fP .sp Where SPM logs messages. .SS spm_repos_config .sp Default: \fB/etc/salt/spm.repos\fP .sp SPM repositories are configured with this file. There is also a directory which corresponds to it, which ends in \fB\&.d\fP\&. For instance, if the filename is \fB/etc/salt/spm.repos\fP, the directory will be \fB/etc/salt/spm.repos.d/\fP\&. .SS spm_cache_dir .sp Default: \fB/var/cache/salt/spm\fP .sp When SPM updates package repository metadata and downloads packaged, they will be placed in this directory. The package database, normally called \fBpackages.db\fP, also lives in this directory. .SS spm_db .sp Default: \fB/var/cache/salt/spm/packages.db\fP .sp The location and name of the package database. This database stores the names of all of the SPM packages installed on the system, the files that belong to them, and the metadata for those files. .SS spm_build_dir .sp Default: \fB/srv/spm_build\fP .sp When packages are built, they will be placed in this directory. .SS spm_build_exclude .sp Default: \fB[\(aq.git\(aq]\fP .sp When SPM builds a package, it normally adds all files in the formula directory to the package. Files listed here will be excluded from that package. This option requires a list to be specified. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C spm_build_exclude: \- .git \- .svn .ft P .fi .UNINDENT .UNINDENT .SS Types of Packages .sp SPM supports different types of formula packages. The function of each package is denoted by its name. For instance, packages which end in \fB\-formula\fP are considered to be Salt States (the most common type of formula). Packages which end in \fB\-conf\fP contain configuration which is to be placed in the \fB/etc/salt/\fP directory. Packages which do not contain one of these names are treated as if they have a \fB\-formula\fP name. .SS formula .sp By default, most files from this type of package live in the \fB/srv/spm/salt/\fP directory. The exception is the \fBpillar.example\fP file, which will be renamed to \fB.sls\fP and placed in the pillar directory (\fB/srv/spm/pillar/\fP by default). .SS reactor .sp By default, files from this type of package live in the \fB/srv/spm/reactor/\fP directory. .SS conf .sp The files in this type of package are configuration files for Salt, which normally live in the \fB/etc/salt/\fP directory. Configuration files for packages other than Salt can and should be handled with a Salt State (using a \fBformula\fP type of package). .SS FORMULA File .sp In addition to the formula itself, a \fBFORMULA\fP file must exist which describes the package. An example of this file is: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C name: apache os: RedHat, Debian, Ubuntu, SUSE, FreeBSD os_family: RedHat, Debian, SUSE, FreeBSD version: 201506 release: 2 summary: Formula for installing Apache description: Formula for installing Apache .ft P .fi .UNINDENT .UNINDENT .SS Required Fields .sp This file must contain at least the following fields: .SS name .sp The name of the package, as it will appear in the package filename, in the repository metadata, and the package database. Even if the source formula has \fB\-formula\fP in its name, this name should probably not include that. For instance, when packaging the \fBapache\-formula\fP, the name should be set to \fBapache\fP\&. .SS os .sp The value of the \fBos\fP grain that this formula supports. This is used to help users know which operating systems can support this package. .SS os_family .sp The value of the \fBos_family\fP grain that this formula supports. This is used to help users know which operating system families can support this package. .SS version .sp The version of the package. While it is up to the organization that manages this package, it is suggested that this version is specified in a \fBYYYYMM\fP format. For instance, if this version was released in June 2015, the package version should be \fB201506\fP\&. If multiple releases are made in a month, the \fBrelease\fP field should be used. .SS minimum_version .sp Minimum recommended version of Salt to use this formula. Not currently enforced. .SS release .sp This field refers primarily to a release of a version, but also to multiple versions within a month. In general, if a version has been made public, and immediate updates need to be made to it, this field should also be updated. .SS summary .sp A one\-line description of the package. .SS description .sp A more detailed description of the package which can contain more than one line. .SS Optional Fields .sp The following fields may also be present. .SS top_level_dir .sp This field is optional, but highly recommended. If it is not specified, the package name will be used. .sp Formula repositories typically do not store \fB\&.sls\fP files in the root of the repository; instead they are stored in a subdirectory. For instance, an \fBapache\-formula\fP repository would contain a directory called \fBapache\fP, which would contain an \fBinit.sls\fP, plus a number of other related files. In this instance, the \fBtop_level_dir\fP should be set to \fBapache\fP\&. .sp Files outside the \fBtop_level_dir\fP, such as \fBREADME.rst\fP, \fBFORMULA\fP, and \fBLICENSE\fP will not be installed. The exceptions to this rule are files that are already treated specially, such as \fBpillar.example\fP and \fB_modules/\fP\&. .SS dependencies .sp A comma\-separated list of packages that must be installed along with this package. When this package is installed, SPM will attempt to discover and install these packages as well. If it is unable to, then it will refuse to install this package. .sp This is useful for creating packages which tie together other packages. For instance, a package called wordpress\-mariadb\-apache would depend upon wordpress, mariadb, and apache. .SS optional .sp A comma\-separated list of packages which are related to this package, but are neither required nor necessarily recommended. This list is displayed in an informational message when the package is installed to SPM. .SS recommended .sp A comma\-separated list of optional packages that are recommended to be installed with the package. This list is displayed in an informational message when the package is installed to SPM. .SS Building a Package .sp Once a \fBFORMULA\fP file has been created, it is placed into the root of the formula that is to be turned into a package. The \fBspm build\fP command is used to turn that formula into a package: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C spm build /path/to/saltstack\-formulas/apache\-formula .ft P .fi .UNINDENT .UNINDENT .sp The resulting file will be placed in the build directory. By default this directory is located at \fB/srv/spm/\fP\&. .SS Loader Modules .sp When an execution module is placed in \fB/_modules/\fP on the master, it will automatically be synced to minions, the next time a sync operation takes place. Other modules are also propagated this way: state modules can be placed in \fB_states/\fP, and so on. .sp When SPM detects a file in a package which resides in one of these directories, that directory will be placed in \fB\fP instead of in the formula directory with the rest of the files. .SS Removing Packages .sp Packages may be removed once they are installed using the \fBspm remove\fP command. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C spm remove apache .ft P .fi .UNINDENT .UNINDENT .sp If files have been modified, they will not be removed. Empty directories will also be removed. .SS Technical Information .sp Packages are built using BZ2\-compressed tarballs. By default, the package database is stored using the \fBsqlite3\fP driver (see Loader Modules below). .sp Support for these are built into Python, and so no external dependencies are needed. .sp All other files belonging to SPM use YAML, for portability and ease of use and maintainability. .SS SPM\-Specific Loader Modules .sp SPM was designed to behave like traditional package managers, which apply files to the filesystem and store package metadata in a local database. However, because modern infrastructures often extend beyond those use cases, certain parts of SPM have been broken out into their own set of modules. .SS Package Database .sp By default, the package database is stored using the \fBsqlite3\fP module. This module was chosen because support for SQLite3 is built into Python itself. .sp Please see the SPM Development Guide for information on creating new modules for package database management. .SS Package Files .sp By default, package files are installed using the \fBlocal\fP module. This module applies files to the local filesystem, on the machine that the package is installed on. .sp Please see the SPM Development Guide for information on creating new modules for package file management. .SS Types of Packages .sp SPM supports different types of formula packages. The function of each package is denoted by its name. For instance, packages which end in \fB\-formula\fP are considered to be Salt States (the most common type of formula). Packages which end in \fB\-conf\fP contain configuration which is to be placed in the \fB/etc/salt/\fP directory. Packages which do not contain one of these names are treated as if they have a \fB\-formula\fP name. .SS formula .sp By default, most files from this type of package live in the \fB/srv/spm/salt/\fP directory. The exception is the \fBpillar.example\fP file, which will be renamed to \fB.sls\fP and placed in the pillar directory (\fB/srv/spm/pillar/\fP by default). .SS reactor .sp By default, files from this type of package live in the \fB/srv/spm/reactor/\fP directory. .SS conf .sp The files in this type of package are configuration files for Salt, which normally live in the \fB/etc/salt/\fP directory. Configuration files for packages other than Salt can and should be handled with a Salt State (using a \fBformula\fP type of package). .SS SPM Development Guide .sp This document discusses developing additional code for SPM. .SS SPM\-Specific Loader Modules .sp SPM was designed to behave like traditional package managers, which apply files to the filesystem and store package metadata in a local database. However, because modern infrastructures often extend beyond those use cases, certain parts of SPM have been broken out into their own set of modules. .sp Each function that accepts arguments has a set of required and optional arguments. Take note that SPM will pass all arguments in, and therefore each function must accept each of those arguments. However, arguments that are marked as required are crucial to SPM\(aqs core functionality, while arguments that are marked as optional are provided as a benefit to the module, if it needs to use them. .SS Package Database .sp By default, the package database is stored using the \fBsqlite3\fP module. This module was chosen because support for SQLite3 is built into Python itself. .sp Modules for managing the package database are stored in the \fBsalt/spm/pkgdb/\fP directory. A number of functions must exist to support database management. .SS init() .sp Get a database connection, and initialize the package database if necessary. .sp This function accepts no arguments. If a database is used which supports a connection object, then that connection object is returned. For instance, the \fBsqlite3\fP module returns a \fBconnect()\fP object from the \fBsqlite3\fP library: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C conn = sqlite3.connect(__opts__[\(aqspm_db\(aq], isolation_level=None) \&... return conn .ft P .fi .UNINDENT .UNINDENT .sp SPM itself will not use this connection object; it will be passed in as\-is to the other functions in the module. Therefore, when you set up this object, make sure to do so in a way that is easily usable throughout the module. .SS info() .sp Return information for a package. This generally consists of the information that is stored in the \fBFORMULA\fP file in the package. .sp The arguments that are passed in, in order, are \fBpackage\fP (required) and \fBconn\fP (optional). .sp \fBpackage\fP is the name of the package, as specified in the \fBFORMULA\fP\&. \fBconn\fP is the connection object returned from \fBinit()\fP\&. .SS list_files() .sp Return a list of files for an installed package. Only the filename should be returned, and no other information. .sp The arguments that are passed in, in order, are \fBpackage\fP (required) and \fBconn\fP (optional). .sp \fBpackage\fP is the name of the package, as specified in the \fBFORMULA\fP\&. \fBconn\fP is the connection object returned from \fBinit()\fP\&. .SS register_pkg() .sp Register a package in the package database. Nothing is expected to be returned from this function. .sp The arguments that are passed in, in order, are \fBname\fP (required), \fBformula_def\fP (required), and \fBconn\fP (optional). .sp \fBname\fP is the name of the package, as specified in the \fBFORMULA\fP\&. \fBformula_def\fP is the contents of the \fBFORMULA\fP file, as a \fBdict\fP\&. \fBconn\fP is the connection object returned from \fBinit()\fP\&. .SS register_file() .sp Register a file in the package database. Nothing is expected to be returned from this function. .sp The arguments that are passed in are \fBname\fP (required), \fBmember\fP (required), \fBpath\fP (required), \fBdigest\fP (optional), and \fBconn\fP (optional). .sp \fBname\fP is the name of the package. .sp \fBmember\fP is a \fBtarfile\fP object for the package file. It is included, because it contains most of the information for the file. .sp \fBpath\fP is the location of the file on the local filesystem. .sp \fBdigest\fP is the SHA1 checksum of the file. .sp \fBconn\fP is the connection object returned from \fBinit()\fP\&. .SS unregister_pkg() .sp Unregister a package from the package database. This usually only involves removing the package\(aqs record from the database. Nothing is expected to be returned from this function. .sp The arguments that are passed in, in order, are \fBname\fP (required) and \fBconn\fP (optional). .sp \fBname\fP is the name of the package, as specified in the \fBFORMULA\fP\&. \fBconn\fP is the connection object returned from \fBinit()\fP\&. .SS unregister_file() .sp Unregister a package from the package database. This usually only involves removing the package\(aqs record from the database. Nothing is expected to be returned from this function. .sp The arguments that are passed in, in order, are \fBname\fP (required), \fBpkg\fP (optional) and \fBconn\fP (optional). .sp \fBname\fP is the path of the file, as it was installed on the filesystem. .sp \fBpkg\fP is the name of the package that the file belongs to. .sp \fBconn\fP is the connection object returned from \fBinit()\fP\&. .SS db_exists() .sp Check to see whether the package database already exists. This is the path to the package database file. This function will return \fBTrue\fP or \fBFalse\fP\&. .sp The only argument that is expected is \fBdb_\fP, which is the package database file. .SS Package Files .sp By default, package files are installed using the \fBlocal\fP module. This module applies files to the local filesystem, on the machine that the package is installed on. .sp Modules for managing the package database are stored in the \fBsalt/spm/pkgfiles/\fP directory. A number of functions must exist to support file management. .SS init() .sp Initialize the installation location for the package files. Normally these will be directory paths, but other external destinations such as databases can be used. For this reason, this function will return a connection object, which can be a database object. However, in the default \fBlocal\fP module, this object is a dict containing the paths. This object will be passed into all other functions. .sp Three directories are used for the destinations: \fBformula_path\fP, \fBpillar_path\fP, and \fBreactor_path\fP\&. .sp \fBformula_path\fP is the location of most of the files that will be installed. The default is specific to the operating system, but is normally \fB/srv/salt/\fP\&. .sp \fBpillar_path\fP is the location that the \fBpillar.example\fP file will be installed to. The default is specific to the operating system, but is normally \fB/srv/pillar/\fP\&. .sp \fBreactor_path\fP is the location that reactor files will be installed to. The default is specific to the operating system, but is normally \fB/srv/reactor/\fP\&. .SS check_existing() .sp Check the filesystem for existing files. All files for the package will be checked, and if any are existing, then this function will normally state that SPM will refuse to install the package. .sp This function returns a list of the files that exist on the system. .sp The arguments that are passed into this function are, in order: \fBpackage\fP (required), \fBpkg_files\fP (required), \fBformula_def\fP (formula_def), and \fBconn\fP (optional). .sp \fBpackage\fP is the name of the package that is to be installed. .sp \fBpkg_files\fP is a list of the files to be checked. .sp \fBformula_def\fP is a copy of the information that is stored in the \fBFORMULA\fP file. .sp \fBconn\fP is the file connection object. .SS install_file() .sp Install a single file to the destination (normally on the filesystem). Nothing is expected to be returned from this function. .sp This function returns the final location that the file was installed to. .sp The arguments that are passed into this function are, in order, \fBpackage\fP (required), \fBformula_tar\fP (required), \fBmember\fP (required), \fBformula_def\fP (required), and \fBconn\fP (optional). .sp \fBpackage\fP is the name of the package that is to be installed. .sp \fBformula_tar\fP is the tarfile object for the package. This is passed in so that the function can call \fBformula_tar.extract()\fP for the file. .sp \fBmember\fP is the tarfile object which represents the individual file. This may be modified as necessary, before being passed into \fBformula_tar.extract()\fP\&. .sp \fBformula_def\fP is a copy of the information from the \fBFORMULA\fP file. .sp \fBconn\fP is the file connection object. .SS remove_file() .sp Remove a single file from file system. Normally this will be little more than an \fBos.remove()\fP\&. Nothing is expected to be returned from this function. .sp The arguments that are passed into this function are, in order, \fBpath\fP (required) and \fBconn\fP (optional). .sp \fBpath\fP is the absolute path to the file to be removed. .sp \fBconn\fP is the file connection object. .SS hash_file() .sp Returns the hexdigest hash value of a file. .sp The arguments that are passed into this function are, in order, \fBpath\fP (required), \fBhashobj\fP (required), and \fBconn\fP (optional). .sp \fBpath\fP is the absolute path to the file. .sp \fBhashobj\fP is a reference to \fBhashlib.sha1()\fP, which is used to pull the \fBhexdigest()\fP for the file. .sp \fBconn\fP is the file connection object. .sp This function will not generally be more complex than: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C def hash_file(path, hashobj, conn=None): with salt.utils.fopen(path, \(aqr\(aq) as f: hashobj.update(f.read()) return hashobj.hexdigest() .ft P .fi .UNINDENT .UNINDENT .SS path_exists() .sp Check to see whether the file already exists on the filesystem. Returns \fBTrue\fP or \fBFalse\fP\&. .sp This function expects a \fBpath\fP argument, which is the absolute path to the file to be checked. .SS path_isdir() .sp Check to see whether the path specified is a directory. Returns \fBTrue\fP or \fBFalse\fP\&. .sp This function expects a \fBpath\fP argument, which is the absolute path to be checked. .SS Storing Data in Other Databases .sp The SDB interface is designed to store and retrieve data that, unlike pillars and grains, is not necessarily minion\-specific. The initial design goal was to allow passwords to be stored in a secure database, such as one managed by the keyring package, rather than as plain\-text files. However, as a generic database interface, it could conceptually be used for a number of other purposes. .sp SDB was added to Salt in version 2014.7.0. .SS SDB Configuration .sp In order to use the SDB interface, a configuration profile must be set up in either the master or minion configuration file. The configuration stanza includes the name/ID that the profile will be referred to as, a \fBdriver\fP setting, and any other arguments that are necessary for the SDB module that will be used. For instance, a profile called \fBmykeyring\fP, which uses the \fBsystem\fP service in the \fBkeyring\fP module would look like: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C mykeyring: driver: keyring service: system .ft P .fi .UNINDENT .UNINDENT .sp It is recommended to keep the name of the profile simple, as it is used in the SDB URI as well. .SS SDB URIs .sp SDB is designed to make small database queries (hence the name, SDB) using a compact URL. This allows users to reference a database value quickly inside a number of Salt configuration areas, without a lot of overhead. The basic format of an SDB URI is: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C sdb:/// .ft P .fi .UNINDENT .UNINDENT .sp The profile refers to the configuration profile defined in either the master or the minion configuration file. The args are specific to the module referred to in the profile, but will typically only need to refer to the key of a key/value pair inside the database. This is because the profile itself should define as many other parameters as possible. .sp For example, a profile might be set up to reference credentials for a specific OpenStack account. The profile might look like: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C kevinopenstack: driver: keyring service: salt.cloud.openstack.kevin .ft P .fi .UNINDENT .UNINDENT .sp And the URI used to reference the password might look like: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C sdb://kevinopenstack/password .ft P .fi .UNINDENT .UNINDENT .SS Getting, Setting and Deleting SDB Values .sp Once an SDB driver is configured, you can use the \fBsdb\fP execution module to get, set and delete values from it. There are two functions that may appear in most SDB modules: \fBget\fP, \fBset\fP and \fBdelete\fP\&. .sp Getting a value requires only the SDB URI to be specified. To retrieve a value from the \fBkevinopenstack\fP profile above, you would use: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt\-call sdb.get sdb://kevinopenstack/password .ft P .fi .UNINDENT .UNINDENT .sp Some drivers use slightly more complex URIs. For instance, the \fBvault\fP driver requires the full path to where the key is stored, followed by a question mark, followed by the key to be retrieved. If you were using a profile called \fBmyvault\fP, you would use a URI that looks like: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt\-call sdb.get \(aqsdb://myvault/secret/salt?saltstack\(aq .ft P .fi .UNINDENT .UNINDENT .sp Setting a value uses the same URI as would be used to retrieve it, followed by the value as another argument. For the above \fBmyvault\fP URI, you would set a new value using a command like: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt\-call sdb.set \(aqsdb://myvault/secret/salt?saltstack\(aq \(aqsuper awesome\(aq .ft P .fi .UNINDENT .UNINDENT .sp Deleting values (if supported by the driver) is done pretty much the same way as getting them. Provided that you have a profile called \fBmykvstore\fP that uses a driver allowing to delete values you would delete a value as shown bellow: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt\-call sdb.delete \(aqsdb://mykvstore/foobar\(aq .ft P .fi .UNINDENT .UNINDENT .sp The \fBsdb.get\fP, \fBsdb.set\fP and \fBsdb.delete\fP functions are also available in the runner system: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt\-run sdb.get \(aqsdb://myvault/secret/salt?saltstack\(aq salt\-run sdb.set \(aqsdb://myvault/secret/salt?saltstack\(aq \(aqsuper awesome\(aq salt\-run sdb.delete \(aqsdb://mykvstore/foobar\(aq .ft P .fi .UNINDENT .UNINDENT .SS Using SDB URIs in Files .sp SDB URIs can be used in both configuration files, and files that are processed by the renderer system (jinja, mako, etc.). In a configuration file (such as \fB/etc/salt/master\fP, \fB/etc/salt/minion\fP, \fB/etc/salt/cloud\fP, etc.), make an entry as usual, and set the value to the SDB URI. For instance: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C mykey: sdb://myetcd/mykey .ft P .fi .UNINDENT .UNINDENT .sp To retrieve this value using a module, the module in question must use the \fBconfig.get\fP function to retrieve configuration values. This would look something like: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C mykey = __salt__[\(aqconfig.get\(aq](\(aqmykey\(aq) .ft P .fi .UNINDENT .UNINDENT .sp Templating renderers use a similar construct. To get the \fBmykey\fP value from above in Jinja, you would use: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C {{ salt[\(aqconfig.get\(aq](\(aqmykey\(aq) }} .ft P .fi .UNINDENT .UNINDENT .sp When retrieving data from configuration files using \fBconfig.get\fP, the SDB URI need only appear in the configuration file itself. .sp If you would like to retrieve a key directly from SDB, you would call the \fBsdb.get\fP function directly, using the SDB URI. For instance, in Jinja: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C {{ salt[\(aqsdb.get\(aq](\(aqsdb://myetcd/mykey\(aq) }} .ft P .fi .UNINDENT .UNINDENT .sp When writing Salt modules, it is not recommended to call \fBsdb.get\fP directly, as it requires the user to provide values in SDB, using a specific URI. Use \fBconfig.get\fP instead. .SS Writing SDB Modules .sp There is currently one function that MUST exist in any SDB module (\fBget()\fP), one that SHOULD exist (\fBset_()\fP) and one that MAY exist (\fBdelete()\fP). If using a (\fBset_()\fP) function, a \fB__func_alias__\fP dictionary MUST be declared in the module as well: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C __func_alias__ = { \(aqset_\(aq: \(aqset\(aq, } .ft P .fi .UNINDENT .UNINDENT .sp This is because \fBset\fP is a Python built\-in, and therefore functions should not be created which are called \fBset()\fP\&. The \fB__func_alias__\fP functionality is provided via Salt\(aqs loader interfaces, and allows legally\-named functions to be referred to using names that would otherwise be unwise to use. .sp The \fBget()\fP function is required, as it will be called via functions in other areas of the code which make use of the \fBsdb://\fP URI. For example, the \fBconfig.get\fP function in the \fBconfig\fP execution module uses this function. .sp The \fBset_()\fP function may be provided, but is not required, as some sources may be read\-only, or may be otherwise unwise to access via a URI (for instance, because of SQL injection attacks). .sp The \fBdelete()\fP function may be provided as well, but is not required, as many sources may be read\-only or restrict such operations. .sp A simple example of an SDB module is \fBsalt/sdb/keyring_db.py\fP, as it provides basic examples of most, if not all, of the types of functionality that are available not only for SDB modules, but for Salt modules in general. .SS Running the Salt Master/Minion as an Unprivileged User .sp While the default setup runs the master and minion as the root user, some may consider it an extra measure of security to run the master as a non\-root user. Keep in mind that doing so does not change the master\(aqs capability to access minions as the user they are running as. Due to this many feel that running the master as a non\-root user does not grant any real security advantage which is why the master has remained as root by default. .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 Some of Salt\(aqs operations cannot execute correctly when the master is not running as root, specifically the pam external auth system, as this system needs root access to check authentication. .UNINDENT .UNINDENT .sp As of Salt 0.9.10 it is possible to run Salt 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 .IP \(bu 2 /var/run/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 /var/run/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 .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.apply .ft P .fi .UNINDENT .UNINDENT .sp This will cause the minion to check in with the master and ensure it is in the correct "state". .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 cron to run the \fBsalt\-call\fP command: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C 0 0 * * * salt\-call state.apply .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 When executing Salt using cron, keep in mind that the default PATH for cron may not include the path for any scripts or commands used by Salt, and it may be necessary to set the PATH accordingly in the crontab: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C PATH=/bin:/sbin:/usr/bin:/usr/sbin:/usr/local/bin:/usr/local/sbin:/opt/bin 0 0 * * * salt\-call state.apply .ft P .fi .UNINDENT .UNINDENT .UNINDENT .UNINDENT .SS Hardening Salt .sp This topic contains tips you can use to secure and harden your Salt environment. How you best secure and harden your Salt environment depends heavily on how you use Salt, where you use Salt, how your team is structured, where you get data from, and what kinds of access (internal and external) you require. .SS General hardening tips .INDENT 0.0 .IP \(bu 2 Restrict who can directly log into your Salt master system. .IP \(bu 2 Use SSH keys secured with a passphrase to gain access to the Salt master system. .IP \(bu 2 Track and secure SSH keys and any other login credentials you and your team need to gain access to the Salt master system. .IP \(bu 2 Use a hardened bastion server or a VPN to restrict direct access to the Salt master from the internet. .IP \(bu 2 Don\(aqt expose the Salt master any more than what is required. .IP \(bu 2 Harden the system as you would with any high\-priority target. .IP \(bu 2 Keep the system patched and up\-to\-date. .IP \(bu 2 Use tight firewall rules. .UNINDENT .SS Salt hardening tips .INDENT 0.0 .IP \(bu 2 Subscribe to \fI\%salt\-users\fP or \fI\%salt\-announce\fP so you know when new Salt releases are available. Keep your systems up\-to\-date with the latest patches. .IP \(bu 2 Use Salt\(aqs Client ACL system to avoid having to give out root access in order to run Salt commands. .IP \(bu 2 Use Salt\(aqs Client ACL system to restrict which users can run what commands. .IP \(bu 2 Use external Pillar to pull data into Salt from external sources so that non\-sysadmins (other teams, junior admins, developers, etc) can provide configuration data without needing access to the Salt master. .IP \(bu 2 Make heavy use of SLS files that are version\-controlled and go through a peer\-review/code\-review process before they\(aqre deployed and run in production. This is good advice even for "one\-off" CLI commands because it helps mitigate typos and mistakes. .IP \(bu 2 Use salt\-api, SSL, and restrict authentication with the external auth system if you need to expose your Salt master to external services. .IP \(bu 2 Make use of Salt\(aqs event system and reactor to allow minions to signal the Salt master without requiring direct access. .IP \(bu 2 Run the \fBsalt\-master\fP daemon as non\-root. .IP \(bu 2 Disable which modules are loaded onto minions with the \fBdisable_modules\fP setting. (for example, disable the \fBcmd\fP module if it makes sense in your environment.) .IP \(bu 2 Look through the fully\-commented sample master and minion config files. There are many options for securing an installation. .IP \(bu 2 Run masterless\-mode minions on particularly sensitive minions. There is also salt\-ssh or the \fBmodules.sudo\fP if you need to further restrict a minion. .UNINDENT .SS Security disclosure policy .INDENT 0.0 .TP .B email \fI\%security@saltstack.com\fP .TP .B gpg key ID 4EA0793D .TP .B gpg key fingerprint \fB8ABE 4EFC F0F4 B24B FF2A AF90 D570 F2D3 4EA0 793D\fP .UNINDENT .sp \fBgpg public key:\fP .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C \-\-\-\-\-BEGIN PGP PUBLIC KEY BLOCK\-\-\-\-\- Version: GnuPG/MacGPG2 v2.0.22 (Darwin) mQINBFO15mMBEADa3CfQwk5ED9wAQ8fFDku277CegG3U1hVGdcxqKNvucblwoKCb hRK6u9ihgaO9V9duV2glwgjytiBI/z6lyWqdaD37YXG/gTL+9Md+qdSDeaOa/9eg 7y+g4P+FvU9HWUlujRVlofUn5Dj/IZgUywbxwEybutuzvvFVTzsn+DFVwTH34Qoh QIuNzQCSEz3Lhh8zq9LqkNy91ZZQO1ZIUrypafspH6GBHHcE8msBFgYiNBnVcUFH u0r4j1Rav+621EtD5GZsOt05+NJI8pkaC/dDKjURcuiV6bhmeSpNzLaXUhwx6f29 Vhag5JhVGGNQxlRTxNEM86HEFp+4zJQ8m/wRDrGX5IAHsdESdhP+ljDVlAAX/ttP /Ucl2fgpTnDKVHOA00E515Q87ZHv6awJ3GL1veqi8zfsLaag7rw1TuuHyGLOPkDt t5PAjsS9R3KI7pGnhqI6bTOi591odUdgzUhZChWUUX1VStiIDi2jCvyoOOLMOGS5 AEYXuWYP7KgujZCDRaTNqRDdgPd93Mh9JI8UmkzXDUgijdzVpzPjYgFaWtyK8lsc Fizqe3/Yzf9RCVX/lmRbiEH+ql/zSxcWlBQd17PKaL+TisQFXcmQzccYgAxFbj2r QHp5ABEu9YjFme2Jzun7Mv9V4qo3JF5dmnUk31yupZeAOGZkirIsaWC3hwARAQAB tDBTYWx0U3RhY2sgU2VjdXJpdHkgVGVhbSA8c2VjdXJpdHlAc2FsdHN0YWNrLmNv bT6JAj4EEwECACgFAlO15mMCGwMFCQeGH4AGCwkIBwMCBhUIAgkKCwQWAgMBAh4B AheAAAoJENVw8tNOoHk9z/MP/2vzY27fmVxU5X8joiiturjlgEqQw41IYEmWv1Bw 4WVXYCHP1yu/1MC1uuvOmOd5BlI8YO2C2oyW7d1B0NorguPtz55b7jabCElekVCh h/H4ZVThiwqgPpthRv/2npXjIm7SLSs/kuaXo6Qy2JpszwDVFw+xCRVL0tH9KJxz HuNBeVq7abWD5fzIWkmGM9hicG/R2D0RIlco1Q0VNKy8klG+pOFOW886KnwkSPc7 JUYp1oUlHsSlhTmkLEG54cyVzrTP/XuZuyMTdtyTc3mfgW0adneAL6MARtC5UB/h q+v9dqMf4iD3wY6ctu8KWE8Vo5MUEsNNO9EA2dUR88LwFZ3ZnnXdQkizgR/Aa515 dm17vlNkSoomYCo84eN7GOTfxWcq+iXYSWcKWT4X+h/ra+LmNndQWQBRebVUtbKE ZDwKmiQz/5LY5EhlWcuU4lVmMSFpWXt5FR/PtzgTdZAo9QKkBjcv97LYbXvsPI69 El1BLAg+m+1UpE1L7zJT1il6PqVyEFAWBxW46wXCCkGssFsvz2yRp0PDX8A6u4yq rTkt09uYht1is61joLDJ/kq3+6k8gJWkDOW+2NMrmf+/qcdYCMYXmrtOpg/wF27W GMNAkbdyzgeX/MbUBCGCMdzhevRuivOI5bu4vT5s3KdshG+yhzV45bapKRd5VN+1 mZRquQINBFO15mMBEAC5UuLii9ZLz6qHfIJp35IOW9U8SOf7QFhzXR7NZ3DmJsd3 f6Nb/habQFIHjm3K9wbpj+FvaW2oWRlFVvYdzjUq6c82GUUjW1dnqgUvFwdmM835 1n0YQ2TonmyaF882RvsRZrbJ65uvy7SQxlouXaAYOdqwLsPxBEOyOnMPSktW5V2U IWyxsNP3sADchWIGq9p5D3Y/loyIMsS1dj+TjoQZOKSj7CuRT98+8yhGAY8YBEXu 9r3I9o6mDkuPpAljuMc8r09Im6az2egtK/szKt4Hy1bpSSBZU4W/XR7XwQNywmb3 wxjmYT6Od3Mwj0jtzc3gQiH8hcEy3+BO+NNmyzFVyIwOLziwjmEcw62S57wYKUVn HD2nglMsQa8Ve0e6ABBMEY7zGEGStva59rfgeh0jUMJiccGiUDTMs0tdkC6knYKb u/fdRqNYFoNuDcSeLEw4DdCuP01l2W4yY+fiK6hAcL25amjzc+yYo9eaaqTn6RAT bzdhHQZdpAMxY+vNT0+NhP1Zo5gYBMR65Zp/VhFsf67ijb03FUtdw9N8dHwiR2m8 vVA8kO/gCD6wS2p9RdXqrJ9JhnHYWjiVuXR+f755ZAndyQfRtowMdQIoiXuJEXYw 6XN+/BX81gJaynJYc0uw0MnxWQX+A5m8HqEsbIFUXBYXPgbwXTm7c4IHGgXXdwAR AQABiQIlBBgBAgAPBQJTteZjAhsMBQkHhh+AAAoJENVw8tNOoHk91rcQAIhxLv4g duF/J1Cyf6Wixz4rqslBQ7DgNztdIUMjCThg3eB6pvIzY5d3DNROmwU5JvGP1rEw hNiJhgBDFaB0J/y28uSci+orhKDTHb/cn30IxfuAuqrv9dujvmlgM7JUswOtLZhs 5FYGa6v1RORRWhUx2PQsF6ORg22QAaagc7OlaO3BXBoiE/FWsnEQCUsc7GnnPqi7 um45OJl/pJntsBUKvivEU20fj7j1UpjmeWz56NcjXoKtEvGh99gM5W2nSMLE3aPw vcKhS4yRyLjOe19NfYbtID8m8oshUDji0XjQ1z5NdGcf2V1YNGHU5xyK6zwyGxgV xZqaWnbhDTu1UnYBna8BiUobkuqclb4T9k2WjbrUSmTwKixokCOirFDZvqISkgmN r6/g3w2TRi11/LtbUciF0FN2pd7rj5mWrOBPEFYJmrB6SQeswWNhr5RIsXrQd/Ho zvNm0HnUNEe6w5YBfA6sXQy8B0Zs6pcgLogkFB15TuHIIIpxIsVRv5z8SlEnB7HQ Io9hZT58yjhekJuzVQB9loU0C/W0lzci/pXTt6fd9puYQe1DG37pSifRG6kfHxrR if6nRyrfdTlawqbqdkoqFDmEybAM9/hv3BqriGahGGH/hgplNQbYoXfNwYMYaHuB aSkJvrOQW8bpuAzgVyd7TyNFv+t1kLlfaRYJ =wBTJ \-\-\-\-\-END PGP PUBLIC KEY BLOCK\-\-\-\-\- .ft P .fi .UNINDENT .UNINDENT .sp The SaltStack Security Team is available at \fI\%security@saltstack.com\fP for security\-related bug reports or questions. .sp We request the disclosure of any security\-related bugs or issues be reported non\-publicly until such time as the issue can be resolved and a security\-fix release can be prepared. At that time we will release the fix and make a public announcement with upgrade instructions and download locations. .SS Security response procedure .sp SaltStack takes security and the trust of our customers and users very seriously. Our disclosure policy is intended to resolve security issues as quickly and safely as is possible. .INDENT 0.0 .IP 1. 3 A security report sent to \fI\%security@saltstack.com\fP is assigned to a team member. This person is the primary contact for questions and will coordinate the fix, release, and announcement. .IP 2. 3 The reported issue is reproduced and confirmed. A list of affected projects and releases is made. .IP 3. 3 Fixes are implemented for all affected projects and releases that are actively supported. Back\-ports of the fix are made to any old releases that are actively supported. .IP 4. 3 Packagers are notified via the \fI\%salt\-packagers\fP mailing list that an issue was reported and resolved, and that an announcement is incoming. .IP 5. 3 A new release is created and pushed to all affected repositories. The release documentation provides a full description of the issue, plus any upgrade instructions or other relevant details. .IP 6. 3 An announcement is made to the \fI\%salt\-users\fP and \fI\%salt\-announce\fP mailing lists. The announcement contains a description of the issue and a link to the full release documentation and download locations. .UNINDENT .SS Receiving security announcements .sp The fastest place to receive security announcements is via the \fI\%salt\-announce\fP mailing list. This list is low\-traffic. .SS Salt Transport .sp One of fundamental features of Salt is remote execution. Salt has two basic "channels" for communicating with minions. Each channel requires a client (minion) and a server (master) implementation to work within Salt. These pairs of channels will work together to implement the specific message passing required by the channel interface. .SS Pub Channel .sp The pub channel, or publish channel, is how a master sends a job (payload) to a minion. This is a basic pub/sub paradigm, which has specific targeting semantics. All data which goes across the publish system should be encrypted such that only members of the Salt cluster can decrypt the publishes. .SS Req Channel .sp The req channel is how the minions send data to the master. This interface is primarily used for fetching files and returning job returns. The req channels have two basic interfaces when talking to the master. \fBsend\fP is the basic method that guarantees the message is encrypted at least so that only minions attached to the same master can read it\-\- but no guarantee of minion\-master confidentiality, whereas the \fBcrypted_transfer_decode_dictentry\fP method does guarantee minion\-master confidentiality. .SS Zeromq Transport .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 Zeromq is the current default transport within Salt .UNINDENT .UNINDENT .sp Zeromq is a messaging library with bindings into many languages. Zeromq implements a socket interface for message passing, with specific semantics for the socket type. .SS Pub Channel .sp The pub channel is implemented using zeromq\(aqs pub/sub sockets. By default we don\(aqt use zeromq\(aqs filtering, which means that all publish jobs are sent to all minions and filtered minion side. Zeromq does have publisher side filtering which can be enabled in salt using \fBzmq_filtering\fP\&. .SS Req Channel .sp The req channel is implemented using zeromq\(aqs req/rep sockets. These sockets enforce a send/recv pattern, which forces salt to serialize messages through these socket pairs. This means that although the interface is asynchronous on the minion we cannot send a second message until we have received the reply of the first message. .SS TCP Transport .sp The tcp transport is an implementation of Salt\(aqs channels using raw tcp sockets. Since this isn\(aqt using a pre\-defined messaging library we will describe the wire protocol, message semantics, etc. in this document. .sp The tcp transport is enabled by changing the \fBtransport\fP setting to \fBtcp\fP on each Salt minion and Salt master. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C transport: tcp .ft P .fi .UNINDENT .UNINDENT .SS Wire Protocol .sp This implementation over TCP focuses on flexibility over absolute efficiency. This means we are okay to spend a couple of bytes of wire space for flexibility in the future. That being said, the wire framing is quite efficient and looks like: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C msgpack({\(aqhead\(aq: SOMEHEADER, \(aqbody\(aq: SOMEBODY}) .ft P .fi .UNINDENT .UNINDENT .sp Since msgpack is an iterably parsed serialization, we can simply write the serialized payload to the wire. Within that payload we have two items "head" and "body". Head contains header information (such as "message id"). The Body contains the actual message that we are sending. With this flexible wire protocol we can implement any message semantics that we\(aqd like\-\- including multiplexed message passing on a single socket. .SS Crypto .sp The current implementation uses the same crypto as the \fBzeromq\fP transport. .SS Pub Channel .sp For the pub channel we send messages without "message ids" which the remote end interprets as a one\-way send. .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 As of today we send all publishes to all minions and rely on minion\-side filtering. .UNINDENT .UNINDENT .SS Req Channel .sp For the req channel we send messages with a "message id". This "message id" allows us to multiplex messages across the socket. .SS The RAET Transport .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 The RAET transport is in very early development, it is functional but no promises are yet made as to its reliability or security. As for reliability and security, the encryption used has been audited and our tests show that raet is reliable. With this said we are still conducting more security audits and pushing the reliability. This document outlines the encryption used in RAET .UNINDENT .UNINDENT .sp New in version 2014.7.0. .sp The Reliable Asynchronous Event Transport, or RAET, is an alternative transport medium developed specifically with Salt in mind. It has been developed to allow queuing to happen up on the application layer and comes with socket layer encryption. It also abstracts a great deal of control over the socket layer and makes it easy to bubble up errors and exceptions. .sp RAET also offers very powerful message routing capabilities, allowing for messages to be routed between processes on a single machine all the way up to processes on multiple machines. Messages can also be restricted, allowing processes to be sent messages of specific types from specific sources allowing for trust to be established. .SS Using RAET in Salt .sp Using RAET in Salt is easy, the main difference is that the core dependencies change, instead of needing pycrypto, M2Crypto, ZeroMQ, and PYZMQ, the packages \fI\%libsodium\fP, libnacl, ioflo, and raet are required. Encryption is handled very cleanly by libnacl, while the queueing and flow control is handled by ioflo. Distribution packages are forthcoming, but \fI\%libsodium\fP can be easily installed from source, or many distributions do ship packages for it. The libnacl and ioflo packages can be easily installed from pypi, distribution packages are in the works. .sp Once the new deps are installed the 2014.7 release or higher of Salt needs to be installed. .sp Once installed, modify the configuration files for the minion and master to set the transport to raet: .sp \fB/etc/salt/master\fP: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C transport: raet .ft P .fi .UNINDENT .UNINDENT .sp \fB/etc/salt/minion\fP: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C transport: raet .ft P .fi .UNINDENT .UNINDENT .sp Now start salt as it would normally be started, the minion will connect to the master and share long term keys, which can then in turn be managed via salt\-key. Remote execution and salt states will function in the same way as with Salt over ZeroMQ. .SS Limitations .sp The 2014.7 release of RAET is not complete! The Syndic and Multi Master have not been completed yet and these are slated for completion in the 2015.5.0 release. .sp Also, Salt\-Raet allows for more control over the client but these hooks have not been implemented yet, thereforre the client still uses the same system as the ZeroMQ client. This means that the extra reliability that RAET exposes has not yet been implemented in the CLI client. .SS Why? .SS Customer and User Request .sp Why make an alternative transport for Salt? There are many reasons, but the primary motivation came from customer requests, many large companies came with requests to run Salt over an alternative transport, the reasoning was varied, from performance and scaling improvements to licensing concerns. These customers have partnered with SaltStack to make RAET a reality. .SS More Capabilities .sp RAET has been designed to allow salt to have greater communication capabilities. It has been designed to allow for development into features which out ZeroMQ topologies can\(aqt match. .sp Many of the proposed features are still under development and will be announced as they enter proof of concept phases, but these features include \fIsalt\-fuse\fP \- a filesystem over salt, \fIsalt\-vt\fP \- a parallel api driven shell over the salt transport and many others. .SS RAET Reliability .sp RAET is reliable, hence the name (Reliable Asynchronous Event Transport). .sp The concern posed by some over RAET reliability is based on the fact that RAET uses UDP instead of TCP and UDP does not have built in reliability. .sp RAET itself implements the needed reliability layers that are not natively present in UDP, this allows RAET to dynamically optimize packet delivery in a way that keeps it both reliable and asynchronous. .SS RAET and ZeroMQ .sp When using RAET, ZeroMQ is not required. RAET is a complete networking replacement. It is noteworthy that RAET is not a ZeroMQ replacement in a general sense, the ZeroMQ constructs are not reproduced in RAET, but they are instead implemented in such a way that is specific to Salt\(aqs needs. .sp RAET is primarily an async communication layer over truly async connections, defaulting to UDP. ZeroMQ is over TCP and abstracts async constructs within the socket layer. .sp Salt is not dropping ZeroMQ support and has no immediate plans to do so. .SS Encryption .sp RAET uses Dan Bernstein\(aqs NACL encryption libraries and \fI\%CurveCP\fP handshake. The libnacl python binding binds to both \fI\%libsodium\fP and tweetnacl to execute the underlying cryptography. This allows us to completely rely on an externally developed cryptography system. .SS Programming Intro .SS Intro to RAET Programming .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 This page is still under construction .UNINDENT .UNINDENT .sp The first thing to cover is that RAET does not present a socket api, it presents, and queueing api, all messages in RAET are made available to via queues. This is the single most differentiating factor with RAET vs other networking libraries, instead of making a socket, a stack is created. Instead of calling send() or recv(), messages are placed on the stack to be sent and messages that are received appear on the stack. .sp Different kinds of stacks are also available, currently two stacks exist, the UDP stack, and the UXD stack. The UDP stack is used to communicate over udp sockets, and the UXD stack is used to communicate over Unix Domain Sockets. .sp The UDP stack runs a context for communicating over networks, while the UXD stack has contexts for communicating between processes. .SS UDP Stack Messages .sp To create a UDP stack in RAET, simply create the stack, manage the queues, and process messages: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C from salt.transport.road.raet import stacking from salt.transport.road.raet import estating udp_stack = stacking.StackUdp(ha=(\(aq127.0.0.1\(aq, 7870)) r_estate = estating.Estate(stack=stack, name=\(aqfoo\(aq, ha=(\(aq192.168.42.42\(aq, 7870)) msg = {\(aqhello\(aq: \(aqworld\(aq} udp_stack.transmit(msg, udp_stack.estates[r_estate.name]) udp_stack.serviceAll() .ft P .fi .UNINDENT .UNINDENT .SS 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\&. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C master_tops: varstack: /path/to/the/config/file/varstack.yaml .ft P .fi .UNINDENT .UNINDENT .sp for \fBVarstack\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: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C import logging import sys # Define the module\(aqs virtual name __virtualname__ = \(aqcustomtop\(aq log = logging.getLogger(__name__) def __virtual__(): return __virtualname__ def top(**kwargs): log.debug(\(aqCalling top in customtop\(aq) return {\(aqbase\(aq: [\(aqtest\(aq]} .ft P .fi .UNINDENT .UNINDENT .sp \fIsalt minion state.show_top\fP should then display something like: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C $ salt minion state.show_top minion \-\-\-\-\-\-\-\-\-\- base: \- test .ft P .fi .UNINDENT .UNINDENT .SS Returners .sp By default the return values of the commands sent to the Salt minions are returned to the Salt master, however anything at all can be done with the results data. .sp By using a Salt returner, results data can be redirected to external data\-stores for analysis and archival. .sp Returners pull their configuration values from the Salt minions. Returners are only configured once, which is generally at load time. .sp The returner interface allows the return data to be sent to any system that can receive data. This means that return data can be sent to a Redis server, a MongoDB server, a MySQL server, or any system. .sp \fBSEE ALSO:\fP .INDENT 0.0 .INDENT 3.5 Full list of builtin returners .UNINDENT .UNINDENT .SS Using Returners .sp All Salt commands will return the command data back to the master. Specifying returners will ensure that the data is _also_ sent to the specified returner interfaces. .sp Specifying what returners to use is done when the command is invoked: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq test.ping \-\-return redis_return .ft P .fi .UNINDENT .UNINDENT .sp This command will ensure that the redis_return returner is used. .sp It is also possible to specify multiple returners: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq test.ping \-\-return mongo_return,redis_return,cassandra_return .ft P .fi .UNINDENT .UNINDENT .sp In this scenario all three returners will be called and the data from the test.ping command will be sent out to the three named returners. .SS Writing a Returner .sp A returner is a Python module containing at minimum a \fBreturner\fP function. Other optional functions can be included to add support for master_job_cache, external_job_cache, and \fI\%Event Returners\fP\&. .INDENT 0.0 .TP .B \fBreturner\fP The \fBreturner\fP function must accept a single argument. The argument contains return data from the called minion function. If the minion function \fBtest.ping\fP is called, the value of the argument will be a dictionary. Run the following command from a Salt master to get a sample of the dictionary: .UNINDENT .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt\-call \-\-local \-\-metadata test.ping \-\-out=pprint .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C import redis import json def returner(ret): \(aq\(aq\(aq Return information to a redis server \(aq\(aq\(aq # Get a redis connection serv = redis.Redis( host=\(aqredis\-serv.example.com\(aq, port=6379, db=\(aq0\(aq) serv.sadd("%(id)s:jobs" % ret, ret[\(aqjid\(aq]) serv.set("%(jid)s:%(id)s" % ret, json.dumps(ret[\(aqreturn\(aq])) serv.sadd(\(aqjobs\(aq, ret[\(aqjid\(aq]) serv.sadd(ret[\(aqjid\(aq], ret[\(aqid\(aq]) .ft P .fi .UNINDENT .UNINDENT .sp The above example of a returner set to send the data to a Redis server serializes the data as JSON and sets it in redis. .SS Master Job Cache Support .sp master_job_cache, external_job_cache, and \fI\%Event Returners\fP\&. Salt\(aqs master_job_cache allows returners to be used as a pluggable replacement for the default_job_cache\&. In order to do so, a returner must implement the following functions: .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 The code samples contained in this section were taken from the cassandra_cql returner. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B \fBprep_jid\fP Ensures that job ids (jid) don\(aqt collide, unless passed_jid is provided. .sp \fBnochache\fP is an optional boolean that indicates if return data should be cached. \fBpassed_jid\fP is a caller provided jid which should be returned unconditionally. .UNINDENT .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C def prep_jid(nocache, passed_jid=None): # pylint: disable=unused\-argument \(aq\(aq\(aq Do any work necessary to prepare a JID, including sending a custom id \(aq\(aq\(aq return passed_jid if passed_jid is not None else salt.utils.jid.gen_jid() .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .TP .B \fBsave_load\fP Save job information. The \fBjid\fP is generated by \fBprep_jid\fP and should be considered a unique identifier for the job. The jid, for example, could be used as the primary/unique key in a database. The \fBload\fP is what is returned to a Salt master by a minion. The following code example stores the load as a JSON string in the salt.jids table. .UNINDENT .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C def save_load(jid, load): \(aq\(aq\(aq Save the load to the specified jid id \(aq\(aq\(aq query = \(aq\(aq\(aqINSERT INTO salt.jids ( jid, load ) VALUES ( \(aq{0}\(aq, \(aq{1}\(aq );\(aq\(aq\(aq.format(jid, json.dumps(load)) # cassandra_cql.cql_query may raise a CommandExecutionError try: __salt__[\(aqcassandra_cql.cql_query\(aq](query) except CommandExecutionError: log.critical(\(aqCould not save load in jids table.\(aq) raise except Exception as e: log.critical(\(aq\(aq\(aqUnexpected error while inserting into jids: {0}\(aq\(aq\(aq.format(str(e))) raise .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .TP .B \fBget_load\fP must accept a job id (jid) and return the job load stored by \fBsave_load\fP, or an empty dictionary when not found. .UNINDENT .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C def get_load(jid): \(aq\(aq\(aq Return the load data that marks a specified jid \(aq\(aq\(aq query = \(aq\(aq\(aqSELECT load FROM salt.jids WHERE jid = \(aq{0}\(aq;\(aq\(aq\(aq.format(jid) ret = {} # cassandra_cql.cql_query may raise a CommandExecutionError try: data = __salt__[\(aqcassandra_cql.cql_query\(aq](query) if data: load = data[0].get(\(aqload\(aq) if load: ret = json.loads(load) except CommandExecutionError: log.critical(\(aqCould not get load from jids table.\(aq) raise except Exception as e: log.critical(\(aq\(aq\(aqUnexpected error while getting load from jids: {0}\(aq\(aq\(aq.format(str(e))) raise return ret .ft P .fi .UNINDENT .UNINDENT .SS External Job Cache Support .sp Salt\(aqs external_job_cache extends the master_job_cache\&. External Job Cache support requires the following functions in addition to what is required for Master Job Cache support: .INDENT 0.0 .TP .B \fBget_jid\fP Return a dictionary containing the information (load) returned by each minion when the specified job id was executed. .UNINDENT .sp Sample: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C { "local": { "master_minion": { "fun_args": [], "jid": "20150330121011408195", "return": true, "retcode": 0, "success": true, "cmd": "_return", "_stamp": "2015\-03\-30T12:10:12.708663", "fun": "test.ping", "id": "master_minion" } } } .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .TP .B \fBget_fun\fP Return a dictionary of minions that called a given Salt function as their last function call. .UNINDENT .sp Sample: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C { "local": { "minion1": "test.ping", "minion3": "test.ping", "minion2": "test.ping" } } .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .TP .B \fBget_jids\fP Return a list of all job ids. .UNINDENT .sp Sample: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C { "local": [ "20150330121011408195", "20150330195922139916" ] } .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .TP .B \fBget_minions\fP Returns a list of minions .UNINDENT .sp Sample: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C { "local": [ "minion3", "minion2", "minion1", "master_minion" ] } .ft P .fi .UNINDENT .UNINDENT .sp Please refer to one or more of the existing returners (i.e. mysql, cassandra_cql) if you need further clarification. .SS Event Support .sp An \fBevent_return\fP function must be added to the returner module to allow events to be logged from a master via the returner. A list of events are passed to the function by the master. .sp The following example was taken from the MySQL returner. In this example, each event is inserted into the salt_events table keyed on the event tag. The tag contains the jid and therefore is guaranteed to be unique. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C def event_return(events): \(aq\(aq\(aq Return event to mysql server Requires that configuration be enabled via \(aqevent_return\(aq option in master config. \(aq\(aq\(aq with _get_serv(events, commit=True) as cur: for event in events: tag = event.get(\(aqtag\(aq, \(aq\(aq) data = event.get(\(aqdata\(aq, \(aq\(aq) sql = \(aq\(aq\(aqINSERT INTO \(gasalt_events\(ga (\(gatag\(ga, \(gadata\(ga, \(gamaster_id\(ga ) VALUES (%s, %s, %s)\(aq\(aq\(aq cur.execute(sql, (tag, json.dumps(data), __opts__[\(aqid\(aq])) .ft P .fi .UNINDENT .UNINDENT .SS Custom Returners .sp Place custom returners in a \fB_returners\fP directory within the \fBfile_roots\fP specified by the master config file. .sp Custom returners are distributed when any of the following are called: .INDENT 0.0 .IP \(bu 2 \fBstate.apply\fP .IP \(bu 2 \fBsaltutil.sync_returners\fP .IP \(bu 2 \fBsaltutil.sync_all\fP .UNINDENT .sp Any custom returners which have been synced to a minion that are named the same as one of Salt\(aqs default set of returners will take the place of the default returner with the same name. .SS Naming the Returner .sp Note that a returner\(aqs default name is its filename (i.e. \fBfoo.py\fP becomes returner \fBfoo\fP), but that its name can be overridden by using a __virtual__ function\&. A good example of this can be found in the \fI\%redis\fP returner, which is named \fBredis_return.py\fP but is loaded as simply \fBredis\fP: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C try: import redis HAS_REDIS = True except ImportError: HAS_REDIS = False __virtualname__ = \(aqredis\(aq def __virtual__(): if not HAS_REDIS: return False return __virtualname__ .ft P .fi .UNINDENT .UNINDENT .SS Testing the Returner .sp The \fBreturner\fP, \fBprep_jid\fP, \fBsave_load\fP, \fBget_load\fP, and \fBevent_return\fP functions can be tested by configuring the master_job_cache and \fI\%Event Returners\fP in the master config file and submitting a job to \fBtest.ping\fP each minion from the master. .sp Once you have successfully exercised the Master Job Cache functions, test the External Job Cache functions using the \fBret\fP execution module. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt\-call ret.get_jids cassandra_cql \-\-output=json salt\-call ret.get_fun cassandra_cql test.ping \-\-output=json salt\-call ret.get_minions cassandra_cql \-\-output=json salt\-call ret.get_jid cassandra_cql 20150330121011408195 \-\-output=json .ft P .fi .UNINDENT .UNINDENT .SS Event Returners .sp For maximum visibility into the history of events across a Salt infrastructure, all events seen by a salt master may be logged to one or more returners. .sp To enable event logging, set the \fBevent_return\fP configuration option in the master config to the returner(s) which should be designated as the handler for event returns. .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 Not all returners support event returns. Verify a returner has an \fBevent_return()\fP function before using. .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 On larger installations, many hundreds of events may be generated on a busy master every second. Be certain to closely monitor the storage of a given returner as Salt can easily overwhelm an underpowered server with thousands of returns. .UNINDENT .UNINDENT .SS Full List of Returners .SS returner modules .TS center; |l|l|. _ T{ \fBcarbon_return\fP T} T{ Take data from salt and "return" it into a carbon receiver T} _ T{ \fBcassandra_cql_return\fP T} T{ Return data to a cassandra server T} _ T{ \fBcassandra_return\fP T} T{ Return data to a Cassandra ColumnFamily T} _ T{ \fBcouchbase_return\fP T} T{ Simple returner for Couchbase. T} _ T{ \fBcouchdb_return\fP T} T{ Simple returner for CouchDB. T} _ T{ \fBdjango_return\fP T} T{ A returner that will infor a Django system that returns are available using Django\(aqs signal system. T} _ T{ \fBelasticsearch_return\fP T} T{ Return data to an elasticsearch server for indexing. T} _ T{ \fBetcd_return\fP T} T{ Return data to an etcd server or cluster T} _ T{ \fBhipchat_return\fP T} T{ Return salt data via hipchat. T} _ T{ \fBinfluxdb_return\fP T} T{ Return data to an influxdb server. T} _ T{ \fBkafka_return\fP T} T{ Return data to a Kafka topic T} _ T{ \fBlocal\fP T} T{ The local returner is used to test the returner interface, it just prints the T} _ T{ \fBlocal_cache\fP T} T{ Return data to local job cache T} _ T{ \fBmemcache_return\fP T} T{ Return data to a memcache server T} _ T{ \fBmongo_future_return\fP T} T{ Return data to a mongodb server T} _ T{ \fBmongo_return\fP T} T{ Return data to a mongodb server T} _ T{ \fBmulti_returner\fP T} T{ Read/Write multiple returners T} _ T{ \fBmysql\fP T} T{ Return data to a mysql server T} _ T{ \fBnagios_return\fP T} T{ Return salt data to Nagios T} _ T{ \fBodbc\fP T} T{ Return data to an ODBC compliant server. T} _ T{ \fBpgjsonb\fP T} T{ Return data to a PostgreSQL server with json data stored in Pg\(aqs jsonb data type T} _ T{ \fBpostgres\fP T} T{ Return data to a postgresql server T} _ T{ \fBpostgres_local_cache\fP T} T{ Use a postgresql server for the master job cache. T} _ T{ \fBpushover_returner\fP T} T{ Return salt data via pushover (\fI\%http://www.pushover.net\fP) T} _ T{ \fBrawfile_json\fP T} T{ Take data from salt and "return" it into a raw file containing the json, with one line per event. T} _ T{ \fBredis_return\fP T} T{ Return data to a redis server T} _ T{ \fBsentry_return\fP T} T{ Salt returner that reports execution results back to sentry. T} _ T{ \fBslack_returner\fP T} T{ Return salt data via slack T} _ T{ \fBsms_return\fP T} T{ Return data by SMS. T} _ T{ \fBsmtp_return\fP T} T{ Return salt data via email T} _ T{ \fBsplunk\fP T} T{ Send json response data to Splunk via the HTTP Event Collector T} _ T{ \fBsqlite3_return\fP T} T{ Insert minion return data into a sqlite3 database T} _ T{ \fBsyslog_return\fP T} T{ Return data to the host operating system\(aqs syslog facility T} _ T{ \fBxmpp_return\fP T} T{ Return salt data via xmpp T} _ .TE .SS salt.returners.carbon_return .sp Take data from salt and "return" it into a carbon receiver .sp Add the following configuration to the minion configuration file: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C carbon.host: carbon.port: 2003 .ft P .fi .UNINDENT .UNINDENT .sp Errors when trying to convert data to numbers may be ignored by setting \fBcarbon.skip_on_error\fP to \fITrue\fP: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C carbon.skip_on_error: True .ft P .fi .UNINDENT .UNINDENT .sp By default, data will be sent to carbon using the plaintext protocol. To use the pickle protocol, set \fBcarbon.mode\fP to \fBpickle\fP: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C carbon.mode: pickle .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .TP .B You can also specify the pattern used for the metric base path (except for virt modules metrics): carbon.metric_base_pattern: carbon.[minion_id].[module].[function] .TP .B These tokens can used : [module]: salt module [function]: salt function [minion_id]: minion id .TP .B Default is : carbon.metric_base_pattern: [module].[function].[minion_id] .UNINDENT .sp Carbon settings may also be configured as: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C carbon: host: port: skip_on_error: True mode: (pickle|text) metric_base_pattern: | [module].[function].[minion_id] .ft P .fi .UNINDENT .UNINDENT .sp Alternative configuration values can be used by prefacing the configuration. Any values not found in the alternative configuration will be pulled from the default location: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C alternative.carbon: host: port: skip_on_error: True mode: (pickle|text) .ft P .fi .UNINDENT .UNINDENT .sp To use the carbon returner, append \(aq\-\-return carbon\(aq to the salt command. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq test.ping \-\-return carbon .ft P .fi .UNINDENT .UNINDENT .sp To use the alternative configuration, append \(aq\-\-return_config alternative\(aq to the salt command. .sp New in version 2015.5.0. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq test.ping \-\-return carbon \-\-return_config alternative .ft P .fi .UNINDENT .UNINDENT .sp To override individual configuration items, append \-\-return_kwargs \(aq{"key:": "value"}\(aq to the salt command. .sp New in version 2016.3.0. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq test.ping \-\-return carbon \-\-return_kwargs \(aq{"skip_on_error": False}\(aq .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.returners.carbon_return.event_return(events) Return event data to remote carbon server .sp Provide a list of events to be stored in carbon .UNINDENT .INDENT 0.0 .TP .B salt.returners.carbon_return.prep_jid(nocache=False, passed_jid=None) Do any work necessary to prepare a JID, including sending a custom id .UNINDENT .INDENT 0.0 .TP .B salt.returners.carbon_return.returner(ret) Return data to a remote carbon server using the text metric protocol .sp Each metric will look like: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C [module].[function].[minion_id].[metric path [...]].[metric name] .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.returners.cassandra_cql_return .sp Return data to a cassandra server .sp New in version 2015.5.0. .INDENT 0.0 .TP .B maintainer Corin Kochenower<\fI\%ckochenower@saltstack.com\fP> .TP .B maturity new as of 2015.2 .TP .B depends salt.modules.cassandra_cql .TP .B depends DataStax Python Driver for Apache Cassandra \fI\%https://github.com/datastax/python\-driver\fP pip install cassandra\-driver .TP .B platform all .TP .B configuration To enable this returner, the minion will need the DataStax Python Driver for Apache Cassandra ( \fI\%https://github.com/datastax/python\-driver\fP ) installed and the following values configured in the minion or master config. The list of cluster IPs must include at least one cassandra node IP address. No assumption or default will be used for the cluster IPs. The cluster IPs will be tried in the order listed. The port, username, and password values shown below will be the assumed defaults if you do not provide values.: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C cassandra: cluster: \- 192.168.50.11 \- 192.168.50.12 \- 192.168.50.13 port: 9042 username: salt password: salt .ft P .fi .UNINDENT .UNINDENT .sp Use the following cassandra database schema: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C CREATE KEYSPACE IF NOT EXISTS salt WITH replication = {\(aqclass\(aq: \(aqSimpleStrategy\(aq, \(aqreplication_factor\(aq : 1}; CREATE USER IF NOT EXISTS salt WITH PASSWORD \(aqsalt\(aq NOSUPERUSER; GRANT ALL ON KEYSPACE salt TO salt; USE salt; CREATE TABLE IF NOT EXISTS salt.salt_returns ( jid text, minion_id text, fun text, alter_time timestamp, full_ret text, return text, success boolean, PRIMARY KEY (jid, minion_id, fun) ) WITH CLUSTERING ORDER BY (minion_id ASC, fun ASC); CREATE INDEX IF NOT EXISTS salt_returns_minion_id ON salt.salt_returns (minion_id); CREATE INDEX IF NOT EXISTS salt_returns_fun ON salt.salt_returns (fun); CREATE TABLE IF NOT EXISTS salt.jids ( jid text PRIMARY KEY, load text ); CREATE TABLE IF NOT EXISTS salt.minions ( minion_id text PRIMARY KEY, last_fun text ); CREATE INDEX IF NOT EXISTS minions_last_fun ON salt.minions (last_fun); CREATE TABLE IF NOT EXISTS salt.salt_events ( id timeuuid, tag text, alter_time timestamp, data text, master_id text, PRIMARY KEY (id, tag) ) WITH CLUSTERING ORDER BY (tag ASC); CREATE INDEX tag ON salt.salt_events (tag); .ft P .fi .UNINDENT .UNINDENT .UNINDENT .sp Required python modules: cassandra\-driver .sp To use the cassandra returner, append \(aq\-\-return cassandra_cql\(aq to the salt command. ex: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq test.ping \-\-return_cql cassandra .ft P .fi .UNINDENT .UNINDENT .sp Note: if your Cassandra instance has not been tuned much you may benefit from altering some timeouts in \fIcassandra.yaml\fP like so: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C # How long the coordinator should wait for read operations to complete read_request_timeout_in_ms: 5000 # How long the coordinator should wait for seq or index scans to complete range_request_timeout_in_ms: 20000 # How long the coordinator should wait for writes to complete write_request_timeout_in_ms: 20000 # How long the coordinator should wait for counter writes to complete counter_write_request_timeout_in_ms: 10000 # How long a coordinator should continue to retry a CAS operation # that contends with other proposals for the same row cas_contention_timeout_in_ms: 5000 # How long the coordinator should wait for truncates to complete # (This can be much longer, because unless auto_snapshot is disabled # we need to flush first so we can snapshot before removing the data.) truncate_request_timeout_in_ms: 60000 # The default timeout for other, miscellaneous operations request_timeout_in_ms: 20000 .ft P .fi .UNINDENT .UNINDENT .sp As always, your mileage may vary and your Cassandra cluster may have different needs. SaltStack has seen situations where these timeouts can resolve some stacktraces that appear to come from the Datastax Python driver. .INDENT 0.0 .TP .B salt.returners.cassandra_cql_return.event_return(events) Return event to one of potentially many clustered cassandra nodes .sp Requires that configuration be enabled via \(aqevent_return\(aq option in master config. .sp Cassandra does not support an auto\-increment feature due to the highly inefficient nature of creating a monotonically increasing number across all nodes in a distributed database. Each event will be assigned a uuid by the connecting client. .UNINDENT .INDENT 0.0 .TP .B salt.returners.cassandra_cql_return.get_fun(fun) Return a dict of the last function called for all minions .UNINDENT .INDENT 0.0 .TP .B salt.returners.cassandra_cql_return.get_jid(jid) Return the information returned when the specified job id was executed .UNINDENT .INDENT 0.0 .TP .B salt.returners.cassandra_cql_return.get_jids() Return a list of all job ids .UNINDENT .INDENT 0.0 .TP .B salt.returners.cassandra_cql_return.get_load(jid) Return the load data that marks a specified jid .UNINDENT .INDENT 0.0 .TP .B salt.returners.cassandra_cql_return.get_minions() Return a list of minions .UNINDENT .INDENT 0.0 .TP .B salt.returners.cassandra_cql_return.prep_jid(nocache, passed_jid=None) Do any work necessary to prepare a JID, including sending a custom id .UNINDENT .INDENT 0.0 .TP .B salt.returners.cassandra_cql_return.returner(ret) Return data to one of potentially many clustered cassandra nodes .UNINDENT .INDENT 0.0 .TP .B salt.returners.cassandra_cql_return.save_load(jid, load, minions=None) Save the load to the specified jid id .UNINDENT .SS salt.returners.cassandra_return .sp Return data to a Cassandra ColumnFamily .sp Here\(aqs an example Keyspace / ColumnFamily setup that works with this returner: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C create keyspace salt; use salt; create column family returns with key_validation_class=\(aqUTF8Type\(aq and comparator=\(aqUTF8Type\(aq and default_validation_class=\(aqUTF8Type\(aq; .ft P .fi .UNINDENT .UNINDENT .sp Required python modules: pycassa .INDENT 0.0 .INDENT 3.5 To use the cassandra returner, append \(aq\-\-return cassandra\(aq to the salt command. ex: .INDENT 0.0 .INDENT 3.5 salt \(aq*\(aq test.ping \-\-return cassandra .UNINDENT .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.returners.cassandra_return.prep_jid(nocache=False, passed_jid=None) Do any work necessary to prepare a JID, including sending a custom id .UNINDENT .INDENT 0.0 .TP .B salt.returners.cassandra_return.returner(ret) Return data to a Cassandra ColumnFamily .UNINDENT .SS salt.returners.couchbase_return .sp Simple returner for Couchbase. Optional configuration settings are listed below, along with sane defaults. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C couchbase.host: \(aqsalt\(aq couchbase.port: 8091 couchbase.bucket: \(aqsalt\(aq couchbase.ttl: 24 couchbase.password: \(aqpassword\(aq couchbase.skip_verify_views: False .ft P .fi .UNINDENT .UNINDENT .sp To use the couchbase returner, append \(aq\-\-return couchbase\(aq to the salt command. ex: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq test.ping \-\-return couchbase .ft P .fi .UNINDENT .UNINDENT .sp To use the alternative configuration, append \(aq\-\-return_config alternative\(aq to the salt command. .sp New in version 2015.5.0. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq test.ping \-\-return couchbase \-\-return_config alternative .ft P .fi .UNINDENT .UNINDENT .sp To override individual configuration items, append \-\-return_kwargs \(aq{"key:": "value"}\(aq to the salt command. .sp New in version 2016.3.0. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq test.ping \-\-return couchbase \-\-return_kwargs \(aq{"bucket": "another\-salt"}\(aq .ft P .fi .UNINDENT .UNINDENT .sp All of the return data will be stored in documents as follows: .SS JID .sp load: load obj tgt_minions: list of minions targeted nocache: should we not cache the return data .SS JID/MINION_ID .sp return: return_data full_ret: full load of job return .INDENT 0.0 .TP .B salt.returners.couchbase_return.get_jid(jid) Return the information returned when the specified job id was executed .UNINDENT .INDENT 0.0 .TP .B salt.returners.couchbase_return.get_jids() Return a list of all job ids .UNINDENT .INDENT 0.0 .TP .B salt.returners.couchbase_return.get_load(jid) Return the load data that marks a specified jid .UNINDENT .INDENT 0.0 .TP .B salt.returners.couchbase_return.prep_jid(nocache=False, passed_jid=None) Return a job id and prepare the job id directory This is the function responsible for making sure jids don\(aqt collide (unless its passed a jid) So do what you have to do to make sure that stays the case .UNINDENT .INDENT 0.0 .TP .B salt.returners.couchbase_return.returner(load) Return data to couchbase bucket .UNINDENT .INDENT 0.0 .TP .B salt.returners.couchbase_return.save_load(jid, clear_load, minion=None) Save the load to the specified jid .UNINDENT .INDENT 0.0 .TP .B salt.returners.couchbase_return.save_minions(jid, minions, syndic_id=None) Save/update the minion list for a given jid. The syndic_id argument is included for API compatibility only. .UNINDENT .SS salt.returners.couchdb_return .sp Simple returner for CouchDB. Optional configuration settings are listed below, along with sane defaults: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C couchdb.db: \(aqsalt\(aq couchdb.url: \(aqhttp://salt:5984/\(aq .ft P .fi .UNINDENT .UNINDENT .sp Alternative configuration values can be used by prefacing the configuration. Any values not found in the alternative configuration will be pulled from the default location: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C alternative.couchdb.db: \(aqsalt\(aq alternative.couchdb.url: \(aqhttp://salt:5984/\(aq .ft P .fi .UNINDENT .UNINDENT .sp To use the couchdb returner, append \fB\-\-return couchdb\fP to the salt command. Example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq test.ping \-\-return couchdb .ft P .fi .UNINDENT .UNINDENT .sp To use the alternative configuration, append \fB\-\-return_config alternative\fP to the salt command. .sp New in version 2015.5.0. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq test.ping \-\-return couchdb \-\-return_config alternative .ft P .fi .UNINDENT .UNINDENT .sp To override individual configuration items, append \-\-return_kwargs \(aq{"key:": "value"}\(aq to the salt command. .sp New in version 2016.3.0. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq test.ping \-\-return couchdb \-\-return_kwargs \(aq{"db": "another\-salt"}\(aq .ft P .fi .UNINDENT .UNINDENT .SS On concurrent database access .sp As this returner creates a couchdb document with the salt job id as document id and as only one document with a given id can exist in a given couchdb database, it is advised for most setups that every minion be configured to write to it own database (the value of \fBcouchdb.db\fP may be suffixed with the minion id), otherwise multi\-minion targeting can lead to losing output: .INDENT 0.0 .IP \(bu 2 the first returning minion is able to create a document in the database .IP \(bu 2 other minions fail with \fB{\(aqerror\(aq: \(aqHTTP Error 409: Conflict\(aq}\fP .UNINDENT .INDENT 0.0 .TP .B salt.returners.couchdb_return.ensure_views() This function makes sure that all the views that should exist in the design document do exist. .UNINDENT .INDENT 0.0 .TP .B salt.returners.couchdb_return.get_fun(fun) Return a dict with key being minion and value being the job details of the last run of function \(aqfun\(aq. .UNINDENT .INDENT 0.0 .TP .B salt.returners.couchdb_return.get_jid(jid) Get the document with a given JID. .UNINDENT .INDENT 0.0 .TP .B salt.returners.couchdb_return.get_jids() List all the jobs that we have.. .UNINDENT .INDENT 0.0 .TP .B salt.returners.couchdb_return.get_minions() Return a list of minion identifiers from a request of the view. .UNINDENT .INDENT 0.0 .TP .B salt.returners.couchdb_return.get_valid_salt_views() Returns a dict object of views that should be part of the salt design document. .UNINDENT .INDENT 0.0 .TP .B salt.returners.couchdb_return.prep_jid(nocache=False, passed_jid=None) Do any work necessary to prepare a JID, including sending a custom id .UNINDENT .INDENT 0.0 .TP .B salt.returners.couchdb_return.returner(ret) Take in the return and shove it into the couchdb database. .UNINDENT .INDENT 0.0 .TP .B salt.returners.couchdb_return.set_salt_view() Helper function that sets the salt design document. Uses get_valid_salt_views and some hardcoded values. .UNINDENT .SS salt.returners.django_return .sp A returner that will infor a Django system that returns are available using Django\(aqs signal system. .sp \fI\%https://docs.djangoproject.com/en/dev/topics/signals/\fP .sp It is up to the Django developer to register necessary handlers with the signals provided by this returner and process returns as necessary. .sp The easiest way to use signals is to import them from this returner directly and then use a decorator to register them. .sp An example Django module that registers a function called \(aqreturner_callback\(aq with this module\(aqs \(aqreturner\(aq function: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C import salt.returners.django_return from django.dispatch import receiver @receiver(salt.returners.django_return, sender=returner) def returner_callback(sender, ret): print(\(aqI received {0} from {1}\(aq.format(ret, sender)) .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.returners.django_return.prep_jid(nocache=False, passed_jid=None) Do any work necessary to prepare a JID, including sending a custom ID .UNINDENT .INDENT 0.0 .TP .B salt.returners.django_return.returner(ret) Signal a Django server that a return is available .UNINDENT .INDENT 0.0 .TP .B salt.returners.django_return.save_load(jid, load, minions=None) Save the load to the specified jid .UNINDENT .SS salt.returners.elasticsearch_return .sp Return data to an elasticsearch server for indexing. .INDENT 0.0 .TP .B maintainer Jurnell Cockhren <\fI\%jurnell.cockhren@sophicware.com\fP>, Arnold Bechtoldt <\fI\%mail@arnoldbechtoldt.com\fP> .TP .B maturity New .TP .B depends \fI\%elasticsearch\-py\fP .TP .B platform all .UNINDENT .sp To enable this returner the elasticsearch python client must be installed on the desired minions (all or some subset). .sp Please see documentation of \fBelasticsearch execution module\fP for a valid connection configuration. .sp \fBWARNING:\fP .INDENT 0.0 .INDENT 3.5 The index that you wish to store documents will be created by Elasticsearch automatically if doesn\(aqt exist yet. It is highly recommended to create predefined index templates with appropriate mapping(s) that will be used by Elasticsearch upon index creation. Otherwise you will have problems as described in #20826. .UNINDENT .UNINDENT .sp To use the returner per salt call: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq test.ping \-\-return elasticsearch .ft P .fi .UNINDENT .UNINDENT .sp In order to have the returner apply to all minions: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C ext_job_cache: elasticsearch .ft P .fi .UNINDENT .UNINDENT .sp Minion configuration example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C elasticsearch: hosts: \- "10.10.10.10:9200" \- "10.10.10.11:9200" \- "10.10.10.12:9200" index_date: True number_of_shards: 5 number_of_replicas: 1 functions_blacklist: \- "test.ping" .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.returners.elasticsearch_return.event_return(events) Return events to Elasticsearch .sp Requires that the \fIevent_return\fP configuration be set in master config. .UNINDENT .INDENT 0.0 .TP .B salt.returners.elasticsearch_return.get_load(jid) Return the load data that marks a specified jid .sp New in version 2015.8.1. .UNINDENT .INDENT 0.0 .TP .B salt.returners.elasticsearch_return.prep_jid(nocache=False, passed_jid=None) Do any work necessary to prepare a JID, including sending a custom id .UNINDENT .INDENT 0.0 .TP .B salt.returners.elasticsearch_return.returner(ret) Process the return from Salt .UNINDENT .INDENT 0.0 .TP .B salt.returners.elasticsearch_return.save_load(jid, load, minions=None) Save the load to the specified jid id .sp New in version 2015.8.1. .UNINDENT .SS salt.returners.etcd_return .sp Return data to an etcd server or cluster .INDENT 0.0 .TP .B depends .INDENT 7.0 .IP \(bu 2 python\-etcd .UNINDENT .UNINDENT .sp In order to return to an etcd server, a profile should be created in the master configuration file: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C my_etcd_config: etcd.host: 127.0.0.1 etcd.port: 4001 .ft P .fi .UNINDENT .UNINDENT .sp It is technically possible to configure etcd without using a profile, but this is not considered to be a best practice, especially when multiple etcd servers or clusters are available. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C etcd.host: 127.0.0.1 etcd.port: 4001 .ft P .fi .UNINDENT .UNINDENT .sp Additionally, two more options must be specified in the top\-level configuration in order to use the etcd returner: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C etcd.returner: my_etcd_config etcd.returner_root: /salt/return .ft P .fi .UNINDENT .UNINDENT .sp The \fBetcd.returner\fP option specifies which configuration profile to use. The \fBetcd.returner_root\fP option specifies the path inside etcd to use as the root of the returner system. .sp Once the etcd options are configured, the returner may be used: .sp CLI Example: .INDENT 0.0 .INDENT 3.5 salt \(aq*\(aq test.ping \-\-return etcd .UNINDENT .UNINDENT .sp A username and password can be set: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C etcd.username: larry # Optional; requires etcd.password to be set etcd.password: 123pass # Optional; requires etcd.username to be set .ft P .fi .UNINDENT .UNINDENT .sp You can also set a TTL (time to live) value for the returner: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C etcd.ttl: 5 .ft P .fi .UNINDENT .UNINDENT .sp Authentication with username and password, and ttl, currently requires the \fBmaster\fP branch of \fBpython\-etcd\fP\&. .sp You may also specify different roles for read and write operations. First, create the profiles as specified above. Then add: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C etcd.returner_read_profile: my_etcd_read etcd.returner_write_profile: my_etcd_write .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.returners.etcd_return.get_fun() Return a dict of the last function called for all minions .UNINDENT .INDENT 0.0 .TP .B salt.returners.etcd_return.get_jid(jid) Return the information returned when the specified job id was executed .UNINDENT .INDENT 0.0 .TP .B salt.returners.etcd_return.get_jids() Return a list of all job ids .UNINDENT .INDENT 0.0 .TP .B salt.returners.etcd_return.get_load(jid) Return the load data that marks a specified jid .UNINDENT .INDENT 0.0 .TP .B salt.returners.etcd_return.get_minions() Return a list of minions .UNINDENT .INDENT 0.0 .TP .B salt.returners.etcd_return.prep_jid(nocache=False, passed_jid=None) Do any work necessary to prepare a JID, including sending a custom id .UNINDENT .INDENT 0.0 .TP .B salt.returners.etcd_return.returner(ret) Return data to an etcd server or cluster .UNINDENT .INDENT 0.0 .TP .B salt.returners.etcd_return.save_load(jid, load, minions=None) Save the load to the specified jid .UNINDENT .SS salt.returners.hipchat_return .sp Return salt data via hipchat. .sp New in version 2015.5.0. .sp The following fields can be set in the minion conf file: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C hipchat.room_id (required) hipchat.api_key (required) hipchat.api_version (required) hipchat.api_url (optional) hipchat.from_name (required) hipchat.color (optional) hipchat.notify (optional) hipchat.profile (optional) hipchat.url (optional) .ft P .fi .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 When using Hipchat\(aqs API v2, \fBapi_key\fP needs to be assigned to the room with the "Label" set to what you would have been set in the hipchat.from_name field. The v2 API disregards the \fBfrom_name\fP in the data sent for the room notification and uses the Label assigned through the Hipchat control panel. .UNINDENT .UNINDENT .sp Alternative configuration values can be used by prefacing the configuration. Any values not found in the alternative configuration will be pulled from the default location: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C hipchat.room_id hipchat.api_key hipchat.api_version hipchat.api_url hipchat.from_name .ft P .fi .UNINDENT .UNINDENT .sp Hipchat settings may also be configured as: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C hipchat: room_id: RoomName api_url: https://hipchat.myteam.con api_key: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx api_version: v1 from_name: user@email.com alternative.hipchat: room_id: RoomName api_key: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx api_version: v1 from_name: user@email.com hipchat_profile: hipchat.api_key: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx hipchat.api_version: v1 hipchat.from_name: user@email.com hipchat: profile: hipchat_profile room_id: RoomName alternative.hipchat: profile: hipchat_profile room_id: RoomName hipchat: room_id: RoomName api_key: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx api_version: v1 api_url: api.hipchat.com from_name: user@email.com .ft P .fi .UNINDENT .UNINDENT .sp To use the HipChat returner, append \(aq\-\-return hipchat\(aq to the salt command. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq test.ping \-\-return hipchat .ft P .fi .UNINDENT .UNINDENT .sp To use the alternative configuration, append \(aq\-\-return_config alternative\(aq to the salt command. .sp New in version 2015.5.0. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq test.ping \-\-return hipchat \-\-return_config alternative .ft P .fi .UNINDENT .UNINDENT .sp To override individual configuration items, append \-\-return_kwargs \(aq{"key:": "value"}\(aq to the salt command. .sp New in version 2016.3.0. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq test.ping \-\-return hipchat \-\-return_kwargs \(aq{"room_id": "another\-room"}\(aq .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.returners.hipchat_return.event_return(events) Return event data to hipchat .UNINDENT .INDENT 0.0 .TP .B salt.returners.hipchat_return.returner(ret) Send an hipchat message with the return data from a job .UNINDENT .SS salt.returners.influxdb_return .sp Return data to an influxdb server. .sp New in version 2015.8.0. .sp To enable this returner the minion will need the python client for influxdb installed and the following values configured in the minion or master config, these are the defaults: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C influxdb.db: \(aqsalt\(aq influxdb.user: \(aqsalt\(aq influxdb.password: \(aqsalt\(aq influxdb.host: \(aqlocalhost\(aq influxdb.port: 8086 .ft P .fi .UNINDENT .UNINDENT .sp Alternative configuration values can be used by prefacing the configuration. Any values not found in the alternative configuration will be pulled from the default location: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C alternative.influxdb.db: \(aqsalt\(aq alternative.influxdb.user: \(aqsalt\(aq alternative.influxdb.password: \(aqsalt\(aq alternative.influxdb.host: \(aqlocalhost\(aq alternative.influxdb.port: 6379 .ft P .fi .UNINDENT .UNINDENT .sp To use the influxdb returner, append \(aq\-\-return influxdb\(aq to the salt command. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq test.ping \-\-return influxdb .ft P .fi .UNINDENT .UNINDENT .sp To use the alternative configuration, append \(aq\-\-return_config alternative\(aq to the salt command. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq test.ping \-\-return influxdb \-\-return_config alternative .ft P .fi .UNINDENT .UNINDENT .sp To override individual configuration items, append \-\-return_kwargs \(aq{"key:": "value"}\(aq to the salt command. .sp New in version 2016.3.0. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq test.ping \-\-return influxdb \-\-return_kwargs \(aq{"db": "another\-salt"}\(aq .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.returners.influxdb_return.get_fun(fun) Return a dict of the last function called for all minions .UNINDENT .INDENT 0.0 .TP .B salt.returners.influxdb_return.get_jid(jid) Return the information returned when the specified job id was executed .UNINDENT .INDENT 0.0 .TP .B salt.returners.influxdb_return.get_jids() Return a list of all job ids .UNINDENT .INDENT 0.0 .TP .B salt.returners.influxdb_return.get_load(jid) Return the load data that marks a specified jid .UNINDENT .INDENT 0.0 .TP .B salt.returners.influxdb_return.get_minions() Return a list of minions .UNINDENT .INDENT 0.0 .TP .B salt.returners.influxdb_return.prep_jid(nocache=False, passed_jid=None) Do any work necessary to prepare a JID, including sending a custom id .UNINDENT .INDENT 0.0 .TP .B salt.returners.influxdb_return.returner(ret) Return data to a influxdb data store .UNINDENT .INDENT 0.0 .TP .B salt.returners.influxdb_return.save_load(jid, load, minions=None) Save the load to the specified jid .UNINDENT .SS salt.returners.kafka_return .sp Return data to a Kafka topic .INDENT 0.0 .TP .B maintainer Christer Edwards (\fI\%christer.edwards@gmail.com\fP) .TP .B maturity 0.1 .TP .B depends kafka\-python .TP .B platform all .UNINDENT .sp To enable this returner install kafka\-python and enable the following settings in the minion config: .INDENT 0.0 .INDENT 3.5 .INDENT 0.0 .TP .B returner.kafka.hostnames: .INDENT 7.0 .IP \(bu 2 "server1" .IP \(bu 2 "server2" .IP \(bu 2 "server3" .UNINDENT .UNINDENT .sp returner.kafka.topic: \(aqtopic\(aq .UNINDENT .UNINDENT .sp To use the kafka returner, append \(aq\-\-return kafka\(aq to the Salt command, eg; .INDENT 0.0 .INDENT 3.5 salt \(aq*\(aq test.ping \-\-return kafka .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.returners.kafka_return.returner(ret) Return information to a Kafka server .UNINDENT .SS salt.returners.local .sp The local returner is used to test the returner interface, it just prints the return data to the console to verify that it is being passed properly .INDENT 0.0 .INDENT 3.5 To use the local returner, append \(aq\-\-return local\(aq to the salt command. ex: .INDENT 0.0 .INDENT 3.5 salt \(aq*\(aq test.ping \-\-return local .UNINDENT .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.returners.local.event_return(event) Print event return data to the terminal to verify functionality .UNINDENT .INDENT 0.0 .TP .B salt.returners.local.returner(ret) Print the return data to the terminal to verify functionality .UNINDENT .SS salt.returners.local_cache .sp Return data to local job cache .INDENT 0.0 .TP .B salt.returners.local_cache.clean_old_jobs() Clean out the old jobs from the job cache .UNINDENT .INDENT 0.0 .TP .B salt.returners.local_cache.get_endtime(jid) Retrieve the stored endtime for a given job .sp Returns False if no endtime is present .UNINDENT .INDENT 0.0 .TP .B salt.returners.local_cache.get_jid(jid) Return the information returned when the specified job id was executed .UNINDENT .INDENT 0.0 .TP .B salt.returners.local_cache.get_jids() Return a dict mapping all job ids to job information .UNINDENT .INDENT 0.0 .TP .B salt.returners.local_cache.get_jids_filter(count, filter_find_job=True) Return a list of all jobs information filtered by the given criteria. :param int count: show not more than the count of most recent jobs :param bool filter_find_jobs: filter out \(aqsaltutil.find_job\(aq jobs .UNINDENT .INDENT 0.0 .TP .B salt.returners.local_cache.get_load(jid) Return the load data that marks a specified jid .UNINDENT .INDENT 0.0 .TP .B salt.returners.local_cache.load_reg() Load the register from msgpack files .UNINDENT .INDENT 0.0 .TP .B salt.returners.local_cache.prep_jid(nocache=False, passed_jid=None, recurse_count=0) Return a job id and prepare the job id directory. .sp This is the function responsible for making sure jids don\(aqt collide (unless it is passed a jid). So do what you have to do to make sure that stays the case .UNINDENT .INDENT 0.0 .TP .B salt.returners.local_cache.returner(load) Return data to the local job cache .UNINDENT .INDENT 0.0 .TP .B salt.returners.local_cache.save_load(jid, clear_load, minions=None, recurse_count=0) Save the load to the specified jid .sp minions argument is to provide a pre\-computed list of matched minions for the job, for cases when this function can\(aqt compute that list itself (such as for salt\-ssh) .UNINDENT .INDENT 0.0 .TP .B salt.returners.local_cache.save_minions(jid, minions, syndic_id=None) Save/update the serialized list of minions for a given job .UNINDENT .INDENT 0.0 .TP .B salt.returners.local_cache.save_reg(data) Save the register to msgpack files .UNINDENT .INDENT 0.0 .TP .B salt.returners.local_cache.update_endtime(jid, time) Update (or store) the end time for a given job .sp Endtime is stored as a plain text string .UNINDENT .SS salt.returners.memcache_return .sp Return data to a memcache server .sp To enable this returner the minion will need the python client for memcache installed and the following values configured in the minion or master config, these are the defaults. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C memcache.host: \(aqlocalhost\(aq memcache.port: \(aq11211\(aq .ft P .fi .UNINDENT .UNINDENT .sp Alternative configuration values can be used by prefacing the configuration. Any values not found in the alternative configuration will be pulled from the default location. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C alternative.memcache.host: \(aqlocalhost\(aq alternative.memcache.port: \(aq11211\(aq .ft P .fi .UNINDENT .UNINDENT .sp python2\-memcache uses \(aqlocalhost\(aq and \(aq11211\(aq as syntax on connection. .sp To use the memcache returner, append \(aq\-\-return memcache\(aq to the salt command. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq test.ping \-\-return memcache .ft P .fi .UNINDENT .UNINDENT .sp To use the alternative configuration, append \(aq\-\-return_config alternative\(aq to the salt command. .sp New in version 2015.5.0. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq test.ping \-\-return memcache \-\-return_config alternative .ft P .fi .UNINDENT .UNINDENT .sp To override individual configuration items, append \-\-return_kwargs \(aq{"key:": "value"}\(aq to the salt command. .sp New in version 2016.3.0. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq test.ping \-\-return memcache \-\-return_kwargs \(aq{"host": "hostname.domain.com"}\(aq .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.returners.memcache_return.get_fun(fun) Return a dict of the last function called for all minions .UNINDENT .INDENT 0.0 .TP .B salt.returners.memcache_return.get_jid(jid) Return the information returned when the specified job id was executed .UNINDENT .INDENT 0.0 .TP .B salt.returners.memcache_return.get_jids() Return a list of all job ids .UNINDENT .INDENT 0.0 .TP .B salt.returners.memcache_return.get_load(jid) Return the load data that marks a specified jid .UNINDENT .INDENT 0.0 .TP .B salt.returners.memcache_return.get_minions() Return a list of minions .UNINDENT .INDENT 0.0 .TP .B salt.returners.memcache_return.prep_jid(nocache=False, passed_jid=None) Do any work necessary to prepare a JID, including sending a custom id .UNINDENT .INDENT 0.0 .TP .B salt.returners.memcache_return.returner(ret) Return data to a memcache data store .UNINDENT .INDENT 0.0 .TP .B salt.returners.memcache_return.save_load(jid, load, minions=None) Save the load to the specified jid .UNINDENT .SS salt.returners.mongo_future_return .sp Return data to a mongodb server .sp Required python modules: pymongo .sp This returner will send data from the minions to a MongoDB server. To configure the settings for your MongoDB server, add the following lines to the minion config files: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C mongo.db: mongo.host: mongo.user: mongo.password: mongo.port: 27017 .ft P .fi .UNINDENT .UNINDENT .sp You can also ask for indexes creation on the most common used fields, which should greatly improve performance. Indexes are not created by default. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C mongo.indexes: true .ft P .fi .UNINDENT .UNINDENT .sp Alternative configuration values can be used by prefacing the configuration. Any values not found in the alternative configuration will be pulled from the default location: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C alternative.mongo.db: alternative.mongo.host: alternative.mongo.user: alternative.mongo.password: alternative.mongo.port: 27017 .ft P .fi .UNINDENT .UNINDENT .sp This mongo returner is being developed to replace the default mongodb returner in the future and should not be considered API stable yet. .sp To use the mongo returner, append \(aq\-\-return mongo\(aq to the salt command. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq test.ping \-\-return mongo .ft P .fi .UNINDENT .UNINDENT .sp To use the alternative configuration, append \(aq\-\-return_config alternative\(aq to the salt command. .sp New in version 2015.5.0. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq test.ping \-\-return mongo \-\-return_config alternative .ft P .fi .UNINDENT .UNINDENT .sp To override individual configuration items, append \-\-return_kwargs \(aq{"key:": "value"}\(aq to the salt command. .sp New in version 2016.3.0. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq test.ping \-\-return mongo \-\-return_kwargs \(aq{"db": "another\-salt"}\(aq .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.returners.mongo_future_return.event_return(events) Return events to Mongodb server .UNINDENT .INDENT 0.0 .TP .B salt.returners.mongo_future_return.get_fun(fun) Return the most recent jobs that have executed the named function .UNINDENT .INDENT 0.0 .TP .B salt.returners.mongo_future_return.get_jid(jid) Return the return information associated with a jid .UNINDENT .INDENT 0.0 .TP .B salt.returners.mongo_future_return.get_jids() Return a list of job ids .UNINDENT .INDENT 0.0 .TP .B salt.returners.mongo_future_return.get_load(jid) Return the load associated with a given job id .UNINDENT .INDENT 0.0 .TP .B salt.returners.mongo_future_return.get_minions() Return a list of minions .UNINDENT .INDENT 0.0 .TP .B salt.returners.mongo_future_return.prep_jid(nocache=False, passed_jid=None) Do any work necessary to prepare a JID, including sending a custom id .UNINDENT .INDENT 0.0 .TP .B salt.returners.mongo_future_return.returner(ret) Return data to a mongodb server .UNINDENT .INDENT 0.0 .TP .B salt.returners.mongo_future_return.save_load(jid, load, minions=None) Save the load for a given job id .UNINDENT .SS salt.returners.mongo_return .sp Return data to a mongodb server .sp Required python modules: pymongo .sp This returner will send data from the minions to a MongoDB server. To configure the settings for your MongoDB server, add the following lines to the minion config files. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C mongo.db: mongo.host: mongo.user: mongo.password: mongo.port: 27017 .ft P .fi .UNINDENT .UNINDENT .sp Alternative configuration values can be used by prefacing the configuration. Any values not found in the alternative configuration will be pulled from the default location. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C alternative.mongo.db: alternative.mongo.host: alternative.mongo.user: alternative.mongo.password: alternative.mongo.port: 27017 .ft P .fi .UNINDENT .UNINDENT .sp To use the mongo returner, append \(aq\-\-return mongo\(aq to the salt command. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq test.ping \-\-return mongo_return .ft P .fi .UNINDENT .UNINDENT .sp To use the alternative configuration, append \(aq\-\-return_config alternative\(aq to the salt command. .sp New in version 2015.5.0. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq test.ping \-\-return mongo_return \-\-return_config alternative .ft P .fi .UNINDENT .UNINDENT .sp To override individual configuration items, append \-\-return_kwargs \(aq{"key:": "value"}\(aq to the salt command. .sp New in version 2016.3.0. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq test.ping \-\-return mongo \-\-return_kwargs \(aq{"db": "another\-salt"}\(aq .ft P .fi .UNINDENT .UNINDENT .sp To override individual configuration items, append \-\-return_kwargs \(aq{"key:": "value"}\(aq to the salt command. .sp New in version 2016.3.0. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq test.ping \-\-return mongo \-\-return_kwargs \(aq{"db": "another\-salt"}\(aq .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.returners.mongo_return.get_fun(fun) Return the most recent jobs that have executed the named function .UNINDENT .INDENT 0.0 .TP .B salt.returners.mongo_return.get_jid(jid) Return the return information associated with a jid .UNINDENT .INDENT 0.0 .TP .B salt.returners.mongo_return.prep_jid(nocache=False, passed_jid=None) Do any work necessary to prepare a JID, including sending a custom id .UNINDENT .INDENT 0.0 .TP .B salt.returners.mongo_return.returner(ret) Return data to a mongodb server .UNINDENT .SS salt.returners.multi_returner .sp Read/Write multiple returners .INDENT 0.0 .TP .B salt.returners.multi_returner.clean_old_jobs() Clean out the old jobs from all returners (if you have it) .UNINDENT .INDENT 0.0 .TP .B salt.returners.multi_returner.get_jid(jid) Merge the return data from all returners .UNINDENT .INDENT 0.0 .TP .B salt.returners.multi_returner.get_jids() Return all job data from all returners .UNINDENT .INDENT 0.0 .TP .B salt.returners.multi_returner.get_load(jid) Merge the load data from all returners .UNINDENT .INDENT 0.0 .TP .B salt.returners.multi_returner.prep_jid(nocache=False, passed_jid=None) Call both with prep_jid on all returners in multi_returner .sp TODO: finish this, what do do when you get different jids from 2 returners... since our jids are time based, this make this problem hard, because they aren\(aqt unique, meaning that we have to make sure that no one else got the jid and if they did we spin to get a new one, which means "locking" the jid in 2 returners is non\-trivial .UNINDENT .INDENT 0.0 .TP .B salt.returners.multi_returner.returner(load) Write return to all returners in multi_returner .UNINDENT .INDENT 0.0 .TP .B salt.returners.multi_returner.save_load(jid, clear_load, minions=None) Write load to all returners in multi_returner .UNINDENT .SS salt.returners.mysql .sp Return data to a mysql server .INDENT 0.0 .TP .B maintainer Dave Boucha <\fI\%dave@saltstack.com\fP>, Seth House <\fI\%shouse@saltstack.com\fP> .TP .B maturity mature .TP .B depends python\-mysqldb .TP .B platform all .UNINDENT .sp To enable this returner, the minion will need the python client for mysql installed and the following values configured in the minion or master config. These are the defaults: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C mysql.host: \(aqsalt\(aq mysql.user: \(aqsalt\(aq mysql.pass: \(aqsalt\(aq mysql.db: \(aqsalt\(aq mysql.port: 3306 .ft P .fi .UNINDENT .UNINDENT .sp SSL is optional. The defaults are set to None. If you do not want to use SSL, either exclude these options or set them to None. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C mysql.ssl_ca: None mysql.ssl_cert: None mysql.ssl_key: None .ft P .fi .UNINDENT .UNINDENT .sp Alternative configuration values can be used by prefacing the configuration with \fIalternative.\fP\&. Any values not found in the alternative configuration will be pulled from the default location. As stated above, SSL configuration is optional. The following ssl options are simply for illustration purposes: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C alternative.mysql.host: \(aqsalt\(aq alternative.mysql.user: \(aqsalt\(aq alternative.mysql.pass: \(aqsalt\(aq alternative.mysql.db: \(aqsalt\(aq alternative.mysql.port: 3306 alternative.mysql.ssl_ca: \(aq/etc/pki/mysql/certs/localhost.pem\(aq alternative.mysql.ssl_cert: \(aq/etc/pki/mysql/certs/localhost.crt\(aq alternative.mysql.ssl_key: \(aq/etc/pki/mysql/certs/localhost.key\(aq .ft P .fi .UNINDENT .UNINDENT .sp Should you wish the returner data to be cleaned out every so often, set \fIkeep_jobs\fP to the number of hours for the jobs to live in the tables. Setting it to \fI0\fP or leaving it unset will cause the data to stay in the tables. .sp Should you wish to archive jobs in a different table for later processing, set \fIarchive_jobs\fP to True. Salt will create 3 archive tables .INDENT 0.0 .IP \(bu 2 \fIjids_archive\fP .IP \(bu 2 \fIsalt_returns_archive\fP .IP \(bu 2 \fIsalt_events_archive\fP .UNINDENT .sp and move the contents of \fIjids\fP, \fIsalt_returns\fP, and \fIsalt_events\fP that are more than \fIkeep_jobs\fP hours old to these tables. .sp Use the following mysql database schema: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C CREATE DATABASE \(gasalt\(ga DEFAULT CHARACTER SET utf8 DEFAULT COLLATE utf8_general_ci; USE \(gasalt\(ga; \-\- \-\- Table structure for table \(gajids\(ga \-\- DROP TABLE IF EXISTS \(gajids\(ga; CREATE TABLE \(gajids\(ga ( \(gajid\(ga varchar(255) NOT NULL, \(gaload\(ga mediumtext NOT NULL, UNIQUE KEY \(gajid\(ga (\(gajid\(ga) ) ENGINE=InnoDB DEFAULT CHARSET=utf8; CREATE INDEX jid ON jids(jid) USING BTREE; \-\- \-\- Table structure for table \(gasalt_returns\(ga \-\- DROP TABLE IF EXISTS \(gasalt_returns\(ga; CREATE TABLE \(gasalt_returns\(ga ( \(gafun\(ga varchar(50) NOT NULL, \(gajid\(ga varchar(255) NOT NULL, \(gareturn\(ga mediumtext NOT NULL, \(gaid\(ga varchar(255) NOT NULL, \(gasuccess\(ga varchar(10) NOT NULL, \(gafull_ret\(ga mediumtext NOT NULL, \(gaalter_time\(ga TIMESTAMP DEFAULT CURRENT_TIMESTAMP, KEY \(gaid\(ga (\(gaid\(ga), KEY \(gajid\(ga (\(gajid\(ga), KEY \(gafun\(ga (\(gafun\(ga) ) ENGINE=InnoDB DEFAULT CHARSET=utf8; \-\- \-\- Table structure for table \(gasalt_events\(ga \-\- DROP TABLE IF EXISTS \(gasalt_events\(ga; CREATE TABLE \(gasalt_events\(ga ( \(gaid\(ga BIGINT NOT NULL AUTO_INCREMENT, \(gatag\(ga varchar(255) NOT NULL, \(gadata\(ga mediumtext NOT NULL, \(gaalter_time\(ga TIMESTAMP DEFAULT CURRENT_TIMESTAMP, \(gamaster_id\(ga varchar(255) NOT NULL, PRIMARY KEY (\(gaid\(ga), KEY \(gatag\(ga (\(gatag\(ga) ) ENGINE=InnoDB DEFAULT CHARSET=utf8; .ft P .fi .UNINDENT .UNINDENT .sp Required python modules: MySQLdb .sp To use the mysql returner, append \(aq\-\-return mysql\(aq to the salt command. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq test.ping \-\-return mysql .ft P .fi .UNINDENT .UNINDENT .sp To use the alternative configuration, append \(aq\-\-return_config alternative\(aq to the salt command. .sp New in version 2015.5.0. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq test.ping \-\-return mysql \-\-return_config alternative .ft P .fi .UNINDENT .UNINDENT .sp To override individual configuration items, append \-\-return_kwargs \(aq{"key:": "value"}\(aq to the salt command. .sp New in version 2016.3.0. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq test.ping \-\-return mysql \-\-return_kwargs \(aq{"db": "another\-salt"}\(aq .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.returners.mysql.clean_old_jobs() Called in the master\(aqs event loop every loop_interval. Archives and/or deletes the events and job details from the database. :return: .UNINDENT .INDENT 0.0 .TP .B salt.returners.mysql.event_return(events) Return event to mysql server .sp Requires that configuration be enabled via \(aqevent_return\(aq option in master config. .UNINDENT .INDENT 0.0 .TP .B salt.returners.mysql.get_fun(fun) Return a dict of the last function called for all minions .UNINDENT .INDENT 0.0 .TP .B salt.returners.mysql.get_jid(jid) Return the information returned when the specified job id was executed .UNINDENT .INDENT 0.0 .TP .B salt.returners.mysql.get_jids() Return a list of all job ids .UNINDENT .INDENT 0.0 .TP .B salt.returners.mysql.get_jids_filter(count, filter_find_job=True) Return a list of all job ids :param int count: show not more than the count of most recent jobs :param bool filter_find_jobs: filter out \(aqsaltutil.find_job\(aq jobs .UNINDENT .INDENT 0.0 .TP .B salt.returners.mysql.get_load(jid) Return the load data that marks a specified jid .UNINDENT .INDENT 0.0 .TP .B salt.returners.mysql.get_minions() Return a list of minions .UNINDENT .INDENT 0.0 .TP .B salt.returners.mysql.prep_jid(nocache=False, passed_jid=None) Do any work necessary to prepare a JID, including sending a custom id .UNINDENT .INDENT 0.0 .TP .B salt.returners.mysql.returner(ret) Return data to a mysql server .UNINDENT .INDENT 0.0 .TP .B salt.returners.mysql.save_load(jid, load, minions=None) Save the load to the specified jid id .UNINDENT .SS salt.returners.nagios_return .sp Return salt data to Nagios .sp The following fields can be set in the minion conf file: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C nagios.url (required) nagios.token (required) nagios.service (optional) nagios.check_type (optional) .ft P .fi .UNINDENT .UNINDENT .sp Alternative configuration values can be used by prefacing the configuration. Any values not found in the alternative configuration will be pulled from the default location: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C nagios.url nagios.token nagios.service .ft P .fi .UNINDENT .UNINDENT .sp Nagios settings may also be configured as: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C nagios: url: http://localhost/nrdp token: r4nd0mt0k3n service: service\-check alternative.nagios: url: http://localhost/nrdp token: r4nd0mt0k3n service: another\-service\-check To use the Nagios returner, append \(aq\-\-return nagios\(aq to the salt command. ex: \&.. code\-block:: bash salt \(aq*\(aq test.ping \-\-return nagios To use the alternative configuration, append \(aq\-\-return_config alternative\(aq to the salt command. ex: salt \(aq*\(aq test.ping \-\-return nagios \-\-return_config alternative .ft P .fi .UNINDENT .UNINDENT .sp To override individual configuration items, append \-\-return_kwargs \(aq{"key:": "value"}\(aq to the salt command. .sp New in version 2016.3.0. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq test.ping \-\-return nagios \-\-return_kwargs \(aq{"service": "service\-name"}\(aq .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.returners.nagios_return.returner(ret) Send a message to Nagios with the data .UNINDENT .SS salt.returners.odbc .sp Return data to an ODBC compliant server. This driver was developed with Microsoft SQL Server in mind, but theoretically could be used to return data to any compliant ODBC database as long as there is a working ODBC driver for it on your minion platform. .INDENT 0.0 .TP .B maintainer .INDENT 7.0 .IP C. 3 .INDENT 3.0 .IP R. 3 Oldham (\fI\%cr@saltstack.com\fP) .UNINDENT .UNINDENT .TP .B maturity New .TP .B depends unixodbc, pyodbc, freetds (for SQL Server) .TP .B platform all .UNINDENT .sp To enable this returner the minion will need .sp On Linux: .INDENT 0.0 .INDENT 3.5 unixodbc (\fI\%http://www.unixodbc.org\fP) pyodbc (\fIpip install pyodbc\fP) The FreeTDS ODBC driver for SQL Server (\fI\%http://www.freetds.org\fP) or another compatible ODBC driver .UNINDENT .UNINDENT .sp On Windows: .INDENT 0.0 .INDENT 3.5 TBD .UNINDENT .UNINDENT .sp unixODBC and FreeTDS need to be configured via /etc/odbcinst.ini and /etc/odbc.ini. .sp /etc/odbcinst.ini: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C [TDS] Description=TDS Driver=/usr/lib/x86_64\-linux\-gnu/odbc/libtdsodbc.so .ft P .fi .UNINDENT .UNINDENT .sp (Note the above Driver line needs to point to the location of the FreeTDS shared library. This example is for Ubuntu 14.04.) .sp /etc/odbc.ini: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C [TS] Description = "Salt Returner" Driver=TDS Server = Port = 1433 Database = salt Trace = No .ft P .fi .UNINDENT .UNINDENT .sp Also you need the following values configured in the minion or master config. Configure as you see fit: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C returner.odbc.dsn: \(aqTS\(aq returner.odbc.user: \(aqsalt\(aq returner.odbc.passwd: \(aqsalt\(aq .ft P .fi .UNINDENT .UNINDENT .sp Alternative configuration values can be used by prefacing the configuration. Any values not found in the alternative configuration will be pulled from the default location: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C alternative.returner.odbc.dsn: \(aqTS\(aq alternative.returner.odbc.user: \(aqsalt\(aq alternative.returner.odbc.passwd: \(aqsalt\(aq .ft P .fi .UNINDENT .UNINDENT .sp Running the following commands against Microsoft SQL Server in the desired database as the appropriate user should create the database tables correctly. Replace with equivalent SQL for other ODBC\-compliant servers .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C \-\- \-\- Table structure for table \(aqjids\(aq \-\- if OBJECT_ID(\(aqdbo.jids\(aq, \(aqU\(aq) is not null DROP TABLE dbo.jids CREATE TABLE dbo.jids ( jid varchar(255) PRIMARY KEY, load varchar(MAX) NOT NULL ); \-\- \-\- Table structure for table \(aqsalt_returns\(aq \-\- IF OBJECT_ID(\(aqdbo.salt_returns\(aq, \(aqU\(aq) IS NOT NULL DROP TABLE dbo.salt_returns; CREATE TABLE dbo.salt_returns ( added datetime not null default (getdate()), fun varchar(100) NOT NULL, jid varchar(255) NOT NULL, retval varchar(MAX) NOT NULL, id varchar(255) NOT NULL, success bit default(0) NOT NULL, full_ret varchar(MAX) ); CREATE INDEX salt_returns_added on dbo.salt_returns(added); CREATE INDEX salt_returns_id on dbo.salt_returns(id); CREATE INDEX salt_returns_jid on dbo.salt_returns(jid); CREATE INDEX salt_returns_fun on dbo.salt_returns(fun); To use this returner, append \(aq\-\-return odbc\(aq to the salt command. \&.. code\-block:: bash salt \(aq*\(aq status.diskusage \-\-return odbc To use the alternative configuration, append \(aq\-\-return_config alternative\(aq to the salt command. \&.. versionadded:: 2015.5.0 \&.. code\-block:: bash salt \(aq*\(aq test.ping \-\-return odbc \-\-return_config alternative .ft P .fi .UNINDENT .UNINDENT .sp To override individual configuration items, append \-\-return_kwargs \(aq{"key:": "value"}\(aq to the salt command. .sp New in version 2016.3.0. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq test.ping \-\-return odbc \-\-return_kwargs \(aq{"dsn": "dsn\-name"}\(aq .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.returners.odbc.get_fun(fun) Return a dict of the last function called for all minions .UNINDENT .INDENT 0.0 .TP .B salt.returners.odbc.get_jid(jid) Return the information returned when the specified job id was executed .UNINDENT .INDENT 0.0 .TP .B salt.returners.odbc.get_jids() Return a list of all job ids .UNINDENT .INDENT 0.0 .TP .B salt.returners.odbc.get_load(jid) Return the load data that marks a specified jid .UNINDENT .INDENT 0.0 .TP .B salt.returners.odbc.get_minions() Return a list of minions .UNINDENT .INDENT 0.0 .TP .B salt.returners.odbc.prep_jid(nocache=False, passed_jid=None) Do any work necessary to prepare a JID, including sending a custom id .UNINDENT .INDENT 0.0 .TP .B salt.returners.odbc.returner(ret) Return data to an odbc server .UNINDENT .INDENT 0.0 .TP .B salt.returners.odbc.save_load(jid, load, minions=None) Save the load to the specified jid id .UNINDENT .SS salt.returners.pgjsonb .sp Return data to a PostgreSQL server with json data stored in Pg\(aqs jsonb data type .INDENT 0.0 .TP .B maintainer Dave Boucha <\fI\%dave@saltstack.com\fP>, Seth House <\fI\%shouse@saltstack.com\fP>, C. R. Oldham <\fI\%cr@saltstack.com\fP> .TP .B maturity new .TP .B depends python\-psycopg2 .TP .B platform all .UNINDENT .sp To enable this returner, the minion will need the python client for PostgreSQL installed and the following values configured in the minion or master config. These are the defaults: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C returner.pgjsonb.host: \(aqsalt\(aq returner.pgjsonb.user: \(aqsalt\(aq returner.pgjsonb.pass: \(aqsalt\(aq returner.pgjsonb.db: \(aqsalt\(aq returner.pgjsonb.port: 5432 .ft P .fi .UNINDENT .UNINDENT .sp SSL is optional. The defaults are set to None. If you do not want to use SSL, either exclude these options or set them to None. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C returner.pgjsonb.ssl_ca: None returner.pgjsonb.ssl_cert: None returner.pgjsonb.ssl_key: None .ft P .fi .UNINDENT .UNINDENT .sp Alternative configuration values can be used by prefacing the configuration with \fIalternative.\fP\&. Any values not found in the alternative configuration will be pulled from the default location. As stated above, SSL configuration is optional. The following ssl options are simply for illustration purposes: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C alternative.pgjsonb.host: \(aqsalt\(aq alternative.pgjsonb.user: \(aqsalt\(aq alternative.pgjsonb.pass: \(aqsalt\(aq alternative.pgjsonb.db: \(aqsalt\(aq alternative.pgjsonb.port: 5432 alternative.pgjsonb.ssl_ca: \(aq/etc/pki/mysql/certs/localhost.pem\(aq alternative.pgjsonb.ssl_cert: \(aq/etc/pki/mysql/certs/localhost.crt\(aq alternative.pgjsonb.ssl_key: \(aq/etc/pki/mysql/certs/localhost.key\(aq .ft P .fi .UNINDENT .UNINDENT .sp Use the following Pg database schema: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C CREATE DATABASE salt WITH ENCODING \(aqutf\-8\(aq; \-\- \-\- Table structure for table \(gajids\(ga \-\- DROP TABLE IF EXISTS jids; CREATE TABLE jids ( jid varchar(255) NOT NULL primary key, load jsonb NOT NULL ); CREATE INDEX idx_jids_jsonb on jids USING gin (load) WITH (fastupdate=on); \-\- \-\- Table structure for table \(gasalt_returns\(ga \-\- DROP TABLE IF EXISTS salt_returns; CREATE TABLE salt_returns ( fun varchar(50) NOT NULL, jid varchar(255) NOT NULL, return jsonb NOT NULL, id varchar(255) NOT NULL, success varchar(10) NOT NULL, full_ret jsonb NOT NULL, alter_time TIMESTAMP WITH TIME ZONE DEFAULT NOW()); CREATE INDEX idx_salt_returns_id ON salt_returns (id); CREATE INDEX idx_salt_returns_jid ON salt_returns (jid); CREATE INDEX idx_salt_returns_fun ON salt_returns (fun); CREATE INDEX idx_salt_returns_return ON salt_returns USING gin (return) with (fastupdate=on); CREATE INDEX idx_salt_returns_full_ret ON salt_returns USING gin (full_ret) with (fastupdate=on); \-\- \-\- Table structure for table \(gasalt_events\(ga \-\- DROP TABLE IF EXISTS salt_events; DROP SEQUENCE IF EXISTS seq_salt_events_id; CREATE SEQUENCE seq_salt_events_id; CREATE TABLE salt_events ( id BIGINT NOT NULL UNIQUE DEFAULT nextval(\(aqseq_salt_events_id\(aq), tag varchar(255) NOT NULL, data jsonb NOT NULL, alter_time TIMESTAMP WITH TIME ZONE DEFAULT NOW(), master_id varchar(255) NOT NULL); CREATE INDEX idx_salt_events_tag on salt_events (tag); CREATE INDEX idx_salt_events_data ON salt_events USING gin (data) with (fastupdate=on); .ft P .fi .UNINDENT .UNINDENT .sp Required python modules: Psycopg2 .sp To use this returner, append \(aq\-\-return pgjsonb\(aq to the salt command. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq test.ping \-\-return pgjsonb .ft P .fi .UNINDENT .UNINDENT .sp To use the alternative configuration, append \(aq\-\-return_config alternative\(aq to the salt command. .sp New in version 2015.5.0. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq test.ping \-\-return pgjsonb \-\-return_config alternative .ft P .fi .UNINDENT .UNINDENT .sp To override individual configuration items, append \-\-return_kwargs \(aq{"key:": "value"}\(aq to the salt command. .sp New in version 2016.3.0. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq test.ping \-\-return pgjsonb \-\-return_kwargs \(aq{"db": "another\-salt"}\(aq .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.returners.pgjsonb.event_return(events) Return event to Pg server .sp Requires that configuration be enabled via \(aqevent_return\(aq option in master config. .UNINDENT .INDENT 0.0 .TP .B salt.returners.pgjsonb.get_fun(fun) Return a dict of the last function called for all minions .UNINDENT .INDENT 0.0 .TP .B salt.returners.pgjsonb.get_jid(jid) Return the information returned when the specified job id was executed .UNINDENT .INDENT 0.0 .TP .B salt.returners.pgjsonb.get_jids() Return a list of all job ids .UNINDENT .INDENT 0.0 .TP .B salt.returners.pgjsonb.get_load(jid) Return the load data that marks a specified jid .UNINDENT .INDENT 0.0 .TP .B salt.returners.pgjsonb.get_minions() Return a list of minions .UNINDENT .INDENT 0.0 .TP .B salt.returners.pgjsonb.prep_jid(nocache=False, passed_jid=None) Do any work necessary to prepare a JID, including sending a custom id .UNINDENT .INDENT 0.0 .TP .B salt.returners.pgjsonb.returner(ret) Return data to a Pg server .UNINDENT .INDENT 0.0 .TP .B salt.returners.pgjsonb.save_load(jid, load, minions=None) Save the load to the specified jid id .UNINDENT .SS salt.returners.postgres .sp Return data to a postgresql server .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 \fBreturners.postgres_local_cache\fP is recommended instead of this module when using PostgreSQL as a master job cache\&. These two modules provide different functionality so you should compare each to see which module best suits your particular needs. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B maintainer None .TP .B maturity New .TP .B depends psycopg2 .TP .B platform all .UNINDENT .sp To enable this returner the minion will need the psycopg2 installed and the following values configured in the minion or master config: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C returner.postgres.host: \(aqsalt\(aq returner.postgres.user: \(aqsalt\(aq returner.postgres.passwd: \(aqsalt\(aq returner.postgres.db: \(aqsalt\(aq returner.postgres.port: 5432 .ft P .fi .UNINDENT .UNINDENT .sp Alternative configuration values can be used by prefacing the configuration. Any values not found in the alternative configuration will be pulled from the default location: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C alternative.returner.postgres.host: \(aqsalt\(aq alternative.returner.postgres.user: \(aqsalt\(aq alternative.returner.postgres.passwd: \(aqsalt\(aq alternative.returner.postgres.db: \(aqsalt\(aq alternative.returner.postgres.port: 5432 .ft P .fi .UNINDENT .UNINDENT .sp Running the following commands as the postgres user should create the database correctly: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C psql << EOF CREATE ROLE salt WITH PASSWORD \(aqsalt\(aq; CREATE DATABASE salt WITH OWNER salt; EOF psql \-h localhost \-U salt << EOF \-\- \-\- Table structure for table \(aqjids\(aq \-\- DROP TABLE IF EXISTS jids; CREATE TABLE jids ( jid varchar(20) PRIMARY KEY, load text NOT NULL ); \-\- \-\- Table structure for table \(aqsalt_returns\(aq \-\- DROP TABLE IF EXISTS salt_returns; CREATE TABLE salt_returns ( fun varchar(50) NOT NULL, jid varchar(255) NOT NULL, return text NOT NULL, full_ret text, id varchar(255) NOT NULL, success varchar(10) NOT NULL, alter_time TIMESTAMP WITH TIME ZONE DEFAULT now() ); CREATE INDEX idx_salt_returns_id ON salt_returns (id); CREATE INDEX idx_salt_returns_jid ON salt_returns (jid); CREATE INDEX idx_salt_returns_fun ON salt_returns (fun); CREATE INDEX idx_salt_returns_updated ON salt_returns (alter_time); \-\- \-\- Table structure for table \(gasalt_events\(ga \-\- DROP TABLE IF EXISTS salt_events; DROP SEQUENCE IF EXISTS seq_salt_events_id; CREATE SEQUENCE seq_salt_events_id; CREATE TABLE salt_events ( id BIGINT NOT NULL UNIQUE DEFAULT nextval(\(aqseq_salt_events_id\(aq), tag varchar(255) NOT NULL, data text NOT NULL, alter_time TIMESTAMP WITH TIME ZONE DEFAULT NOW(), master_id varchar(255) NOT NULL ); CREATE INDEX idx_salt_events_tag on salt_events (tag); EOF .ft P .fi .UNINDENT .UNINDENT .sp Required python modules: psycopg2 .sp To use the postgres returner, append \(aq\-\-return postgres\(aq to the salt command. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq test.ping \-\-return postgres .ft P .fi .UNINDENT .UNINDENT .sp To use the alternative configuration, append \(aq\-\-return_config alternative\(aq to the salt command. .sp New in version 2015.5.0. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq test.ping \-\-return postgres \-\-return_config alternative .ft P .fi .UNINDENT .UNINDENT .sp To override individual configuration items, append \-\-return_kwargs \(aq{"key:": "value"}\(aq to the salt command. .sp New in version 2016.3.0. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq test.ping \-\-return postgres \-\-return_kwargs \(aq{"db": "another\-salt"}\(aq .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.returners.postgres.event_return(events) Return event to Pg server .sp Requires that configuration be enabled via \(aqevent_return\(aq option in master config. .UNINDENT .INDENT 0.0 .TP .B salt.returners.postgres.get_fun(fun) Return a dict of the last function called for all minions .UNINDENT .INDENT 0.0 .TP .B salt.returners.postgres.get_jid(jid) Return the information returned when the specified job id was executed .UNINDENT .INDENT 0.0 .TP .B salt.returners.postgres.get_jids() Return a list of all job ids .UNINDENT .INDENT 0.0 .TP .B salt.returners.postgres.get_load(jid) Return the load data that marks a specified jid .UNINDENT .INDENT 0.0 .TP .B salt.returners.postgres.get_minions() Return a list of minions .UNINDENT .INDENT 0.0 .TP .B salt.returners.postgres.prep_jid(nocache=False, passed_jid=None) Do any work necessary to prepare a JID, including sending a custom id .UNINDENT .INDENT 0.0 .TP .B salt.returners.postgres.returner(ret) Return data to a postgres server .UNINDENT .INDENT 0.0 .TP .B salt.returners.postgres.save_load(jid, load, minions=None) Save the load to the specified jid id .UNINDENT .SS salt.returners.postgres_local_cache .sp Use a postgresql server for the master job cache. This helps the job cache to cope with scale. .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 \fBreturners.postgres\fP is also available if you are not using PostgreSQL as a master job cache\&. These two modules provide different functionality so you should compare each to see which module best suits your particular needs. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B maintainer \fI\%gjredelinghuys@gmail.com\fP .TP .B maturity New .TP .B depends psycopg2 .TP .B platform all .UNINDENT .sp To enable this returner the minion will need the psycopg2 installed and the following values configured in the master config: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C master_job_cache: postgres_local_cache master_job_cache.postgres.host: \(aqsalt\(aq master_job_cache.postgres.user: \(aqsalt\(aq master_job_cache.postgres.passwd: \(aqsalt\(aq master_job_cache.postgres.db: \(aqsalt\(aq master_job_cache.postgres.port: 5432 .ft P .fi .UNINDENT .UNINDENT .sp Running the following command as the postgres user should create the database correctly: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C psql << EOF CREATE ROLE salt WITH PASSWORD \(aqsalt\(aq; CREATE DATABASE salt WITH OWNER salt; EOF .ft P .fi .UNINDENT .UNINDENT .sp In case the postgres database is a remote host, you\(aqll need this command also: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C ALTER ROLE salt WITH LOGIN; .ft P .fi .UNINDENT .UNINDENT .sp and then: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C psql \-h localhost \-U salt << EOF \-\- \-\- Table structure for table \(aqjids\(aq \-\- DROP TABLE IF EXISTS jids; CREATE TABLE jids ( jid varchar(20) PRIMARY KEY, started TIMESTAMP WITH TIME ZONE DEFAULT now(), tgt_type text NOT NULL, cmd text NOT NULL, tgt text NOT NULL, kwargs text NOT NULL, ret text NOT NULL, username text NOT NULL, arg text NOT NULL, fun text NOT NULL ); \-\- \-\- Table structure for table \(aqsalt_returns\(aq \-\- \-\- note that \(aqsuccess\(aq must not have NOT NULL constraint, since \-\- some functions don\(aqt provide it. DROP TABLE IF EXISTS salt_returns; CREATE TABLE salt_returns ( added TIMESTAMP WITH TIME ZONE DEFAULT now(), fun text NOT NULL, jid varchar(20) NOT NULL, return text NOT NULL, id text NOT NULL, success boolean ); CREATE INDEX ON salt_returns (added); CREATE INDEX ON salt_returns (id); CREATE INDEX ON salt_returns (jid); CREATE INDEX ON salt_returns (fun); DROP TABLE IF EXISTS salt_events; CREATE TABLE salt_events ( id SERIAL, tag text NOT NULL, data text NOT NULL, alter_time TIMESTAMP WITH TIME ZONE DEFAULT now(), master_id text NOT NULL ); CREATE INDEX ON salt_events (tag); CREATE INDEX ON salt_events (data); CREATE INDEX ON salt_events (id); CREATE INDEX ON salt_events (master_id); EOF .ft P .fi .UNINDENT .UNINDENT .sp Required python modules: psycopg2 .INDENT 0.0 .TP .B salt.returners.postgres_local_cache.clean_old_jobs() Clean out the old jobs from the job cache .UNINDENT .INDENT 0.0 .TP .B salt.returners.postgres_local_cache.event_return(events) Return event to a postgres server .sp Require that configuration be enabled via \(aqevent_return\(aq option in master config. .UNINDENT .INDENT 0.0 .TP .B salt.returners.postgres_local_cache.get_jid(jid) Return the information returned when the specified job id was executed .UNINDENT .INDENT 0.0 .TP .B salt.returners.postgres_local_cache.get_jids() Return a list of all job ids For master job cache this also formats the output and returns a string .UNINDENT .INDENT 0.0 .TP .B salt.returners.postgres_local_cache.get_load(jid) Return the load data that marks a specified jid .UNINDENT .INDENT 0.0 .TP .B salt.returners.postgres_local_cache.prep_jid(nocache=False, passed_jid=None) Return a job id and prepare the job id directory This is the function responsible for making sure jids don\(aqt collide (unless its passed a jid). So do what you have to do to make sure that stays the case .UNINDENT .INDENT 0.0 .TP .B salt.returners.postgres_local_cache.returner(load) Return data to a postgres server .UNINDENT .INDENT 0.0 .TP .B salt.returners.postgres_local_cache.save_load(jid, clear_load, minions=None) Save the load to the specified jid id .UNINDENT .SS salt.returners.pushover_returner .sp Return salt data via pushover (\fI\%http://www.pushover.net\fP) .sp New in version 2016.3.0. .sp The following fields can be set in the minion conf file: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C pushover.user (required) pushover.token (required) pushover.title (optional) pushover.device (optional) pushover.priority (optional) pushover.expire (optional) pushover.retry (optional) pushover.profile (optional) .ft P .fi .UNINDENT .UNINDENT .sp Alternative configuration values can be used by prefacing the configuration. Any values not found in the alternative configuration will be pulled from the default location: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C alternative.pushover.user alternative.pushover.token alternative.pushover.title alternative.pushover.device alternative.pushover.priority alternative.pushover.expire alternative.pushover.retry .ft P .fi .UNINDENT .UNINDENT .sp PushOver settings may also be configured as: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C pushover: user: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx token: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx title: Salt Returner device: phone priority: \-1 expire: 3600 retry: 5 alternative.pushover: user: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx token: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx title: Salt Returner device: phone priority: 1 expire: 4800 retry: 2 pushover_profile: pushover.token: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx pushover: user: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx profile: pushover_profile alternative.pushover: user: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx profile: pushover_profile To use the PushOver returner, append \(aq\-\-return pushover\(aq to the salt command. ex: \&.. code\-block:: bash salt \(aq*\(aq test.ping \-\-return pushover To use the alternative configuration, append \(aq\-\-return_config alternative\(aq to the salt command. ex: salt \(aq*\(aq test.ping \-\-return pushover \-\-return_config alternative .ft P .fi .UNINDENT .UNINDENT .sp To override individual configuration items, append \-\-return_kwargs \(aq{"key:": "value"}\(aq to the salt command. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq test.ping \-\-return pushover \-\-return_kwargs \(aq{"title": "Salt is awesome!"}\(aq .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.returners.pushover_returner.returner(ret) Send an PushOver message with the data .UNINDENT .SS salt.returners.rawfile_json .sp Take data from salt and "return" it into a raw file containing the json, with one line per event. .sp Add the following to the minion or master configuration file. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C rawfile_json.filename: .ft P .fi .UNINDENT .UNINDENT .sp Default is \fB/var/log/salt/events\fP\&. .sp Common use is to log all events on the master. This can generate a lot of noise, so you may wish to configure batch processing and/or configure the \fBevent_return_whitelist\fP or \fBevent_return_blacklist\fP to restrict the events that are written. .INDENT 0.0 .TP .B salt.returners.rawfile_json.event_return(event) Write event return data to a file on the master. .UNINDENT .INDENT 0.0 .TP .B salt.returners.rawfile_json.returner(ret) Write the return data to a file on the minion. .UNINDENT .SS salt.returners.redis_return .sp Return data to a redis server .sp To enable this returner the minion will need the python client for redis installed and the following values configured in the minion or master config, these are the defaults: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C redis.db: \(aq0\(aq redis.host: \(aqsalt\(aq redis.port: 6379 .ft P .fi .UNINDENT .UNINDENT .sp Alternative configuration values can be used by prefacing the configuration. Any values not found in the alternative configuration will be pulled from the default location: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C alternative.redis.db: \(aq0\(aq alternative.redis.host: \(aqsalt\(aq alternative.redis.port: 6379 .ft P .fi .UNINDENT .UNINDENT .sp To use the redis returner, append \(aq\-\-return redis\(aq to the salt command. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq test.ping \-\-return redis .ft P .fi .UNINDENT .UNINDENT .sp To use the alternative configuration, append \(aq\-\-return_config alternative\(aq to the salt command. .sp New in version 2015.5.0. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq test.ping \-\-return redis \-\-return_config alternative .ft P .fi .UNINDENT .UNINDENT .sp To override individual configuration items, append \-\-return_kwargs \(aq{"key:": "value"}\(aq to the salt command. .sp New in version 2016.3.0. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq test.ping \-\-return redis \-\-return_kwargs \(aq{"db": "another\-salt"}\(aq .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.returners.redis_return.clean_old_jobs() Clean out minions\(aqs return data for old jobs. .sp Normally, hset \(aqret:\(aq are saved with a TTL, and will eventually get cleaned by redis.But for jobs with some very late minion return, the corresponding hset\(aqs TTL will be refreshed to a too late timestamp, we\(aqll do manually cleaning here. .UNINDENT .INDENT 0.0 .TP .B salt.returners.redis_return.get_fun(fun) Return a dict of the last function called for all minions .UNINDENT .INDENT 0.0 .TP .B salt.returners.redis_return.get_jid(jid) Return the information returned when the specified job id was executed .UNINDENT .INDENT 0.0 .TP .B salt.returners.redis_return.get_jids() Return a dict mapping all job ids to job information .UNINDENT .INDENT 0.0 .TP .B salt.returners.redis_return.get_load(jid) Return the load data that marks a specified jid .UNINDENT .INDENT 0.0 .TP .B salt.returners.redis_return.get_minions() Return a list of minions .UNINDENT .INDENT 0.0 .TP .B salt.returners.redis_return.prep_jid(nocache=False, passed_jid=None) Do any work necessary to prepare a JID, including sending a custom id .UNINDENT .INDENT 0.0 .TP .B salt.returners.redis_return.returner(ret) Return data to a redis data store .UNINDENT .INDENT 0.0 .TP .B salt.returners.redis_return.save_load(jid, load, minions=None) Save the load to the specified jid .UNINDENT .SS salt.returners.sentry_return .sp Salt returner that reports execution results back to sentry. The returner will inspect the payload to identify errors and flag them as such. .sp Pillar needs something like: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C raven: servers: \- http://192.168.1.1 \- https://sentry.example.com public_key: deadbeefdeadbeefdeadbeefdeadbeef secret_key: beefdeadbeefdeadbeefdeadbeefdead project: 1 tags: \- os \- master \- saltversion \- cpuarch .ft P .fi .UNINDENT .UNINDENT .sp or using a dsn: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C raven: dsn: https://aaaa:bbbb@app.getsentry.com/12345 tags: \- os \- master \- saltversion \- cpuarch .ft P .fi .UNINDENT .UNINDENT .sp \fI\%https://pypi.python.org/pypi/raven\fP must be installed. .sp The pillar can be hidden on sentry return by setting hide_pillar: true. .sp The tags list (optional) specifies grains items that will be used as sentry tags, allowing tagging of events in the sentry ui. .sp To report only errors to sentry, set report_errors_only: true. .INDENT 0.0 .TP .B salt.returners.sentry_return.prep_jid(nocache=False, passed_jid=None) Do any work necessary to prepare a JID, including sending a custom id .UNINDENT .INDENT 0.0 .TP .B salt.returners.sentry_return.returner(ret) Log outcome to sentry. The returner tries to identify errors and report them as such. All other messages will be reported at info level. Failed states will be appended as separate list for convenience. .UNINDENT .SS salt.returners.slack_returner .sp Return salt data via slack .sp New in version 2015.5.0. .sp The following fields can be set in the minion conf file: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C \&.. code\-block:: yaml .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .INDENT 3.5 slack.channel (required) slack.api_key (required) slack.username (required) slack.as_user (required to see the profile picture of your bot) slack.profile (optional) slack.changes(optional, only show changes and failed states) slack.yaml_format(optional, format the json in yaml format) .UNINDENT .UNINDENT .sp Alternative configuration values can be used by prefacing the configuration. Any values not found in the alternative configuration will be pulled from the default location: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C slack.channel slack.api_key slack.username slack.as_user .ft P .fi .UNINDENT .UNINDENT .sp Slack settings may also be configured as: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C slack: channel: RoomName api_key: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx username: user as_user: true alternative.slack: room_id: RoomName api_key: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx from_name: user@email.com slack_profile: slack.api_key: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx slack.from_name: user@email.com slack: profile: slack_profile channel: RoomName alternative.slack: profile: slack_profile channel: RoomName .ft P .fi .UNINDENT .UNINDENT .sp To use the Slack returner, append \(aq\-\-return slack\(aq to the salt command. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq test.ping \-\-return slack .ft P .fi .UNINDENT .UNINDENT .sp To use the alternative configuration, append \(aq\-\-return_config alternative\(aq to the salt command. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq test.ping \-\-return slack \-\-return_config alternative .ft P .fi .UNINDENT .UNINDENT .sp To override individual configuration items, append \-\-return_kwargs \(aq{"key:": "value"}\(aq to the salt command. .sp New in version 2016.3.0. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq test.ping \-\-return slack \-\-return_kwargs \(aq{"channel": "#random"}\(aq .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.returners.slack_returner.returner(ret) Send an slack message with the data .UNINDENT .SS salt.returners.sms_return .sp Return data by SMS. .sp New in version 2015.5.0. .INDENT 0.0 .TP .B maintainer Damian Myerscough .TP .B maturity new .TP .B depends twilio .TP .B platform all .UNINDENT .sp To enable this returner the minion will need the python twilio library installed and the following values configured in the minion or master config: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C twilio.sid: \(aqXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX\(aq twilio.token: \(aqXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX\(aq twilio.to: \(aq+1415XXXXXXX\(aq twilio.from: \(aq+1650XXXXXXX\(aq .ft P .fi .UNINDENT .UNINDENT .sp To use the sms returner, append \(aq\-\-return sms\(aq to the salt command. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq test.ping \-\-return sms .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.returners.sms_return.returner(ret) Return a response in an SMS message .UNINDENT .SS salt.returners.smtp_return .sp Return salt data via email .sp The following fields can be set in the minion conf file. Fields are optional unless noted otherwise. .INDENT 0.0 .IP \(bu 2 \fBfrom\fP (required) The name/address of the email sender. .IP \(bu 2 .INDENT 2.0 .TP .B \fBto\fP (required) The names/addresses of the email recipients; comma\-delimited. For example: \fByou@example.com,someoneelse@example.com\fP\&. .UNINDENT .IP \(bu 2 \fBhost\fP (required) The SMTP server hostname or address. .IP \(bu 2 \fBport\fP The SMTP server port; defaults to \fB25\fP\&. .IP \(bu 2 .INDENT 2.0 .TP .B \fBusername\fP The username used to authenticate to the server. If specified a password is also required. It is recommended but not required to also use TLS with this option. .UNINDENT .IP \(bu 2 \fBpassword\fP The password used to authenticate to the server. .IP \(bu 2 \fBtls\fP Whether to secure the connection using TLS; defaults to \fBFalse\fP .IP \(bu 2 \fBsubject\fP The email subject line. .IP \(bu 2 .INDENT 2.0 .TP .B \fBfields\fP Which fields from the returned data to include in the subject line of the email; comma\-delimited. For example: \fBid,fun\fP\&. Please note, \fIthe subject line is not encrypted\fP\&. .UNINDENT .IP \(bu 2 .INDENT 2.0 .TP .B \fBgpgowner\fP A user\(aqs \fB~/.gpg\fP directory. This must contain a gpg public key matching the address the mail is sent to. If left unset, no encryption will be used. Requires \fBpython\-gnupg\fP to be installed. .UNINDENT .IP \(bu 2 \fBtemplate\fP The path to a file to be used as a template for the email body. .IP \(bu 2 .INDENT 2.0 .TP .B \fBrenderer\fP A Salt renderer, or render\-pipe, to use to render the email template. Default \fBjinja\fP\&. .UNINDENT .UNINDENT .sp Below is an example of the above settings in a Salt Minion configuration file: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C smtp.from: me@example.net smtp.to: you@example.com smtp.host: localhost smtp.port: 1025 .ft P .fi .UNINDENT .UNINDENT .sp Alternative configuration values can be used by prefacing the configuration. Any values not found in the alternative configuration will be pulled from the default location. For example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C alternative.smtp.username: saltdev alternative.smtp.password: saltdev alternative.smtp.tls: True .ft P .fi .UNINDENT .UNINDENT .sp To use the SMTP returner, append \(aq\-\-return smtp\(aq to the \fBsalt\fP command. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq test.ping \-\-return smtp .ft P .fi .UNINDENT .UNINDENT .sp To use the alternative configuration, append \(aq\-\-return_config alternative\(aq to the \fBsalt\fP command. .sp New in version 2015.5.0. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq test.ping \-\-return smtp \-\-return_config alternative .ft P .fi .UNINDENT .UNINDENT .sp To override individual configuration items, append \-\-return_kwargs \(aq{"key:": "value"}\(aq to the \fBsalt\fP command. .sp New in version 2016.3.0. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq test.ping \-\-return smtp \-\-return_kwargs \(aq{"to": "user@domain.com"}\(aq .ft P .fi .UNINDENT .UNINDENT .sp An easy way to test the SMTP returner is to use the development SMTP server built into Python. The command below will start a single\-threaded SMTP server that prints any email it receives to the console. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C python \-m smtpd \-n \-c DebuggingServer localhost:1025 .ft P .fi .UNINDENT .UNINDENT .sp New in version 2016.11.0. .sp It is possible to send emails with selected Salt events by configuring \fBevent_return\fP option for Salt Master. For example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C event_return: smtp event_return_whitelist: \- salt/key smtp.from: me@example.net smtp.to: you@example.com smtp.host: localhost smtp.subject: \(aqSalt Master {{act}}ed key from Minion ID: {{id}}\(aq smtp.template: /srv/salt/templates/email.j2 .ft P .fi .UNINDENT .UNINDENT .sp Also you need to create additional file \fB/srv/salt/templates/email.j2\fP with email body template: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C act: {{act}} id: {{id}} result: {{result}} .ft P .fi .UNINDENT .UNINDENT .sp This configuration enables Salt Master to send an email when accepting or rejecting minions keys. .INDENT 0.0 .TP .B salt.returners.smtp_return.event_return(events) Return event data via SMTP .UNINDENT .INDENT 0.0 .TP .B salt.returners.smtp_return.prep_jid(nocache=False, passed_jid=None) Do any work necessary to prepare a JID, including sending a custom id .UNINDENT .INDENT 0.0 .TP .B salt.returners.smtp_return.returner(ret) Send an email with the data .UNINDENT .SS salt.returners.splunk module .sp Send json response data to Splunk via the HTTP Event Collector Requires the following config values to be specified in config or pillar: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C splunk_http_forwarder: token: indexer: sourcetype: index: .ft P .fi .UNINDENT .UNINDENT .sp Run a test by using \fBsalt\-call test.ping \-\-return splunk\fP .sp Written by Scott Pack (github.com/scottjpack) .INDENT 0.0 .TP .B salt.returners.splunk.returner(ret) Send a message to Splunk via the HTTP Event Collector .UNINDENT .SS salt.returners.sqlite3 .sp Insert minion return data into a sqlite3 database .INDENT 0.0 .TP .B maintainer Mickey Malone <\fI\%mickey.malone@gmail.com\fP> .TP .B maturity New .TP .B depends None .TP .B platform All .UNINDENT .sp Sqlite3 is a serverless database that lives in a single file. In order to use this returner the database file must exist, have the appropriate schema defined, and be accessible to the user whom the minion process is running as. This returner requires the following values configured in the master or minion config: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C sqlite3.database: /usr/lib/salt/salt.db sqlite3.timeout: 5.0 .ft P .fi .UNINDENT .UNINDENT .sp Alternative configuration values can be used by prefacing the configuration. Any values not found in the alternative configuration will be pulled from the default location: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C alternative.sqlite3.database: /usr/lib/salt/salt.db alternative.sqlite3.timeout: 5.0 .ft P .fi .UNINDENT .UNINDENT .sp Use the commands to create the sqlite3 database and tables: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C sqlite3 /usr/lib/salt/salt.db << EOF \-\- \-\- Table structure for table \(aqjids\(aq \-\- CREATE TABLE jids ( jid TEXT PRIMARY KEY, load TEXT NOT NULL ); \-\- \-\- Table structure for table \(aqsalt_returns\(aq \-\- CREATE TABLE salt_returns ( fun TEXT KEY, jid TEXT KEY, id TEXT KEY, fun_args TEXT, date TEXT NOT NULL, full_ret TEXT NOT NULL, success TEXT NOT NULL ); EOF .ft P .fi .UNINDENT .UNINDENT .sp To use the sqlite returner, append \(aq\-\-return sqlite3\(aq to the salt command. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq test.ping \-\-return sqlite3 .ft P .fi .UNINDENT .UNINDENT .sp To use the alternative configuration, append \(aq\-\-return_config alternative\(aq to the salt command. .sp New in version 2015.5.0. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq test.ping \-\-return sqlite3 \-\-return_config alternative .ft P .fi .UNINDENT .UNINDENT .sp To override individual configuration items, append \-\-return_kwargs \(aq{"key:": "value"}\(aq to the salt command. .sp New in version 2016.3.0. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq test.ping \-\-return sqlite3 \-\-return_kwargs \(aq{"db": "/var/lib/salt/another\-salt.db"}\(aq .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.returners.sqlite3_return.get_fun(fun) Return a dict of the last function called for all minions .UNINDENT .INDENT 0.0 .TP .B salt.returners.sqlite3_return.get_jid(jid) Return the information returned from a specified jid .UNINDENT .INDENT 0.0 .TP .B salt.returners.sqlite3_return.get_jids() Return a list of all job ids .UNINDENT .INDENT 0.0 .TP .B salt.returners.sqlite3_return.get_load(jid) Return the load from a specified jid .UNINDENT .INDENT 0.0 .TP .B salt.returners.sqlite3_return.get_minions() Return a list of minions .UNINDENT .INDENT 0.0 .TP .B salt.returners.sqlite3_return.prep_jid(nocache=False, passed_jid=None) Do any work necessary to prepare a JID, including sending a custom id .UNINDENT .INDENT 0.0 .TP .B salt.returners.sqlite3_return.returner(ret) Insert minion return data into the sqlite3 database .UNINDENT .INDENT 0.0 .TP .B salt.returners.sqlite3_return.save_load(jid, load, minions=None) Save the load to the specified jid .UNINDENT .SS salt.returners.syslog_return .sp Return data to the host operating system\(aqs syslog facility .sp To use the syslog returner, append \(aq\-\-return syslog\(aq to the salt command. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq test.ping \-\-return syslog .ft P .fi .UNINDENT .UNINDENT .sp The following fields can be set in the minion conf file: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C syslog.level (optional, Default: LOG_INFO) syslog.facility (optional, Default: LOG_USER) syslog.tag (optional, Default: salt\-minion) syslog.options (list, optional, Default: []) .ft P .fi .UNINDENT .UNINDENT .sp Available levels, facilities, and options can be found in the \fBsyslog\fP docs for your python version. .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 The default tag comes from \fBsys.argv[0]\fP which is usually "salt\-minion" but could be different based on the specific environment. .UNINDENT .UNINDENT .sp Configuration example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C syslog.level: \(aqLOG_ERR\(aq syslog.facility: \(aqLOG_DAEMON\(aq syslog.tag: \(aqmysalt\(aq syslog.options: \- LOG_PID .ft P .fi .UNINDENT .UNINDENT .sp Of course you can also nest the options: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C syslog: level: \(aqLOG_ERR\(aq facility: \(aqLOG_DAEMON\(aq tag: \(aqmysalt\(aq options: \- LOG_PID .ft P .fi .UNINDENT .UNINDENT .sp Alternative configuration values can be used by prefacing the configuration. Any values not found in the alternative configuration will be pulled from the default location: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C alternative.syslog.level: \(aqLOG_WARN\(aq alternative.syslog.facility: \(aqLOG_NEWS\(aq .ft P .fi .UNINDENT .UNINDENT .sp To use the alternative configuration, append \fB\-\-return_config alternative\fP to the salt command. .sp New in version 2015.5.0. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq test.ping \-\-return syslog \-\-return_config alternative .ft P .fi .UNINDENT .UNINDENT .sp To override individual configuration items, append \-\-return_kwargs \(aq{"key:": "value"}\(aq to the salt command. .sp New in version 2016.3.0. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq test.ping \-\-return syslog \-\-return_kwargs \(aq{"level": "LOG_DEBUG"}\(aq .ft P .fi .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 Syslog server implementations may have limits on the maximum record size received by the client. This may lead to job return data being truncated in the syslog server\(aqs logs. For example, for rsyslog on RHEL\-based systems, the default maximum record size is approximately 2KB (which return data can easily exceed). This is configurable in rsyslog.conf via the $MaxMessageSize config parameter. Please consult your syslog implmentation\(aqs documentation to determine how to adjust this limit. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.returners.syslog_return.prep_jid(nocache=False, passed_jid=None) Do any work necessary to prepare a JID, including sending a custom id .UNINDENT .INDENT 0.0 .TP .B salt.returners.syslog_return.returner(ret) Return data to the local syslog .UNINDENT .SS salt.returners.xmpp_return .sp Return salt data via xmpp .INDENT 0.0 .TP .B depends sleekxmpp >= 1.3.1 .UNINDENT .sp The following fields can be set in the minion conf file: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C xmpp.jid (required) xmpp.password (required) xmpp.recipient (required) xmpp.profile (optional) .ft P .fi .UNINDENT .UNINDENT .sp Alternative configuration values can be used by prefacing the configuration. Any values not found in the alternative configuration will be pulled from the default location: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C xmpp.jid xmpp.password xmpp.recipient xmpp.profile .ft P .fi .UNINDENT .UNINDENT .sp XMPP settings may also be configured as: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C xmpp: jid: user@xmpp.domain.com/resource password: password recipient: user@xmpp.example.com alternative.xmpp: jid: user@xmpp.domain.com/resource password: password recipient: someone@xmpp.example.com xmpp_profile: xmpp.jid: user@xmpp.domain.com/resource xmpp.password: password xmpp: profile: xmpp_profile recipient: user@xmpp.example.com alternative.xmpp: profile: xmpp_profile recipient: someone\-else@xmpp.example.com .ft P .fi .UNINDENT .UNINDENT .sp To use the XMPP returner, append \(aq\-\-return xmpp\(aq to the salt command. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq test.ping \-\-return xmpp .ft P .fi .UNINDENT .UNINDENT .sp To use the alternative configuration, append \(aq\-\-return_config alternative\(aq to the salt command. .sp New in version 2015.5.0. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq test.ping \-\-return xmpp \-\-return_config alternative .ft P .fi .UNINDENT .UNINDENT .sp To override individual configuration items, append \-\-return_kwargs \(aq{"key:": "value"}\(aq to the salt command. .sp New in version 2016.3.0. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq test.ping \-\-return xmpp \-\-return_kwargs \(aq{"recipient": "someone\-else@xmpp.example.com"}\(aq .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.returners.xmpp_return.returner(ret) Send an xmpp message with the data .UNINDENT .SS Renderers .sp The Salt state system operates by gathering information from common data types such as lists, dictionaries, and strings that would be familiar to any developer. .sp SLS files are translated from whatever data templating format they are written in back into Python data types to be consumed by Salt. .sp By default SLS files are rendered as Jinja templates and then parsed as YAML documents. But since the only thing the state system cares about is raw data, the SLS files can be any structured format that can be dreamed up. .sp Currently there is support for \fBJinja + YAML\fP, \fBMako + YAML\fP, \fBWempy + YAML\fP, \fBJinja + json\fP, \fBMako + json\fP and \fBWempy + json\fP\&. .sp Renderers can be written to support any template type. This means that the Salt states could be managed by XML files, HTML files, Puppet files, or any format that can be translated into the Pythonic data structure used by the state system. .SS Multiple Renderers .sp A default renderer is selected in the master configuration file by providing a value to the \fBrenderer\fP key. .sp When evaluating an SLS, more than one renderer can be used. .sp When rendering SLS files, Salt checks for the presence of a Salt\-specific shebang line. .sp The shebang line directly calls the name of the renderer as it is specified within Salt. One of the most common reasons to use multiple renderers is to use the Python or \fBpy\fP renderer. .sp Below, the first line is a shebang that references the \fBpy\fP renderer. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C #!py def run(): \(aq\(aq\(aq Install the python\-mako package \(aq\(aq\(aq return {\(aqinclude\(aq: [\(aqpython\(aq], \(aqpython\-mako\(aq: {\(aqpkg\(aq: [\(aqinstalled\(aq]}} .ft P .fi .UNINDENT .UNINDENT .SS Composing Renderers .sp A renderer can be composed from other renderers by connecting them in a series of pipes(\fB|\fP). .sp In fact, the default \fBJinja + YAML\fP renderer is implemented by connecting a YAML renderer to a Jinja renderer. Such renderer configuration is specified as: \fBjinja | yaml\fP\&. .sp Other renderer combinations are possible: .INDENT 0.0 .INDENT 3.5 .INDENT 0.0 .TP .B \fByaml\fP i.e, just YAML, no templating. .TP .B \fBmako | yaml\fP pass the input to the \fBmako\fP renderer, whose output is then fed into the \fByaml\fP renderer. .TP .B \fBjinja | mako | yaml\fP This one allows you to use both jinja and mako templating syntax in the input and then parse the final rendered output as YAML. .UNINDENT .UNINDENT .UNINDENT .sp The following is a contrived example SLS file using the \fBjinja | mako | yaml\fP renderer: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C #!jinja|mako|yaml An_Example: cmd.run: \- name: | echo "Using Salt ${grains[\(aqsaltversion\(aq]}" \e "from path {{grains[\(aqsaltpath\(aq]}}." \- cwd: / <%doc> ${...} is Mako\(aqs notation, and so is this comment. {# Similarly, {{...}} is Jinja\(aqs notation, and so is this comment. #} .ft P .fi .UNINDENT .UNINDENT .sp For backward compatibility, \fBjinja | yaml\fP can also be written as \fByaml_jinja\fP, and similarly, the \fByaml_mako\fP, \fByaml_wempy\fP, \fBjson_jinja\fP, \fBjson_mako\fP, and \fBjson_wempy\fP renderers are all supported. .sp Keep in mind that not all renderers can be used alone or with any other renderers. For example, the template renderers shouldn\(aqt be used alone as their outputs are just strings, which still need to be parsed by another renderer to turn them into highstate data structures. .sp For example, it doesn\(aqt make sense to specify \fByaml | jinja\fP because the output of the YAML renderer is a highstate data structure (a dict in Python), which cannot be used as the input to a template renderer. Therefore, when combining renderers, you should know what each renderer accepts as input and what it returns as output. .SS Writing Renderers .sp A custom renderer must be a Python module placed in the renderers directory and the module implement the \fBrender\fP function. .sp The \fBrender\fP function will be passed the path of the SLS file as an argument. .sp The purpose of of \fBrender\fP function is to parse the passed file and to return the Python data structure derived from the file. .sp Custom renderers must be placed in a \fB_renderers\fP directory within the \fBfile_roots\fP specified by the master config file. .sp Custom renderers are distributed when any of the following are run: .INDENT 0.0 .IP \(bu 2 \fBstate.apply\fP .IP \(bu 2 \fBsaltutil.sync_renderers\fP .IP \(bu 2 \fBsaltutil.sync_all\fP .UNINDENT .sp Any custom renderers which have been synced to a minion, that are named the same as one of Salt\(aqs default set of renderers, will take the place of the default renderer with the same name. .SS Examples .sp The best place to find examples of renderers is in the Salt source code. .sp Documentation for renderers included with Salt can be found here: .sp \fI\%https://github.com/saltstack/salt/blob/develop/salt/renderers\fP .sp Here is a simple YAML renderer example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C import yaml def render(yaml_data, saltenv=\(aq\(aq, sls=\(aq\(aq, **kws): if not isinstance(yaml_data, basestring): yaml_data = yaml_data.read() data = yaml.load(yaml_data) return data if data else {} .ft P .fi .UNINDENT .UNINDENT .SS Full List of Renderers .SS renderer modules .TS center; |l|l|. _ T{ \fBcheetah\fP T} T{ Cheetah Renderer for Salt T} _ T{ \fBdson\fP T} T{ DSON Renderer for Salt T} _ T{ \fBgenshi\fP T} T{ Genshi Renderer for Salt T} _ T{ \fBgpg\fP T} T{ Renderer that will decrypt GPG ciphers T} _ T{ \fBhjson\fP T} T{ Hjson Renderer for Salt T} _ T{ \fBjinja\fP T} T{ Jinja loading utils to enable a more powerful backend for jinja templates T} _ T{ \fBjson\fP T} T{ JSON Renderer for Salt T} _ T{ \fBjson5\fP T} T{ JSON5 Renderer for Salt T} _ T{ \fBmako\fP T} T{ Mako Renderer for Salt T} _ T{ \fBmsgpack\fP T} T{ T} _ T{ \fBpy\fP T} T{ Pure python state renderer T} _ T{ \fBpydsl\fP T} T{ A Python\-based DSL T} _ T{ \fBpyobjects\fP T} T{ Python renderer that includes a Pythonic Object based interface T} _ T{ \fBstateconf\fP T} T{ A flexible renderer that takes a templating engine and a data format T} _ T{ \fBwempy\fP T} T{ T} _ T{ \fByaml\fP T} T{ YAML Renderer for Salt T} _ T{ \fByamlex\fP T} T{ T} _ .TE .SS salt.renderers.cheetah .sp Cheetah Renderer for Salt .INDENT 0.0 .TP .B salt.renderers.cheetah.render(cheetah_data, saltenv=\(aqbase\(aq, sls=\(aq\(aq, method=\(aqxml\(aq, **kws) Render a Cheetah template. .INDENT 7.0 .TP .B Return type A Python data structure .UNINDENT .UNINDENT .SS salt.renderers.dson .sp DSON Renderer for Salt .sp This renderer is intended for demonstration purposes. Information on the DSON spec can be found \fI\%here\fP\&. .sp This renderer requires \fI\%Dogeon\fP (installable via pip) .INDENT 0.0 .TP .B salt.renderers.dson.render(dson_input, saltenv=\(aqbase\(aq, sls=\(aq\(aq, **kwargs) Accepts DSON data as a string or as a file object and runs it through the JSON parser. .INDENT 7.0 .TP .B Return type A Python data structure .UNINDENT .UNINDENT .SS salt.renderers.genshi .sp Genshi Renderer for Salt .INDENT 0.0 .TP .B salt.renderers.genshi.render(genshi_data, saltenv=\(aqbase\(aq, sls=\(aq\(aq, method=\(aqxml\(aq, **kws) Render a Genshi template. A method should be passed in as part of the kwargs. If no method is passed in, xml is assumed. Valid methods are: .sp Note that the \fBtext\fP method will call \fBNewTextTemplate\fP\&. If \fBoldtext\fP is desired, it must be called explicitly .INDENT 7.0 .TP .B Return type A Python data structure .UNINDENT .UNINDENT .SS salt.renderers.gpg .sp Renderer that will decrypt GPG ciphers .sp Any key in the SLS file can be a GPG cipher, and this renderer will decrypt it before passing it off to Salt. This allows you to safely store secrets in source control, in such a way that only your Salt master can decrypt them and distribute them only to the minions that need them. .sp The typical use\-case would be to use ciphers in your pillar data, and keep a secret key on your master. You can put the public key in source control so that developers can add new secrets quickly and easily. .sp This renderer requires the \fI\%gpg\fP binary. No python libraries are required as of the 2015.8.0 release. .SS Setup .sp To set things up, first generate a keypair. On the master, run the following: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C # mkdir \-p /etc/salt/gpgkeys # chmod 0700 /etc/salt/gpgkeys # gpg \-\-gen\-key \-\-homedir /etc/salt/gpgkeys .ft P .fi .UNINDENT .UNINDENT .sp Do not supply a password for the keypair, and use a name that makes sense for your application. Be sure to back up the \fBgpgkeys\fP directory someplace safe! .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 Unfortunately, there are some scenarios \- for example, on virtual machines which don’t have real hardware \- where insufficient entropy causes key generation to be extremely slow. In these cases, there are usually means of increasing the system entropy. On virtualised Linux systems, this can often be achieved by installing the \fBrng\-tools\fP package. .UNINDENT .UNINDENT .SS Export the Public Key .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C # gpg \-\-homedir /etc/salt/gpgkeys \-\-armor \-\-export > exported_pubkey.gpg .ft P .fi .UNINDENT .UNINDENT .SS Import the Public Key .sp To encrypt secrets, copy the public key to your local machine and run: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C $ gpg \-\-import exported_pubkey.gpg .ft P .fi .UNINDENT .UNINDENT .sp To generate a cipher from a secret: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C $ echo \-n "supersecret" | gpg \-\-armor \-\-batch \-\-trust\-model always \-\-encrypt \-r .ft P .fi .UNINDENT .UNINDENT .sp To apply the renderer on a file\-by\-file basis add the following line to the top of any pillar with gpg data in it: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C #!yaml|gpg .ft P .fi .UNINDENT .UNINDENT .sp Now with your renderer configured, you can include your ciphers in your pillar data like so: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C #!yaml|gpg a\-secret: | \-\-\-\-\-BEGIN PGP MESSAGE\-\-\-\-\- Version: GnuPG v1 hQEMAweRHKaPCfNeAQf9GLTN16hCfXAbPwU6BbBK0unOc7i9/etGuVc5CyU9Q6um QuetdvQVLFO/HkrC4lgeNQdM6D9E8PKonMlgJPyUvC8ggxhj0/IPFEKmrsnv2k6+ cnEfmVexS7o/U1VOVjoyUeliMCJlAz/30RXaME49Cpi6No2+vKD8a4q4nZN1UZcG RhkhC0S22zNxOXQ38TBkmtJcqxnqT6YWKTUsjVubW3bVC+u2HGqJHu79wmwuN8tz m4wBkfCAd8Eyo2jEnWQcM4TcXiF01XPL4z4g1/9AAxh+Q4d8RIRP4fbw7ct4nCJv Gr9v2DTF7HNigIMl4ivMIn9fp+EZurJNiQskLgNbktJGAeEKYkqX5iCuB1b693hJ FKlwHiJt5yA8X2dDtfk8/Ph1Jx2TwGS+lGjlZaNqp3R1xuAZzXzZMLyZDe5+i3RJ skqmFTbOiA===Eqsm \-\-\-\-\-END PGP MESSAGE\-\-\-\-\- .ft P .fi .UNINDENT .UNINDENT .SS Encrypted CLI Pillar Data .sp New in version 2016.3.0. .sp Functions like \fBstate.highstate\fP and \fBstate.sls\fP allow for pillar data to be passed on the CLI. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt myminion state.highstate pillar="{\(aqmypillar\(aq: \(aqfoo\(aq}" .ft P .fi .UNINDENT .UNINDENT .sp Starting with the 2016.3.0 release of Salt, it is now possible for this pillar data to be GPG\-encrypted, and to use the GPG renderer to decrypt it. .SS Replacing Newlines .sp To pass encrypted pillar data on the CLI, the ciphertext must have its newlines replaced with a literal backslash\-n (\fB\en\fP), as newlines are not supported within Salt CLI arguments. There are a number of ways to do this: .sp With awk or Perl: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C # awk ciphertext=\(gaecho \-n "supersecret" | gpg \-\-armor \-\-batch \-\-trust\-model always \-\-encrypt \-r user@domain.com | awk \(aq{printf "%s\e\en",$0} END {print ""}\(aq\(ga # Perl ciphertext=\(gaecho \-n "supersecret" | gpg \-\-armor \-\-batch \-\-trust\-model always \-\-encrypt \-r user@domain.com | perl \-pe \(aqs/\en/\e\en/g\(aq\(ga .ft P .fi .UNINDENT .UNINDENT .sp With Python: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C import subprocess secret, stderr = subprocess.Popen( [\(aqgpg\(aq, \(aq\-\-armor\(aq, \(aq\-\-batch\(aq, \(aq\-\-trust\-model\(aq, \(aqalways\(aq, \(aq\-\-encrypt\(aq, \(aq\-r\(aq, \(aquser@domain.com\(aq], stdin=subprocess.PIPE, stdout=subprocess.PIPE, stderr=subprocess.PIPE).communicate(input=\(aqsupersecret\(aq) if secret: print(secret.replace(\(aq\en\(aq, r\(aq\en\(aq)) else: raise ValueError(\(aqNo ciphertext found: {0}\(aq.format(stderr)) .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C ciphertext=\(gapython /path/to/script.py\(ga .ft P .fi .UNINDENT .UNINDENT .sp The ciphertext can be included in the CLI pillar data like so: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt myminion state.sls secretstuff pillar_enc=gpg pillar="{secret_pillar: \(aq$ciphertext\(aq}" .ft P .fi .UNINDENT .UNINDENT .sp The \fBpillar_enc=gpg\fP argument tells Salt that there is GPG\-encrypted pillar data, so that the CLI pillar data is passed through the GPG renderer, which will iterate recursively though the CLI pillar dictionary to decrypt any encrypted values. .SS Encrypting the Entire CLI Pillar Dictionary .sp If several values need to be encrypted, it may be more convenient to encrypt the entire CLI pillar dictionary. Again, this can be done in several ways: .sp With awk or Perl: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C # awk ciphertext=\(gaecho \-n "{\(aqsecret_a\(aq: \(aqCorrectHorseBatteryStaple\(aq, \(aqsecret_b\(aq: \(aqGPG is fun!\(aq}" | gpg \-\-armor \-\-batch \-\-trust\-model always \-\-encrypt \-r user@domain.com | awk \(aq{printf "%s\e\en",$0} END {print ""}\(aq\(ga # Perl ciphertext=\(gaecho \-n "{\(aqsecret_a\(aq: \(aqCorrectHorseBatteryStaple\(aq, \(aqsecret_b\(aq: \(aqGPG is fun!\(aq}" | gpg \-\-armor \-\-batch \-\-trust\-model always \-\-encrypt \-r user@domain.com | perl \-pe \(aqs/\en/\e\en/g\(aq\(ga .ft P .fi .UNINDENT .UNINDENT .sp With Python: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C import subprocess pillar_data = {\(aqsecret_a\(aq: \(aqCorrectHorseBatteryStaple\(aq, \(aqsecret_b\(aq: \(aqGPG is fun!\(aq} secret, stderr = subprocess.Popen( [\(aqgpg\(aq, \(aq\-\-armor\(aq, \(aq\-\-batch\(aq, \(aq\-\-trust\-model\(aq, \(aqalways\(aq, \(aq\-\-encrypt\(aq, \(aq\-r\(aq, \(aquser@domain.com\(aq], stdin=subprocess.PIPE, stdout=subprocess.PIPE, stderr=subprocess.PIPE).communicate(input=repr(pillar_data)) if secret: print(secret.replace(\(aq\en\(aq, r\(aq\en\(aq)) else: raise ValueError(\(aqNo ciphertext found: {0}\(aq.format(stderr)) .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C ciphertext=\(gapython /path/to/script.py\(ga .ft P .fi .UNINDENT .UNINDENT .sp With the entire pillar dictionary now encrypted, it can be included in the CLI pillar data like so: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt myminion state.sls secretstuff pillar_enc=gpg pillar="$ciphertext" .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.renderers.gpg.render(gpg_data, saltenv=\(aqbase\(aq, sls=\(aq\(aq, argline=\(aq\(aq, **kwargs) Create a gpg object given a gpg_keydir, and then use it to try to decrypt the data to be rendered. .UNINDENT .SS salt.renderers.hjson .sp Hjson Renderer for Salt \fI\%http://laktak.github.io/hjson/\fP .INDENT 0.0 .TP .B salt.renderers.hjson.render(hjson_data, saltenv=\(aqbase\(aq, sls=\(aq\(aq, **kws) Accepts HJSON as a string or as a file object and runs it through the HJSON parser. .INDENT 7.0 .TP .B Return type A Python data structure .UNINDENT .UNINDENT .SS salt.renderers.jinja .sp Jinja loading utils to enable a more powerful backend for jinja templates .sp For Jinja usage information see Understanding Jinja\&. .INDENT 0.0 .TP .B salt.renderers.jinja.render(template_file, saltenv=\(aqbase\(aq, sls=\(aq\(aq, argline=\(aq\(aq, context=None, tmplpath=None, **kws) Render the template_file, passing the functions and grains into the Jinja rendering system. .INDENT 7.0 .TP .B Return type string .UNINDENT .UNINDENT .INDENT 0.0 .TP .B class salt.utils.jinja.SerializerExtension(environment) Yaml and Json manipulation. .sp \fBFormat filters\fP .sp Allows jsonifying or yamlifying any data structure. For example, this dataset: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C data = { \(aqfoo\(aq: True, \(aqbar\(aq: 42, \(aqbaz\(aq: [1, 2, 3], \(aqqux\(aq: 2.0 } .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C yaml = {{ data|yaml }} json = {{ data|json }} python = {{ data|python }} .ft P .fi .UNINDENT .UNINDENT .sp will be rendered as: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C yaml = {bar: 42, baz: [1, 2, 3], foo: true, qux: 2.0} json = {"baz": [1, 2, 3], "foo": true, "bar": 42, "qux": 2.0} python = {\(aqbar\(aq: 42, \(aqbaz\(aq: [1, 2, 3], \(aqfoo\(aq: True, \(aqqux\(aq: 2.0} .ft P .fi .UNINDENT .UNINDENT .sp The yaml filter takes an optional flow_style parameter to control the default\-flow\-style parameter of the YAML dumper. .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C {{ data|yaml(False) }} .ft P .fi .UNINDENT .UNINDENT .sp will be rendered as: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C bar: 42 baz: \- 1 \- 2 \- 3 foo: true qux: 2.0 .ft P .fi .UNINDENT .UNINDENT .sp \fBLoad filters\fP .sp Strings and variables can be deserialized with \fBload_yaml\fP and \fBload_json\fP tags and filters. It allows one to manipulate data directly in templates, easily: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C {%\- set yaml_src = "{foo: it works}"|load_yaml %} {%\- set json_src = "{\(aqbar\(aq: \(aqfor real\(aq}"|load_json %} Dude, {{ yaml_src.foo }} {{ json_src.bar }}! .ft P .fi .UNINDENT .UNINDENT .sp will be rendered as: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C Dude, it works for real! .ft P .fi .UNINDENT .UNINDENT .sp \fBLoad tags\fP .sp Salt implements \fBload_yaml\fP and \fBload_json\fP tags. They work like the \fI\%import tag\fP, except that the document is also deserialized. .sp Syntaxes are \fB{% load_yaml as [VARIABLE] %}[YOUR DATA]{% endload %}\fP and \fB{% load_json as [VARIABLE] %}[YOUR DATA]{% endload %}\fP .sp For example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C {% load_yaml as yaml_src %} foo: it works {% endload %} {% load_json as json_src %} { "bar": "for real" } {% endload %} Dude, {{ yaml_src.foo }} {{ json_src.bar }}! .ft P .fi .UNINDENT .UNINDENT .sp will be rendered as: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C Dude, it works for real! .ft P .fi .UNINDENT .UNINDENT .sp \fBImport tags\fP .sp External files can be imported and made available as a Jinja variable. .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C {% import_yaml "myfile.yml" as myfile %} {% import_json "defaults.json" as defaults %} {% import_text "completeworksofshakespeare.txt" as poems %} .ft P .fi .UNINDENT .UNINDENT .sp \fBCatalog\fP .sp \fBimport_*\fP and \fBload_*\fP tags will automatically expose their target variable to import. This feature makes catalog of data to handle. .sp for example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C # doc1.sls {% load_yaml as var1 %} foo: it works {% endload %} {% load_yaml as var2 %} bar: for real {% endload %} .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C # doc2.sls {% from "doc1.sls" import var1, var2 as local2 %} {{ var1.foo }} {{ local2.bar }} .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.renderers.json .sp JSON Renderer for Salt .INDENT 0.0 .TP .B salt.renderers.json.render(json_data, saltenv=\(aqbase\(aq, sls=\(aq\(aq, **kws) Accepts JSON as a string or as a file object and runs it through the JSON parser. .INDENT 7.0 .TP .B Return type A Python data structure .UNINDENT .UNINDENT .SS salt.renderers.json5 .sp JSON5 Renderer for Salt .sp New in version 2016.3.0. .sp JSON5 is an unofficial extension to JSON. See \fI\%http://json5.org/\fP for more information. .sp This renderer requires the \fI\%json5 python bindings\fP, installable via pip. .INDENT 0.0 .TP .B salt.renderers.json5.render(json_data, saltenv=\(aqbase\(aq, sls=\(aq\(aq, **kws) Accepts JSON as a string or as a file object and runs it through the JSON parser. .INDENT 7.0 .TP .B Return type A Python data structure .UNINDENT .UNINDENT .SS salt.renderers.mako .sp Mako Renderer for Salt .INDENT 0.0 .TP .B salt.renderers.mako.render(template_file, saltenv=\(aqbase\(aq, sls=\(aq\(aq, context=None, tmplpath=None, **kws) Render the template_file, passing the functions and grains into the Mako rendering system. .INDENT 7.0 .TP .B Return type string .UNINDENT .UNINDENT .SS salt.renderers.msgpack .INDENT 0.0 .TP .B salt.renderers.msgpack.render(msgpack_data, saltenv=\(aqbase\(aq, sls=\(aq\(aq, **kws) Accepts a message pack string or a file object, renders said data back to a python dict. .INDENT 7.0 .TP .B Return type A Python data structure .UNINDENT .UNINDENT .SS salt.renderers.py .sp Pure python state renderer .sp The SLS file should contain a function called \fBrun\fP which returns high state data. .sp In this module, a few objects are defined for you, giving access to Salt\(aqs execution functions, grains, pillar, etc. They are: .INDENT 0.0 .IP \(bu 2 \fB__salt__\fP \- Execution functions (i.e. \fB__salt__[\(aqtest.echo\(aq](\(aqfoo\(aq)\fP) .IP \(bu 2 \fB__grains__\fP \- Grains (i.e. \fB__grains__[\(aqos\(aq]\fP) .IP \(bu 2 \fB__pillar__\fP \- Pillar data (i.e. \fB__pillar__[\(aqfoo\(aq]\fP) .IP \(bu 2 \fB__opts__\fP \- Minion configuration options .IP \(bu 2 \fB__env__\fP \- The effective salt fileserver environment (i.e. \fBbase\fP). Also referred to as a "saltenv". \fB__env__\fP should not be modified in a pure python SLS file. To use a different environment, the environment should be set when executing the state. This can be done in a couple different ways: .INDENT 2.0 .IP \(bu 2 Using the \fBsaltenv\fP argument on the salt CLI (i.e. \fBsalt \(aq*\(aq state.sls foo.bar.baz saltenv=env_name\fP). .IP \(bu 2 By adding a \fBsaltenv\fP argument to an individual state within the SLS file. In other words, adding a line like this to the state\(aqs data structure: \fB{\(aqsaltenv\(aq: \(aqenv_name\(aq}\fP .UNINDENT .IP \(bu 2 \fB__sls__\fP \- The SLS path of the file. For example, if the root of the base environment is \fB/srv/salt\fP, and the SLS file is \fB/srv/salt/foo/bar/baz.sls\fP, then \fB__sls__\fP in that file will be \fBfoo.bar.baz\fP\&. .UNINDENT .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C #!py def run(): config = {} if __grains__[\(aqos\(aq] == \(aqUbuntu\(aq: user = \(aqubuntu\(aq group = \(aqubuntu\(aq home = \(aq/home/{0}\(aq.format(user) else: user = \(aqroot\(aq group = \(aqroot\(aq home = \(aq/root/\(aq config[\(aqs3cmd\(aq] = { \(aqpkg\(aq: [ \(aqinstalled\(aq, {\(aqname\(aq: \(aqs3cmd\(aq}, ], } config[home + \(aq/.s3cfg\(aq] = { \(aqfile.managed\(aq: [ {\(aqsource\(aq: \(aqsalt://s3cfg/templates/s3cfg\(aq}, {\(aqtemplate\(aq: \(aqjinja\(aq}, {\(aquser\(aq: user}, {\(aqgroup\(aq: group}, {\(aqmode\(aq: 600}, {\(aqcontext\(aq: { \(aqaws_key\(aq: __pillar__[\(aqAWS_ACCESS_KEY_ID\(aq], \(aqaws_secret_key\(aq: __pillar__[\(aqAWS_SECRET_ACCESS_KEY\(aq], }, }, ], } return config .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.renderers.py.render(template, saltenv=\(aqbase\(aq, sls=\(aq\(aq, tmplpath=None, **kws) Render the python module\(aqs components .INDENT 7.0 .TP .B Return type string .UNINDENT .UNINDENT .SS salt.renderers.pydsl .sp A Python\-based DSL .INDENT 0.0 .TP .B maintainer Jack Kuan <\fI\%kjkuan@gmail.com\fP> .TP .B maturity new .TP .B platform all .UNINDENT .sp The \fIpydsl\fP renderer allows one to author salt formulas (.sls files) in pure Python using a DSL that\(aqs easy to write and easy to read. Here\(aqs an example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C #!pydsl apache = state(\(aqapache\(aq) apache.pkg.installed() apache.service.running() state(\(aq/var/www/index.html\(aq) \e .file(\(aqmanaged\(aq, source=\(aqsalt://webserver/index.html\(aq) \e .require(pkg=\(aqapache\(aq) .ft P .fi .UNINDENT .UNINDENT .sp Notice that any Python code is allow in the file as it\(aqs really a Python module, so you have the full power of Python at your disposal. In this module, a few objects are defined for you, including the usual (with \fB__\fP added) \fB__salt__\fP dictionary, \fB__grains__\fP, \fB__pillar__\fP, \fB__opts__\fP, \fB__env__\fP, and \fB__sls__\fP, plus a few more: .INDENT 0.0 .INDENT 3.5 \fB__file__\fP .INDENT 0.0 .INDENT 3.5 local file system path to the sls module. .UNINDENT .UNINDENT .sp \fB__pydsl__\fP .INDENT 0.0 .INDENT 3.5 Salt PyDSL object, useful for configuring DSL behavior per sls rendering. .UNINDENT .UNINDENT .sp \fBinclude\fP .INDENT 0.0 .INDENT 3.5 Salt PyDSL function for creating include\-declaration\(aqs. .UNINDENT .UNINDENT .sp \fBextend\fP .INDENT 0.0 .INDENT 3.5 Salt PyDSL function for creating extend\-declaration\(aqs. .UNINDENT .UNINDENT .sp \fBstate\fP .INDENT 0.0 .INDENT 3.5 Salt PyDSL function for creating ID\-declaration\(aqs. .UNINDENT .UNINDENT .UNINDENT .UNINDENT .sp A state ID\-declaration is created with a \fBstate(id)\fP function call. Subsequent \fBstate(id)\fP call with the same id returns the same object. This singleton access pattern applies to all declaration objects created with the DSL. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C state(\(aqexample\(aq) assert state(\(aqexample\(aq) is state(\(aqexample\(aq) assert state(\(aqexample\(aq).cmd is state(\(aqexample\(aq).cmd assert state(\(aqexample\(aq).cmd.running is state(\(aqexample\(aq).cmd.running .ft P .fi .UNINDENT .UNINDENT .sp The \fIid\fP argument is optional. If omitted, an UUID will be generated and used as the \fIid\fP\&. .sp \fBstate(id)\fP returns an object under which you can create a state\-declaration object by accessing an attribute named after \fIany\fP state module available in Salt. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C state(\(aqexample\(aq).cmd state(\(aqexample\(aq).file state(\(aqexample\(aq).pkg \&... .ft P .fi .UNINDENT .UNINDENT .sp Then, a function\-declaration object can be created from a state\-declaration object by one of the following two ways: .INDENT 0.0 .IP 1. 3 by calling a method named after the state function on the state\-declaration object. .UNINDENT .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C state(\(aqexample\(aq).file.managed(...) .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .IP 2. 3 by directly calling the attribute named for the state\-declaration, and supplying the state function name as the first argument. .UNINDENT .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C state(\(aqexample\(aq).file(\(aqmanaged\(aq, ...) .ft P .fi .UNINDENT .UNINDENT .sp With either way of creating a function\-declaration object, any function\-arg\-declaration\(aqs can be passed as keyword arguments to the call. Subsequent calls of a function\-declaration will update the arg declarations. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C state(\(aqexample\(aq).file(\(aqmanaged\(aq, source=\(aqsalt://webserver/index.html\(aq) state(\(aqexample\(aq).file.managed(source=\(aqsalt://webserver/index.html\(aq) .ft P .fi .UNINDENT .UNINDENT .sp As a shortcut, the special \fIname\fP argument can also be passed as the first or second positional argument depending on the first or second way of calling the state\-declaration object. In the following two examples \fIls \-la\fP is the \fIname\fP argument. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C state(\(aqexample\(aq).cmd.run(\(aqls \-la\(aq, cwd=\(aq/\(aq) state(\(aqexample\(aq).cmd(\(aqrun\(aq, \(aqls \-la\(aq, cwd=\(aq/\(aq) .ft P .fi .UNINDENT .UNINDENT .sp Finally, a requisite\-declaration object with its requisite\-reference\(aqs can be created by invoking one of the requisite methods (see State Requisites) on either a function\-declaration object or a state\-declaration object. The return value of a requisite call is also a function\-declaration object, so you can chain several requisite calls together. .sp Arguments to a requisite call can be a list of state\-declaration objects and/or a set of keyword arguments whose names are state modules and values are IDs of ID\-declaration\(aqs or names of name\-declaration\(aqs. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C apache2 = state(\(aqapache2\(aq) apache2.pkg.installed() state(\(aqlibapache2\-mod\-wsgi\(aq).pkg.installed() # you can call requisites on function declaration apache2.service.running() \e .require(apache2.pkg, pkg=\(aqlibapache2\-mod\-wsgi\(aq) \e .watch(file=\(aq/etc/apache2/httpd.conf\(aq) # or you can call requisites on state declaration. # this actually creates an anonymous function declaration object # to add the requisites. apache2.service.require(state(\(aqlibapache2\-mod\-wsgi\(aq).pkg, pkg=\(aqapache2\(aq) \e .watch(file=\(aq/etc/apache2/httpd.conf\(aq) # we still need to set the name of the function declaration. apache2.service.running() .ft P .fi .UNINDENT .UNINDENT .sp include\-declaration objects can be created with the \fBinclude\fP function, while extend\-declaration objects can be created with the \fBextend\fP function, whose arguments are just function\-declaration objects. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C include(\(aqedit.vim\(aq, \(aqhttp.server\(aq) extend(state(\(aqapache2\(aq).service.watch(file=\(aq/etc/httpd/httpd.conf\(aq) .ft P .fi .UNINDENT .UNINDENT .sp The \fBinclude\fP function, by default, causes the included sls file to be rendered as soon as the \fBinclude\fP function is called. It returns a list of rendered module objects; sls files not rendered with the pydsl renderer return \fBNone\fP\(aqs. This behavior creates no include\-declaration\(aqs in the resulting high state data structure. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C import types # including multiple sls returns a list. _, mod = include(\(aqa\-non\-pydsl\-sls\(aq, \(aqa\-pydsl\-sls\(aq) assert _ is None assert isinstance(slsmods[1], types.ModuleType) # including a single sls returns a single object mod = include(\(aqa\-pydsl\-sls\(aq) # myfunc is a function that calls state(...) to create more states. mod.myfunc(1, 2, "three") .ft P .fi .UNINDENT .UNINDENT .sp Notice how you can define a reusable function in your pydsl sls module and then call it via the module returned by \fBinclude\fP\&. .sp It\(aqs still possible to do late includes by passing the \fBdelayed=True\fP keyword argument to \fBinclude\fP\&. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C include(\(aqedit.vim\(aq, \(aqhttp.server\(aq, delayed=True) .ft P .fi .UNINDENT .UNINDENT .sp Above will just create a include\-declaration in the rendered result, and such call always returns \fBNone\fP\&. .SS Special integration with the \fIcmd\fP state .sp Taking advantage of rendering a Python module, PyDSL allows you to declare a state that calls a pre\-defined Python function when the state is executed. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C greeting = "hello world" def helper(something, *args, **kws): print greeting # hello world print something, args, kws # test123 [\(aqa\(aq, \(aqb\(aq, \(aqc\(aq] {\(aqx\(aq: 1, \(aqy\(aq: 2} state().cmd.call(helper, "test123", \(aqa\(aq, \(aqb\(aq, \(aqc\(aq, x=1, y=2) .ft P .fi .UNINDENT .UNINDENT .sp The \fIcmd.call\fP state function takes care of calling our \fBhelper\fP function with the arguments we specified in the states, and translates the return value of our function into a structure expected by the state system. See \fBsalt.states.cmd.call()\fP for more information. .SS Implicit ordering of states .sp Salt states are explicitly ordered via requisite\-declaration\(aqs. However, with \fIpydsl\fP it\(aqs possible to let the renderer track the order of creation for function\-declaration objects, and implicitly add \fBrequire\fP requisites for your states to enforce the ordering. This feature is enabled by setting the \fBordered\fP option on \fB__pydsl__\fP\&. .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 this feature is only available if your minions are using Python >= 2.7. .UNINDENT .UNINDENT .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C include(\(aqsome.sls.file\(aq) A = state(\(aqA\(aq).cmd.run(cwd=\(aq/var/tmp\(aq) extend(A) __pydsl__.set(ordered=True) for i in range(10): i = str(i) state(i).cmd.run(\(aqecho \(aq+i, cwd=\(aq/\(aq) state(\(aq1\(aq).cmd.run(\(aqecho one\(aq) state(\(aq2\(aq).cmd.run(name=\(aqecho two\(aq) .ft P .fi .UNINDENT .UNINDENT .sp Notice that the \fBordered\fP option needs to be set after any \fBextend\fP calls. This is to prevent \fIpydsl\fP from tracking the creation of a state function that\(aqs passed to an \fBextend\fP call. .sp Above example should create states from \fB0\fP to \fB9\fP that will output \fB0\fP, \fBone\fP, \fBtwo\fP, \fB3\fP, ... \fB9\fP, in that order. .sp It\(aqs important to know that \fIpydsl\fP tracks the \fIcreations\fP of function\-declaration objects, and automatically adds a \fBrequire\fP requisite to a function\-declaration object that requires the last function\-declaration object created before it in the sls file. .sp This means later calls (perhaps to update the function\(aqs function\-arg\-declaration) to a previously created function declaration will not change the order. .SS Render time state execution .sp When Salt processes a salt formula file, the file is rendered to salt\(aqs high state data representation by a renderer before the states can be executed. In the case of the \fIpydsl\fP renderer, the .sls file is executed as a python module as it is being rendered which makes it easy to execute a state at render time. In \fIpydsl\fP, executing one or more states at render time can be done by calling a configured ID\-declaration object. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C #!pydsl s = state() # save for later invocation # configure it s.cmd.run(\(aqecho at render time\(aq, cwd=\(aq/\(aq) s.file.managed(\(aqtarget.txt\(aq, source=\(aqsalt://source.txt\(aq) s() # execute the two states now .ft P .fi .UNINDENT .UNINDENT .sp Once an ID\-declaration is called at render time it is detached from the sls module as if it was never defined. .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 If \fIimplicit ordering\fP is enabled (i.e., via \fB__pydsl__.set(ordered=True)\fP) then the \fIfirst\fP invocation of a ID\-declaration object must be done before a new function\-declaration is created. .UNINDENT .UNINDENT .SS Integration with the stateconf renderer .sp The \fBsalt.renderers.stateconf\fP renderer offers a few interesting features that can be leveraged by the \fIpydsl\fP renderer. In particular, when using with the \fIpydsl\fP renderer, we are interested in \fIstateconf\fP\(aqs sls namespacing feature (via dot\-prefixed id declarations), as well as, the automatic \fIstart\fP and \fIgoal\fP states generation. .sp Now you can use \fIpydsl\fP with \fIstateconf\fP like this: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C #!pydsl|stateconf \-ps include(\(aqxxx\(aq, \(aqyyy\(aq) # ensure that states in xxx run BEFORE states in this file. extend(state(\(aq.start\(aq).stateconf.require(stateconf=\(aqxxx::goal\(aq)) # ensure that states in yyy run AFTER states in this file. extend(state(\(aq.goal\(aq).stateconf.require_in(stateconf=\(aqyyy::start\(aq)) __pydsl__.set(ordered=True) \&... .ft P .fi .UNINDENT .UNINDENT .sp \fB\-s\fP enables the generation of a stateconf \fIstart\fP state, and \fB\-p\fP lets us pipe high state data rendered by \fIpydsl\fP to \fIstateconf\fP\&. This example shows that by \fBrequire\fP\-ing or \fBrequire_in\fP\-ing the included sls\(aq \fIstart\fP or \fIgoal\fP states, it\(aqs possible to ensure that the included sls files can be made to execute before or after a state in the including sls file. .SS Importing custom Python modules .sp To use a custom Python module inside a PyDSL state, place the module somewhere that it can be loaded by the Salt loader, such as \fI_modules\fP in the \fI/srv/salt\fP directory. .sp Then, copy it to any minions as necessary by using \fIsaltutil.sync_modules\fP\&. .sp To import into a PyDSL SLS, one must bypass the Python importer and insert it manually by getting a reference from Python\(aqs \fIsys.modules\fP dictionary. .sp For example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C #!pydsl|stateconf \-ps def main(): my_mod = sys.modules[\(aqsalt.loaded.ext.module.my_mod\(aq] .ft P .fi .UNINDENT .UNINDENT .SS salt.renderers.pyobjects .sp Python renderer that includes a Pythonic Object based interface .INDENT 0.0 .TP .B maintainer Evan Borgstrom <\fI\%evan@borgstrom.ca\fP> .UNINDENT .sp Let\(aqs take a look at how you use pyobjects in a state file. Here\(aqs a quick example that ensures the \fB/tmp\fP directory is in the correct state. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C #!pyobjects File.managed("/tmp", user=\(aqroot\(aq, group=\(aqroot\(aq, mode=\(aq1777\(aq) .ft P .fi .UNINDENT .UNINDENT .sp Nice and Pythonic! .sp By using the "shebang" syntax to switch to the pyobjects renderer we can now write our state data using an object based interface that should feel at home to python developers. You can import any module and do anything that you\(aqd like (with caution, importing sqlalchemy, django or other large frameworks has not been tested yet). Using the pyobjects renderer is exactly the same as using the built\-in Python renderer with the exception that pyobjects provides you with an object based interface for generating state data. .SS Creating state data .sp Pyobjects takes care of creating an object for each of the available states on the minion. Each state is represented by an object that is the CamelCase version of its name (i.e. \fBFile\fP, \fBService\fP, \fBUser\fP, etc), and these objects expose all of their available state functions (i.e. \fBFile.managed\fP, \fBService.running\fP, etc). .sp The name of the state is split based upon underscores (\fB_\fP), then each part is capitalized and finally the parts are joined back together. .sp Some examples: .INDENT 0.0 .IP \(bu 2 \fBpostgres_user\fP becomes \fBPostgresUser\fP .IP \(bu 2 \fBssh_known_hosts\fP becomes \fBSshKnownHosts\fP .UNINDENT .SS Context Managers and requisites .sp How about something a little more complex. Here we\(aqre going to get into the core of how to use pyobjects to write states. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C #!pyobjects with Pkg.installed("nginx"): Service.running("nginx", enable=True) with Service("nginx", "watch_in"): File.managed("/etc/nginx/conf.d/mysite.conf", owner=\(aqroot\(aq, group=\(aqroot\(aq, mode=\(aq0444\(aq, source=\(aqsalt://nginx/mysite.conf\(aq) .ft P .fi .UNINDENT .UNINDENT .sp The objects that are returned from each of the magic method calls are setup to be used a Python context managers (\fBwith\fP) and when you use them as such all declarations made within the scope will \fBautomatically\fP use the enclosing state as a requisite! .sp The above could have also been written use direct requisite statements as. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C #!pyobjects Pkg.installed("nginx") Service.running("nginx", enable=True, require=Pkg("nginx")) File.managed("/etc/nginx/conf.d/mysite.conf", owner=\(aqroot\(aq, group=\(aqroot\(aq, mode=\(aq0444\(aq, source=\(aqsalt://nginx/mysite.conf\(aq, watch_in=Service("nginx")) .ft P .fi .UNINDENT .UNINDENT .sp You can use the direct requisite statement for referencing states that are generated outside of the current file. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C #!pyobjects # some\-other\-package is defined in some other state file Pkg.installed("nginx", require=Pkg("some\-other\-package")) .ft P .fi .UNINDENT .UNINDENT .sp The last thing that direct requisites provide is the ability to select which of the SaltStack requisites you want to use (require, require_in, watch, watch_in, use & use_in) when using the requisite as a context manager. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C #!pyobjects with Service("my\-service", "watch_in"): ... .ft P .fi .UNINDENT .UNINDENT .sp The above example would cause all declarations inside the scope of the context manager to automatically have their \fBwatch_in\fP set to \fBService("my\-service")\fP\&. .SS Including and Extending .sp To include other states use the \fBinclude()\fP function. It takes one name per state to include. .sp To extend another state use the \fBextend()\fP function on the name when creating a state. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C #!pyobjects include(\(aqhttp\(aq, \(aqssh\(aq) Service.running(extend(\(aqapache\(aq), watch=[File(\(aq/etc/httpd/extra/httpd\-vhosts.conf\(aq)]) .ft P .fi .UNINDENT .UNINDENT .SS Importing from other state files .sp Like any Python project that grows you will likely reach a point where you want to create reusability in your state tree and share objects between state files, Map Data (described below) is a perfect example of this. .sp To facilitate this Python\(aqs \fBimport\fP statement has been augmented to allow for a special case when working with a Salt state tree. If you specify a Salt url (\fBsalt://...\fP) as the target for importing from then the pyobjects renderer will take care of fetching the file for you, parsing it with all of the pyobjects features available and then place the requested objects in the global scope of the template being rendered. .sp This works for all types of import statements; \fBimport X\fP, \fBfrom X import Y\fP, and \fBfrom X import Y as Z\fP\&. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C #!pyobjects import salt://myfile.sls from salt://something/data.sls import Object from salt://something/data.sls import Object as Other .ft P .fi .UNINDENT .UNINDENT .sp See the Map Data section for a more practical use. .sp Caveats: .INDENT 0.0 .IP \(bu 2 Imported objects are ALWAYS put into the global scope of your template, regardless of where your import statement is. .UNINDENT .SS Salt object .sp In the spirit of the object interface for creating state data pyobjects also provides a simple object interface to the \fB__salt__\fP object. .sp A function named \fBsalt\fP exists in scope for your sls files and will dispatch its attributes to the \fB__salt__\fP dictionary. .sp The following lines are functionally equivalent: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C #!pyobjects ret = salt.cmd.run(bar) ret = __salt__[\(aqcmd.run\(aq](bar) .ft P .fi .UNINDENT .UNINDENT .SS Pillar, grain, mine & config data .sp Pyobjects provides shortcut functions for calling \fBpillar.get\fP, \fBgrains.get\fP, \fBmine.get\fP & \fBconfig.get\fP on the \fB__salt__\fP object. This helps maintain the readability of your state files. .sp Each type of data can be access by a function of the same name: \fBpillar()\fP, \fBgrains()\fP, \fBmine()\fP and \fBconfig()\fP\&. .sp The following pairs of lines are functionally equivalent: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C #!pyobjects value = pillar(\(aqfoo:bar:baz\(aq, \(aqqux\(aq) value = __salt__[\(aqpillar.get\(aq](\(aqfoo:bar:baz\(aq, \(aqqux\(aq) value = grains(\(aqpkg:apache\(aq) value = __salt__[\(aqgrains.get\(aq](\(aqpkg:apache\(aq) value = mine(\(aqos:Fedora\(aq, \(aqnetwork.interfaces\(aq, \(aqgrain\(aq) value = __salt__[\(aqmine.get\(aq](\(aqos:Fedora\(aq, \(aqnetwork.interfaces\(aq, \(aqgrain\(aq) value = config(\(aqfoo:bar:baz\(aq, \(aqqux\(aq) value = __salt__[\(aqconfig.get\(aq](\(aqfoo:bar:baz\(aq, \(aqqux\(aq) .ft P .fi .UNINDENT .UNINDENT .SS Map Data .sp When building complex states or formulas you often need a way of building up a map of data based on grain data. The most common use of this is tracking the package and service name differences between distributions. .sp To build map data using pyobjects we provide a class named Map that you use to build your own classes with inner classes for each set of values for the different grain matches. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C #!pyobjects class Samba(Map): merge = \(aqsamba:lookup\(aq class Debian: server = \(aqsamba\(aq client = \(aqsamba\-client\(aq service = \(aqsamba\(aq class Ubuntu: __grain__ = \(aqos\(aq service = \(aqsmbd\(aq class RedHat: server = \(aqsamba\(aq client = \(aqsamba\(aq service = \(aqsmb\(aq .ft P .fi .UNINDENT .UNINDENT .sp To use this new data you can import it into your state file and then access your attributes. To access the data in the map you simply access the attribute name on the base class that is extending Map. Assuming the above Map was in the file \fBsamba/map.sls\fP, you could do the following. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C #!pyobjects from salt://samba/map.sls import Samba with Pkg.installed("samba", names=[Samba.server, Samba.client]): Service.running("samba", name=Samba.service) .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .TP .B class salt.renderers.pyobjects.PyobjectsModule(name, attrs) This provides a wrapper for bare imports. .UNINDENT .INDENT 0.0 .TP .B salt.renderers.pyobjects.load_states() This loads our states into the salt __context__ .UNINDENT .SS salt.renderers.stateconf .INDENT 0.0 .TP .B maintainer Jack Kuan <\fI\%kjkuan@gmail.com\fP> .TP .B maturity new .TP .B platform all .UNINDENT .sp This module provides a custom renderer that processes a salt file with a specified templating engine (e.g. Jinja) and a chosen data renderer (e.g. YAML), extracts arguments for any \fBstateconf.set\fP state, and provides the extracted arguments (including Salt\-specific args, such as \fBrequire\fP, etc) as template context. The goal is to make writing reusable/configurable/parameterized salt files easier and cleaner. .sp To use this renderer, either set it as the default renderer via the \fBrenderer\fP option in master/minion\(aqs config, or use the shebang line in each individual sls file, like so: \fB#!stateconf\fP\&. Note, due to the way this renderer works, it must be specified as the first renderer in a render pipeline. That is, you cannot specify \fB#!mako|yaml|stateconf\fP, for example. Instead, you specify them as renderer arguments: \fB#!stateconf mako . yaml\fP\&. .sp Here\(aqs a list of features enabled by this renderer. .INDENT 0.0 .IP \(bu 2 Prefixes any state id (declaration or reference) that starts with a dot (\fB\&.\fP) to avoid duplicated state ids when the salt file is included by other salt files. .sp For example, in the \fIsalt://some/file.sls\fP, a state id such as \fB\&.sls_params\fP will be turned into \fBsome.file::sls_params\fP\&. Example: .INDENT 2.0 .INDENT 3.5 .sp .nf .ft C #!stateconf yaml . jinja \&.vim: pkg.installed .ft P .fi .UNINDENT .UNINDENT .sp Above will be translated into: .INDENT 2.0 .INDENT 3.5 .sp .nf .ft C some.file::vim: pkg.installed: \- name: vim .ft P .fi .UNINDENT .UNINDENT .sp Notice how that if a state under a dot\-prefixed state id has no \fBname\fP argument then one will be added automatically by using the state id with the leading dot stripped off. .sp The leading dot trick can be used with extending state ids as well, so you can include relatively and extend relatively. For example, when extending a state in \fIsalt://some/other_file.sls\fP, e.g.: .INDENT 2.0 .INDENT 3.5 .sp .nf .ft C #!stateconf yaml . jinja include: \- .file extend: .file::sls_params: stateconf.set: \- name1: something .ft P .fi .UNINDENT .UNINDENT .sp Above will be pre\-processed into: .INDENT 2.0 .INDENT 3.5 .sp .nf .ft C include: \- some.file extend: some.file::sls_params: stateconf.set: \- name1: something .ft P .fi .UNINDENT .UNINDENT .IP \(bu 2 Adds a \fBsls_dir\fP context variable that expands to the directory containing the rendering salt file. So, you can write \fBsalt://{{sls_dir}}/...\fP to reference templates files used by your salt file. .IP \(bu 2 Recognizes the special state function, \fBstateconf.set\fP, that configures a default list of named arguments usable within the template context of the salt file. Example: .INDENT 2.0 .INDENT 3.5 .sp .nf .ft C #!stateconf yaml . jinja \&.sls_params: stateconf.set: \- name1: value1 \- name2: value2 \- name3: \- value1 \- value2 \- value3 \- require_in: \- cmd: output # \-\-\- end of state config \-\-\- \&.output: cmd.run: \- name: | echo \(aqname1={{sls_params.name1}} name2={{sls_params.name2}} name3[1]={{sls_params.name3[1]}} \(aq .ft P .fi .UNINDENT .UNINDENT .sp This even works with \fBinclude\fP + \fBextend\fP so that you can override the default configured arguments by including the salt file and then \fBextend\fP the \fBstateconf.set\fP states that come from the included salt file. (\fIIMPORTANT: Both the included and the extending sls files must use the stateconf renderer for this \(ga\(gaextend\(ga\(ga to work!\fP) .sp Notice that the end of configuration marker (\fB# \-\-\- end of state config \-\-\fP) is needed to separate the use of \(aqstateconf.set\(aq form the rest of your salt file. The regex that matches such marker can be configured via the \fBstateconf_end_marker\fP option in your master or minion config file. .sp Sometimes, it is desirable to set a default argument value that\(aqs based on earlier arguments in the same \fBstateconf.set\fP\&. For example, it may be tempting to do something like this: .INDENT 2.0 .INDENT 3.5 .sp .nf .ft C #!stateconf yaml . jinja \&.apache: stateconf.set: \- host: localhost \- port: 1234 \- url: \(aqhttp://{{host}}:{{port}}/\(aq # \-\-\- end of state config \-\-\- \&.test: cmd.run: \- name: echo \(aq{{apache.url}}\(aq \- cwd: / .ft P .fi .UNINDENT .UNINDENT .sp However, this won\(aqt work. It can however be worked around like so: .INDENT 2.0 .INDENT 3.5 .sp .nf .ft C #!stateconf yaml . jinja \&.apache: stateconf.set: \- host: localhost \- port: 1234 {# \- url: \(aqhttp://{{host}}:{{port}}/\(aq #} # \-\-\- end of state config \-\-\- # {{ apache.setdefault(\(aqurl\(aq, "http://%(host)s:%(port)s/" % apache) }} \&.test: cmd.run: \- name: echo \(aq{{apache.url}}\(aq \- cwd: / .ft P .fi .UNINDENT .UNINDENT .IP \(bu 2 Adds support for relative include and exclude of .sls files. Example: .INDENT 2.0 .INDENT 3.5 .sp .nf .ft C #!stateconf yaml . jinja include: \- .apache \- .db.mysql \- ..app.django exclude: \- sls: .users .ft P .fi .UNINDENT .UNINDENT .sp If the above is written in a salt file at \fIsalt://some/where.sls\fP then it will include \fIsalt://some/apache.sls\fP, \fIsalt://some/db/mysql.sls\fP and \fIsalt://app/django.sls\fP, and exclude \fIsalt://some/users.ssl\fP\&. Actually, it does that by rewriting the above \fBinclude\fP and \fBexclude\fP into: .INDENT 2.0 .INDENT 3.5 .sp .nf .ft C include: \- some.apache \- some.db.mysql \- app.django exclude: \- sls: some.users .ft P .fi .UNINDENT .UNINDENT .IP \(bu 2 Optionally (enabled by default, \fIdisable\fP via the \fI\-G\fP renderer option, e.g. in the shebang line: \fB#!stateconf \-G\fP), generates a \fBstateconf.set\fP goal state (state id named as \fB\&.goal\fP by default, configurable via the master/minion config option, \fBstateconf_goal_state\fP) that requires all other states in the salt file. Note, the \fB\&.goal\fP state id is subject to dot\-prefix rename rule mentioned earlier. .sp Such goal state is intended to be required by some state in an including salt file. For example, in your webapp salt file, if you include a sls file that is supposed to setup Tomcat, you might want to make sure that all states in the Tomcat sls file will be executed before some state in the webapp sls file. .IP \(bu 2 Optionally (enable via the \fI\-o\fP renderer option, e.g. in the shebang line: \fB#!stateconf \-o\fP), orders the states in a sls file by adding a \fBrequire\fP requisite to each state such that every state requires the state defined just before it. The order of the states here is the order they are defined in the sls file. (Note: this feature is only available if your minions are using Python >= 2.7. For Python2.6, it should also work if you install the \fIordereddict\fP module from PyPI) .sp By enabling this feature, you are basically agreeing to author your sls files in a way that gives up the explicit (or implicit?) ordering imposed by the use of \fBrequire\fP, \fBwatch\fP, \fBrequire_in\fP or \fBwatch_in\fP requisites, and instead, you rely on the order of states you define in the sls files. This may or may not be a better way for you. However, if there are many states defined in a sls file, then it tends to be easier to see the order they will be executed with this feature. .sp You are still allowed to use all the requisites, with a few restrictions. You cannot \fBrequire\fP or \fBwatch\fP a state defined \fIafter\fP the current state. Similarly, in a state, you cannot \fBrequire_in\fP or \fBwatch_in\fP a state defined \fIbefore\fP it. Breaking any of the two restrictions above will result in a state loop. The renderer will check for such incorrect uses if this feature is enabled. .sp Additionally, \fBnames\fP declarations cannot be used with this feature because the way they are compiled into low states make it impossible to guarantee the order in which they will be executed. This is also checked by the renderer. As a workaround for not being able to use \fBnames\fP, you can achieve the same effect, by generate your states with the template engine available within your sls file. .sp Finally, with the use of this feature, it becomes possible to easily make an included sls file execute all its states \fIafter\fP some state (say, with id \fBX\fP) in the including sls file. All you have to do is to make state, \fBX\fP, \fBrequire_in\fP the first state defined in the included sls file. .UNINDENT .sp When writing sls files with this renderer, one should avoid using what can be defined in a \fBname\fP argument of a state as the state\(aqs id. That is, avoid writing states like this: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C /path/to/some/file: file.managed: \- source: salt://some/file cp /path/to/some/file file2: cmd.run: \- cwd: / \- require: \- file: /path/to/some/file .ft P .fi .UNINDENT .UNINDENT .sp Instead, define the state id and the \fBname\fP argument separately for each state. Also, the ID should be something meaningful and easy to reference within a requisite (which is a good habit anyway, and such extra indirection would also makes the sls file easier to modify later). Thus, the above states should be written like this: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C add\-some\-file: file.managed: \- name: /path/to/some/file \- source: salt://some/file copy\-files: cmd.run: \- name: cp /path/to/some/file file2 \- cwd: / \- require: \- file: add\-some\-file .ft P .fi .UNINDENT .UNINDENT .sp Moreover, when referencing a state from a requisite, you should reference the state\(aqs id plus the state name rather than the state name plus its \fBname\fP argument. (Yes, in the above example, you can actually \fBrequire\fP the \fBfile: /path/to/some/file\fP, instead of the \fBfile: add\-some\-file\fP). The reason is that this renderer will re\-write or rename state id\(aqs and their references for state id\(aqs prefixed with \fB\&.\fP\&. So, if you reference \fBname\fP then there\(aqs no way to reliably rewrite such reference. .SS salt.renderers.wempy .INDENT 0.0 .TP .B salt.renderers.wempy.render(template_file, saltenv=\(aqbase\(aq, sls=\(aq\(aq, argline=\(aq\(aq, context=None, **kws) Render the data passing the functions and grains into the rendering system .INDENT 7.0 .TP .B Return type string .UNINDENT .UNINDENT .SS salt.renderers.yaml .SS Understanding YAML .sp The default renderer for SLS files is the YAML renderer. YAML is a markup language with many powerful features. However, Salt uses a small subset of YAML that maps over very commonly used data structures, like lists and dictionaries. It is the job of the YAML renderer to take the YAML data structure and compile it into a Python data structure for use by Salt. .sp Though YAML syntax may seem daunting and terse at first, there are only three very simple rules to remember when writing YAML for SLS files. .SS Rule One: Indentation .sp YAML uses a fixed indentation scheme to represent relationships between data layers. Salt requires that the indentation for each level consists of exactly two spaces. Do not use tabs. .SS Rule Two: Colons .sp Python dictionaries are, of course, simply key\-value pairs. Users from other languages may recognize this data type as hashes or associative arrays. .sp Dictionary keys are represented in YAML as strings terminated by a trailing colon. Values are represented by either a string following the colon, separated by a space: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C my_key: my_value .ft P .fi .UNINDENT .UNINDENT .sp In Python, the above maps to: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C {\(aqmy_key\(aq: \(aqmy_value\(aq} .ft P .fi .UNINDENT .UNINDENT .sp Dictionaries can be nested: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C first_level_dict_key: second_level_dict_key: value_in_second_level_dict .ft P .fi .UNINDENT .UNINDENT .sp And in Python: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C {\(aqfirst_level_dict_key\(aq: {\(aqsecond_level_dict_key\(aq: \(aqvalue_in_second_level_dict\(aq } .ft P .fi .UNINDENT .UNINDENT .SS Rule Three: Dashes .sp To represent lists of items, a single dash followed by a space is used. Multiple items are a part of the same list as a function of their having the same level of indentation. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C \- list_value_one \- list_value_two \- list_value_three .ft P .fi .UNINDENT .UNINDENT .sp Lists can be the value of a key\-value pair. This is quite common in Salt: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C my_dictionary: \- list_value_one \- list_value_two \- list_value_three .ft P .fi .UNINDENT .UNINDENT .SS Reference .sp YAML Renderer for Salt .sp For YAML usage information see Understanding YAML\&. .INDENT 0.0 .TP .B salt.renderers.yaml.get_yaml_loader(argline) Return the ordered dict yaml loader .UNINDENT .INDENT 0.0 .TP .B salt.renderers.yaml.render(yaml_data, saltenv=\(aqbase\(aq, sls=\(aq\(aq, argline=\(aq\(aq, **kws) Accepts YAML as a string or as a file object and runs it through the YAML parser. .INDENT 7.0 .TP .B Return type A Python data structure .UNINDENT .UNINDENT .SS salt.renderers.yamlex .sp YAMLEX renderer is a replacement of the YAML renderer. It\(aqs 100% YAML with a pinch of Salt magic: .INDENT 0.0 .IP \(bu 2 All mappings are automatically OrderedDict .IP \(bu 2 All strings are automatically str obj .IP \(bu 2 data aggregation with !aggregation yaml tag, based on the \fBsalt.utils.aggregation\fP module. .IP \(bu 2 data aggregation over documents for pillar .UNINDENT .sp Instructed aggregation within the \fB!aggregation\fP and the \fB!reset\fP tags: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C #!yamlex foo: !aggregate first foo: !aggregate second bar: !aggregate {first: foo} bar: !aggregate {second: bar} baz: !aggregate 42 qux: !aggregate default !reset qux: !aggregate my custom data .ft P .fi .UNINDENT .UNINDENT .sp is roughly equivalent to .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C foo: [first, second] bar: {first: foo, second: bar} baz: [42] qux: [my custom data] .ft P .fi .UNINDENT .UNINDENT .SS Reference .INDENT 0.0 .TP .B salt.renderers.yamlex.render(sls_data, saltenv=\(aqbase\(aq, sls=\(aq\(aq, **kws) Accepts YAML_EX as a string or as a file object and runs it through the YAML_EX parser. .INDENT 7.0 .TP .B Return type A Python data structure .UNINDENT .UNINDENT .SH USING SALT .sp This section describes the fundamental components and concepts that you need to understand to use Salt. .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. Grains are collected for the operating system, domain name, IP address, kernel, OS type, memory, and many other system properties. .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 Grain data is relatively static, though if system information changes (for example, if network settings are changed), or if a new value is assigned to a custom grain, grain data is refreshed. .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 Grains resolve to lowercase letters. For example, \fBFOO\fP, and \fBfoo\fP target the same grain. .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 configured grains on the Minion, the top file used in Pillar or during Highstate can be made very efficient. For example, consider the following configuration: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C \(aqnode_type:webserver\(aq: \- match: grain \- webserver \(aqnode_type:postgres\(aq: \- match: grain \- postgres \(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 to have defined the grain \fBnode_type\fP for the minions you wish to match. This simple example is nice, but too much of the code is similar. To go one step further, Jinja templating can be used to simplify the top file\&. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C {% set the_node_type = salt[\(aqgrains.get\(aq](\(aqnode_type\(aq, \(aq\(aq) %} {% if the_node_type %} \(aqnode_type:{{ the_node_type }}\(aq: \- match: grain \- {{ the_node_type }} {% endif %} .ft P .fi .UNINDENT .UNINDENT .sp Using Jinja templating, only one match entry needs to be defined. .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 The example above uses the \fBgrains.get\fP function to account for minions which do not have the \fBnode_type\fP grain set. .UNINDENT .UNINDENT .SS Writing Grains .sp The grains are derived by executing all of the "public" functions (i.e. those which do not begin with an underscore) found in the modules located in the Salt\(aqs core grains code, followed by those in any custom grains modules. The functions in a grains module must return a Python \fI\%dict\fP, where the dictionary keys are the names of grains, and each key\(aqs value is that value for that grain. .sp Custom grains modules should be placed in a subdirectory named \fB_grains\fP located under the \fBfile_roots\fP specified by the master config file. The default path would be \fB/srv/salt/_grains\fP\&. Custom grains modules 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 Grains modules are easy to write, and (as noted above) only need to return a dictionary. For example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C def yourfunction(): # initialize a grains dictionary grains = {} # Some code for logic that sets grains like grains[\(aqyourcustomgrain\(aq] = True grains[\(aqanothergrain\(aq] = \(aqsomevalue\(aq return grains .ft P .fi .UNINDENT .UNINDENT .sp The name of the function does not matter and will not factor into the grains data at all; only the keys/values returned become part of the grains. .SS When to Use a Custom Grain .sp Before adding new grains, consider what the data is and remember that grains should (for the most part) be static data. .sp If the data is something that is likely to change, consider using Pillar or an execution module instead. If it\(aqs a simple set of key/value pairs, pillar is a good match. If compiling the information requires that system commands be run, then putting this information in an execution module is likely a better idea. .sp Good candidates for grains are data that is useful for targeting minions in the top file or the Salt CLI. The name and data structure of the grain should be designed to support many platforms, operating systems or applications. Also, keep in mind that Jinja templating in Salt supports referencing pillar data as well as invoking functions from execution modules, so there\(aqs no need to place information in grains to make it available to Jinja templates. For example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C \&... \&... {{ salt[\(aqmodule.function_name\(aq](\(aqargument_1\(aq, \(aqargument_2\(aq) }} {{ pillar[\(aqmy_pillar_key\(aq] }} \&... \&... .ft P .fi .UNINDENT .UNINDENT .sp \fBWARNING:\fP .INDENT 0.0 .INDENT 3.5 Custom grains will not be available in the top file until after the first highstate\&. To make custom grains available on a minion\(aqs first highstate, it is recommended to use this example to ensure that the custom grains are synced when the minion starts. .UNINDENT .UNINDENT .SS Loading Custom Grains .sp If you have multiple functions specifying grains that are called from a \fBmain\fP function, be sure to prepend grain function names with an underscore. This prevents Salt from including the loaded grains from the grain functions in the final grain data structure. For example, consider this custom grain file: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C #!/usr/bin/env python def _my_custom_grain(): my_grain = {\(aqfoo\(aq: \(aqbar\(aq, \(aqhello\(aq: \(aqworld\(aq} return my_grain def main(): # initialize a grains dictionary grains = {} grains[\(aqmy_grains\(aq] = _my_custom_grain() return grains .ft P .fi .UNINDENT .UNINDENT .sp The output of this example renders like so: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C # salt\-call \-\-local grains.items local: \-\-\-\-\-\-\-\-\-\- my_grains: \-\-\-\-\-\-\-\-\-\- foo: bar hello: world .ft P .fi .UNINDENT .UNINDENT .sp However, if you don\(aqt prepend the \fBmy_custom_grain\fP function with an underscore, the function will be rendered twice by Salt in the items output: once for the \fBmy_custom_grain\fP call itself, and again when it is called in the \fBmain\fP function: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C # salt\-call \-\-local grains.items local: \-\-\-\-\-\-\-\-\-\- foo: bar hello: world my_grains: \-\-\-\-\-\-\-\-\-\- foo: bar hello: world .ft P .fi .UNINDENT .UNINDENT .SS Precedence .sp Core grains can be overridden 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 by custom grains modules synced to minions that have the same name as a core grain will override that core grain. Similarly, grains from \fB/etc/salt/minion\fP override both core grains and custom grain modules, and grains in \fB_grains\fP 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 Storing Static Data in the Pillar .sp Pillar is an interface for Salt designed to offer global values that can be distributed to 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 Pillar data is compiled on the master. Additionally, pillar data for a given minion is only accessible by the minion for which it is targeted in the pillar configuration. This makes pillar useful for storing sensitive data specific to a particular minion. .UNINDENT .UNINDENT .SS Declaring the Master Pillar .sp The Salt Master server maintains a \fBpillar_roots\fP setup that matches the structure of the \fBfile_roots\fP used in the Salt file server. Like \fBfile_roots\fP, the \fBpillar_roots\fP option mapps environments 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 conf_master:\fIpillar_roots\fP is configured just like \fBfile_roots\fP\&. For example: .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. It must not be in a subdirectory of the state tree. .sp 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 In the above top file, it is declared that in the \fBbase\fP environment, the glob matching all minions will have the pillar data found in the \fBpackages\fP pillar available to it. Assuming the \fBpillar_roots\fP value of \fB/srv/pillar\fP taken from above, the \fBpackages\fP pillar would be located at \fB/srv/pillar/packages.sls\fP\&. .sp Any number of matchers can be added to the base environment. For example, here is an expanded version of the Pillar top file stated above: .sp /srv/pillar/top.sls: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C base: \(aq*\(aq: \- packages \(aqweb*\(aq: \- vim .ft P .fi .UNINDENT .UNINDENT .sp In this expanded top file, minions that match \fBweb*\fP will have access to the \fB/srv/pillar/packages.sls\fP file, as well as the \fB/srv/pillar/vim.sls\fP file. .sp Another example shows how to use other standard top matching types to deliver specific salt pillar data to minions with different properties. .sp Here is an example using the \fBgrains\fP matcher to target pillars to minions by their \fBos\fP grain: .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 %} company: Foo Industries .ft P .fi .UNINDENT .UNINDENT .sp \fBIMPORTANT:\fP .INDENT 0.0 .INDENT 3.5 See Is Targeting using Grain Data Secure? for important security information. .UNINDENT .UNINDENT .sp The above pillar sets two key/value pairs. If a minion is running RedHat, then the \fBapache\fP key is set to \fBhttpd\fP and the \fBgit\fP key is set to the value of \fBgit\fP\&. If the minion is running Debian, those values are changed to \fBapache2\fP and \fBgit\-core\fP respectively. All minions that have this pillar targeting to them via a top file will have the key of \fBcompany\fP with a value of \fBFoo Industries\fP\&. .sp Consequently 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 Finally, the above states can utilize the values provided to them via Pillar. All pillar values targeted to a minion are available via the \(aqpillar\(aq dictionary. As seen in the above example, Jinja substitution can then be utilized to access the keys and values in the Pillar dictionary. .sp Note that you cannot just list key/value\-information in \fBtop.sls\fP\&. Instead, target a minion to a pillar file and then list the keys and values in the pillar. Here is an example top file that illustrates this point: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C base: \(aq*\(aq: \- common_pillar .ft P .fi .UNINDENT .UNINDENT .sp And the actual pillar file at \(aq/srv/pillar/common_pillar.sls\(aq: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C foo: bar boo: baz .ft P .fi .UNINDENT .UNINDENT .SS Pillar Namespace Flattening .sp The separate pillar SLS files all merge down into a single dictionary of key\-value pairs. When the same key is defined in multiple SLS files, this can result in unexpected behavior if care is not taken to how the pillar SLS files are laid out. .sp For example, given a \fBtop.sls\fP containing the following: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C base: \(aq*\(aq: \- packages \- services .ft P .fi .UNINDENT .UNINDENT .sp with \fBpackages.sls\fP containing: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C bind: bind9 .ft P .fi .UNINDENT .UNINDENT .sp and \fBservices.sls\fP containing: .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 key will only return \fBnamed\fP\&. The \fBbind9\fP value will be lost, because \fBservices.sls\fP was evaluated later. .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 Pillar files are applied in the order they are listed in the top file. Therefore conflicting keys will be overwritten in a \(aqlast one wins\(aq manner! For example, in the above scenario conflicting key values in \fBservices\fP will overwrite those in \fBpackages\fP because it\(aqs at the bottom of the list. .UNINDENT .UNINDENT .sp It can be better to structure your pillar files with more hierarchy. For example the \fBpackage.sls\fP file could be configured like so: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C packages: bind: bind9 .ft P .fi .UNINDENT .UNINDENT .sp This would make the \fBpackages\fP pillar key a nested dictionary containing a \fBbind\fP key. .SS Pillar Dictionary Merging .sp If the same pillar key is defined in multiple pillar SLS files, and the keys in both files refer to nested dictionaries, then the content from these dictionaries will be recursively merged. .sp For example, keeping the \fBtop.sls\fP the same, assume the following modifications to the pillar SLS files: .sp \fBpackages.sls\fP: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C bind: package\-name: bind9 version: 9.9.5 .ft P .fi .UNINDENT .UNINDENT .sp \fBservices.sls\fP: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C bind: port: 53 listen\-on: any .ft P .fi .UNINDENT .UNINDENT .sp The resulting pillar dictionary will be: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C $ salt\-call pillar.get bind local: \-\-\-\-\-\-\-\-\-\- listen\-on: any package\-name: bind9 port: 53 version: 9.9.5 .ft P .fi .UNINDENT .UNINDENT .sp Since both pillar SLS files contained a \fBbind\fP key which contained a nested dictionary, the pillar dictionary\(aqs \fBbind\fP key contains the combined contents of both SLS files\(aq \fBbind\fP keys. .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 In\-Memory Pillar Data vs. On\-Demand Pillar Data .sp Since compiling pillar data is computationally expensive, the minion will maintain a copy of the pillar data in memory to avoid needing to ask the master to recompile and send it a copy of the pillar data each time pillar data is requested. This in\-memory pillar data is what is returned by the \fBpillar.item\fP, \fBpillar.get\fP, and \fBpillar.raw\fP functions. .sp Also, for those writing custom execution modules, or contributing to Salt\(aqs existing execution modules, the in\-memory pillar data is available as the \fB__pillar__\fP dunder dictionary. .sp The in\-memory pillar data is generated on minion start, and can be refreshed using 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 in\-memory pillar data and will always return \fBNone\fP\&. .sp In contrast to in\-memory pillar data, certain actions trigger pillar data to be compiled to ensure that the most up\-to\-date pillar data is available. These actions include: .INDENT 0.0 .IP \(bu 2 Running states .IP \(bu 2 Running \fBpillar.items\fP .UNINDENT .sp Performing these actions will \fInot\fP refresh the in\-memory pillar data. So, if pillar data is modified, and then states are run, the states will see the updated pillar data, but \fBpillar.item\fP, \fBpillar.get\fP, and \fBpillar.raw\fP will not see this data unless refreshed using \fBsaltutil.refresh_pillar\fP\&. .SS How Pillar Environments Are Handled .sp When multiple pillar environments are used, the default behavior is for the pillar data from all environments to be merged together. The pillar dictionary will therefore contain keys from all configured environments. .sp The \fBpillarenv\fP minion config option can be used to force the minion to only consider pillar configuration from a single environment. This can be useful in cases where one needs to run states with alternate pillar data, either in a testing/QA environment or to test changes to the pillar data before pushing them live. .sp For example, assume that the following is set in the minion config file: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C pillarenv: base .ft P .fi .UNINDENT .UNINDENT .sp This would cause that minion to ignore all other pillar environments besides \fBbase\fP when compiling the in\-memory pillar data. Then, when running states, the \fBpillarenv\fP CLI argument can be used to override the minion\(aqs \fBpillarenv\fP config value: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq state.apply mystates pillarenv=testing .ft P .fi .UNINDENT .UNINDENT .sp The above command will run the states with pillar data sourced exclusively from the \fBtesting\fP environment, without modifying the in\-memory pillar data. .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 When running states, the \fBpillarenv\fP CLI option does not require a \fBpillarenv\fP option to be set in the minion config file. When \fBpillarenv\fP is left unset, as mentioned above all configured environments will be combined. Running states with \fBpillarenv=testing\fP in this case would still restrict the states\(aq pillar data to just that of the \fBtesting\fP pillar environment. .UNINDENT .UNINDENT .SS Viewing Pillar Data .sp To view pillar data, use the \fBpillar\fP execution module. This module includes several functions, each of them with their own use. These functions include: .INDENT 0.0 .IP \(bu 2 \fBpillar.item\fP \- Retrieves the value of one or more keys from the \fI\%in\-memory pillar datj\fP\&. .IP \(bu 2 \fBpillar.items\fP \- Compiles a fresh pillar dictionary and returns it, leaving the \fI\%in\-memory pillar data\fP untouched. If pillar keys are passed to this function however, this function acts like \fBpillar.item\fP and returns their values from the \fI\%in\-memory pillar data\fP\&. .IP \(bu 2 \fBpillar.raw\fP \- Like \fBpillar.items\fP, it returns the entire pillar dictionary, but from the \fI\%in\-memory pillar data\fP instead of compiling fresh pillar data. .IP \(bu 2 \fBpillar.get\fP \- Described in detail below. .UNINDENT .SS The \fBpillar.get\fP 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 dictonaries can be traversed using a colon as a 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 delimiter 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 Setting Pillar Data at the Command Line .sp Pillar data can be set at the command line like the following example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq state.apply pillar=\(aq{"cheese": "spam"}\(aq .ft P .fi .UNINDENT .UNINDENT .sp This will add a pillar key of \fBcheese\fP with its value set to \fBspam\fP\&. .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 Be aware that when sending sensitive data via pillar on the command\-line that the publication containing that data will be received by all minions and will not be restricted to the targeted minions. This may represent a security concern in some cases. .UNINDENT .UNINDENT .SS Master Config in Pillar .sp For convenience the data stored in the master configuration file can be 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. This option is disabled by default. .sp To enable the master config from being added to the pillar set \fBpillar_opts\fP to \fBTrue\fP in the minion config file: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C pillar_opts: True .ft P .fi .UNINDENT .UNINDENT .SS Minion Config in Pillar .sp Minion configuration options can be set on pillars. Any option that you want to modify, should be in the first level of the pillars, in the same way you set the options in the config file. For example, to configure the MySQL root password to be used by MySQL Salt execution module, set the following pillar variable: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C mysql.pass: hardtoguesspassword .ft P .fi .UNINDENT .UNINDENT .SS Master Provided Pillar Error .sp By default if there is an error rendering a pillar, the detailed error is hidden and replaced with: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C Rendering SLS \(aqmy.sls\(aq failed. Please see master log for details. .ft P .fi .UNINDENT .UNINDENT .sp The error is protected because it\(aqs possible to contain templating data which would give that minion information it shouldn\(aqt know, like a password! .sp To have the master provide the detailed error that could potentially carry protected data set \fBpillar_safe_render_error\fP to \fBFalse\fP: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C pillar_safe_render_error: False .ft P .fi .UNINDENT .UNINDENT .SS Pillar Walkthrough .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 This walkthrough assumes that the reader has already completed the initial Salt walkthrough\&. .UNINDENT .UNINDENT .sp Pillars are tree\-like structures of data defined on the Salt Master and passed through to minions. They allow confidential, targeted data to be securely sent only to the relevant minion. .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 Grains and Pillar are sometimes confused, just remember that Grains are data about a minion which is stored or generated from the minion. This is why information like the OS and CPU type are found in Grains. Pillar is information about a minion or many minions stored or generated on the Salt Master. .UNINDENT .UNINDENT .sp Pillar data is useful for: .INDENT 0.0 .TP .B Highly Sensitive Data: Information transferred via pillar is guaranteed to only be presented to the minions that are targeted, making Pillar suitable 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 in dictionary format, so 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. To see the minion\(aqs pillar data: .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 not loaded into pillar for all minions. This default is stored in the \fBpillar_opts\fP setting, which defaults to \fBFalse\fP\&. .sp The contents of the master configuration file can be made available to minion pillar files. This makes global configuration of services and systems very easy, but note that this may not be desired or appropriate if sensitive data is stored in the master\(aqs configuration file. To enable the master configuration file to be available to a minion\(aqs pillar files, set \fBpillar_opts\fP to \fBTrue\fP in the minion configuration file. .sp Similar to the state tree, the pillar is comprised of sls files and has a top file. 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. It must not be in a subdirectory of the state tree or file_roots. If the pillar is under file_roots, any pillar targeting can be bypassed by minions. .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 create a simple top file, following the same format as the top file used for states: .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 To ensure that the minions have the new pillar data, issue a command to them asking that they fetch their pillars from the master: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq saltutil.refresh_pillar .ft P .fi .UNINDENT .UNINDENT .sp Now that the minions have the new pillar, it can be retrieved: .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 Unlike states, pillar files do not need to define \fBformulas\fP\&. This example 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 top file\&. .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, you can use 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 Parameterizing States With Pillar .sp Pillar data can be accessed in state files to customise behavior for each minion. All pillar (and grain) data applicable to each minion is substituted into the state files through templating before being run. Typical uses include setting directories appropriate for the minion and skipping states that don\(aqt apply. .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 Setting Pillar Data on the Command Line .sp Pillar data can be set on the command line when running \fBstate.apply {% for server, addrs in salt[\(aqmine.get\(aq](\(aqroles:web\(aq, \(aqnetwork.ip_addrs\(aq, expr_form=\(aqgrain\(aq) | dictsort() %} server {{ server }} {{ addrs[0] }}:80 check {% endfor %} <...file contents snipped...> .ft P .fi .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 The expr_form argument will be renamed to \fBtgt_type\fP in the Nitrogen release of Salt. .UNINDENT .UNINDENT .SS Runners .sp Salt runners are convenience applications executed with the salt\-run command. .sp Salt runners work similarly to Salt execution modules however they execute on the Salt master itself instead of remote Salt minions. .sp A Salt runner can be a simple client call or a complex application. .sp \fBSEE ALSO:\fP .INDENT 0.0 .INDENT 3.5 The full list of runners .UNINDENT .UNINDENT .SS Writing Salt Runners .sp A Salt runner is written in a similar manner to a Salt execution module. Both are Python modules which contain functions and each public function is a runner which may be executed via the \fIsalt\-run\fP command. .sp For example, if a Python module named \fBtest.py\fP is created in the runners directory and contains a function called \fBfoo\fP, the \fBtest\fP runner could be invoked with the following command: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C # salt\-run test.foo .ft P .fi .UNINDENT .UNINDENT .sp Runners have several options for controlling output. .sp Any \fBprint\fP statement in a runner is automatically also fired onto the master event bus where. For example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C def a_runner(outputter=None, display_progress=False): print(\(aqHello world\(aq) ... .ft P .fi .UNINDENT .UNINDENT .sp The above would result in an event fired as follows: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C Event fired at Tue Jan 13 15:26:45 2015 ************************* Tag: salt/run/20150113152644070246/print Data: {\(aq_stamp\(aq: \(aq2015\-01\-13T15:26:45.078707\(aq, \(aqdata\(aq: \(aqhello\(aq, \(aqoutputter\(aq: \(aqpprint\(aq} .ft P .fi .UNINDENT .UNINDENT .sp A runner may also send a progress event, which is displayed to the user during runner execution and is also passed across the event bus if the \fBdisplay_progress\fP argument to a runner is set to True. .sp A custom runner may send its own progress event by using the \fB__jid_event_.fire_event()\fP method as shown here: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C if display_progress: __jid_event__.fire_event({\(aqmessage\(aq: \(aqA progress message\(aq}, \(aqprogress\(aq) .ft P .fi .UNINDENT .UNINDENT .sp The above would produce output on the console reading: \fBA progress message\fP as well as an event on the event similar to: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C Event fired at Tue Jan 13 15:21:20 2015 ************************* Tag: salt/run/20150113152118341421/progress Data: {\(aq_stamp\(aq: \(aq2015\-01\-13T15:21:20.390053\(aq, \(aqmessage\(aq: "A progress message"} .ft P .fi .UNINDENT .UNINDENT .sp A runner could use the same approach to send an event with a customized tag onto the event bus by replacing the second argument (\fBprogress\fP) with whatever tag is desired. However, this will not be shown on the command\-line and will only be fired onto the event bus. .SS Synchronous vs. Asynchronous .sp A runner may be fired asynchronously which will immediately return control. In this case, no output will be display to the user if \fBsalt\-run\fP is being used from the command\-line. If used programmatically, no results will be returned. If results are desired, they must be gathered either by firing events on the bus from the runner and then watching for them or by some other means. .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 When running a runner in asynchronous mode, the \fB\-\-progress\fP flag will not deliver output to the salt\-run CLI. However, progress events will still be fired on the bus. .UNINDENT .UNINDENT .sp In synchronous mode, which is the default, control will not be returned until the runner has finished executing. .sp To add custom runners, put them in a directory and add it to \fBrunner_dirs\fP in the master configuration file. .SS Examples .sp Examples of runners can be found in the Salt distribution: .sp \fI\%https://github.com/saltstack/salt/blob/develop/salt/runners\fP .sp A simple runner that returns a well\-formatted list of the minions that are responding to Salt calls could look like this: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C # Import salt modules import salt.client def up(): \(aq\(aq\(aq Print a list of all of the minions that are up \(aq\(aq\(aq client = salt.client.LocalClient(__opts__[\(aqconf_file\(aq]) minions = client.cmd(\(aq*\(aq, \(aqtest.ping\(aq, timeout=1) for minion in sorted(minions): print minion .ft P .fi .UNINDENT .UNINDENT .SS Salt Engines .sp New in version 2015.8.0. .sp Salt Engines are long\-running, external system processes that leverage Salt. .INDENT 0.0 .IP \(bu 2 Engines have access to Salt configuration, execution modules, and runners (\fB__opts__\fP, \fB__salt__\fP, and \fB__runners__\fP). .IP \(bu 2 Engines are executed in a separate process that is monitored by Salt. If a Salt engine stops, it is restarted automatically. .IP \(bu 2 Engines can run on the Salt master and on Salt minions. .UNINDENT .sp Salt engines enhance and replace the external processes functionality. .SS Configuration .sp Salt engines are configured under an \fBengines\fP top\-level section in your Salt master or Salt minion configuration. Provide a list of engines and parameters under this section. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C engines: \- logstash: host: log.my_network.com port: 5959 .ft P .fi .UNINDENT .UNINDENT .sp Salt engines must be in the Salt path, or you can add the \fBengines_dirs\fP option in your Salt master configuration with a list of directories under which Salt attempts to find Salt engines. .SS Writing an Engine .sp An example Salt engine, \fI\%https://github.com/saltstack/salt/blob/develop/salt/engines/test.py\fP, is available in the Salt source. To develop an engine, the only requirement is that your module implement the \fBstart()\fP function. .SS Understanding YAML .sp The default renderer for SLS files is the YAML renderer. YAML is a markup language with many powerful features. However, Salt uses a small subset of YAML that maps over very commonly used data structures, like lists and dictionaries. It is the job of the YAML renderer to take the YAML data structure and compile it into a Python data structure for use by Salt. .sp Though YAML syntax may seem daunting and terse at first, there are only three very simple rules to remember when writing YAML for SLS files. .SS Rule One: Indentation .sp YAML uses a fixed indentation scheme to represent relationships between data layers. Salt requires that the indentation for each level consists of exactly two spaces. Do not use tabs. .SS Rule Two: Colons .sp Python dictionaries are, of course, simply key\-value pairs. Users from other languages may recognize this data type as hashes or associative arrays. .sp Dictionary keys are represented in YAML as strings terminated by a trailing colon. Values are represented by either a string following the colon, separated by a space: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C my_key: my_value .ft P .fi .UNINDENT .UNINDENT .sp In Python, the above maps to: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C {\(aqmy_key\(aq: \(aqmy_value\(aq} .ft P .fi .UNINDENT .UNINDENT .sp Alternatively, a value can be associated with a key through indentation. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C my_key: my_value .ft P .fi .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 The above syntax is valid YAML but is uncommon in SLS files because most often, the value for a key is not singular but instead is a \fIlist\fP of values. .UNINDENT .UNINDENT .sp In Python, the above maps to: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C {\(aqmy_key\(aq: \(aqmy_value\(aq} .ft P .fi .UNINDENT .UNINDENT .sp Dictionaries can be nested: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C first_level_dict_key: second_level_dict_key: value_in_second_level_dict .ft P .fi .UNINDENT .UNINDENT .sp And in Python: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C { \(aqfirst_level_dict_key\(aq: { \(aqsecond_level_dict_key\(aq: \(aqvalue_in_second_level_dict\(aq } } .ft P .fi .UNINDENT .UNINDENT .SS Rule Three: Dashes .sp To represent lists of items, a single dash followed by a space is used. Multiple items are a part of the same list as a function of their having the same level of indentation. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C \- list_value_one \- list_value_two \- list_value_three .ft P .fi .UNINDENT .UNINDENT .sp Lists can be the value of a key\-value pair. This is quite common in Salt: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C my_dictionary: \- list_value_one \- list_value_two \- list_value_three .ft P .fi .UNINDENT .UNINDENT .sp In Python, the above maps to: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C {\(aqmy_dictionary\(aq: [\(aqlist_value_one\(aq, \(aqlist_value_two\(aq, \(aqlist_value_three\(aq]} .ft P .fi .UNINDENT .UNINDENT .SS Learning More .sp One easy way to learn more about how YAML gets rendered into Python data structures is to use an online YAML parser to see the Python output. .sp One excellent choice for experimenting with YAML parsing is: \fI\%http://yaml\-online\-parser.appspot.com/\fP .SS Templating .sp Jinja statements and expressions are allowed by default in SLS files. See Understanding Jinja\&. .SS Understanding Jinja .sp \fI\%Jinja\fP is the default templating language in SLS files. .SS Jinja in States .sp Jinja is evaluated before YAML, which means it is evaluated before the States are run. .sp The most basic usage of Jinja in state files is using control structures to wrap conditional or redundant state elements: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C {% if grains[\(aqos\(aq] != \(aqFreeBSD\(aq %} tcsh: pkg: \- installed {% endif %} motd: file.managed: {% if grains[\(aqos\(aq] == \(aqFreeBSD\(aq %} \- name: /etc/motd {% elif grains[\(aqos\(aq] == \(aqDebian\(aq %} \- name: /etc/motd.tail {% endif %} \- source: salt://motd .ft P .fi .UNINDENT .UNINDENT .sp In this example, the first if block will only be evaluated on minions that aren\(aqt running FreeBSD, and the second block changes the file name based on the \fIos\fP grain. .sp Writing \fBif\-else\fP blocks can lead to very redundant state files however. In this case, using pillars, or using a previously defined variable might be easier: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C {% set motd = [\(aq/etc/motd\(aq] %} {% if grains[\(aqos\(aq] == \(aqDebian\(aq %} {% set motd = [\(aq/etc/motd.tail\(aq, \(aq/var/run/motd\(aq] %} {% endif %} {% for motdfile in motd %} {{ motdfile }}: file.managed: \- source: salt://motd {% endfor %} .ft P .fi .UNINDENT .UNINDENT .sp Using a variable set by the template, the \fI\%for loop\fP will iterate over the list of MOTD files to update, adding a state block for each file. .sp The filter_by function can also be used to set variables based on grains: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C {% set auditd = salt[\(aqgrains.filter_by\(aq]({ \(aqRedHat\(aq: { \(aqpackage\(aq: \(aqaudit\(aq }, \(aqDebian\(aq: { \(aqpackage\(aq: \(aqauditd\(aq }, }) %} .ft P .fi .UNINDENT .UNINDENT .SS Include and Import .sp Includes and \fI\%imports\fP can be used to share common, reusable state configuration between state files and between files. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C {% from \(aqlib.sls\(aq import test %} .ft P .fi .UNINDENT .UNINDENT .sp This would import the \fBtest\fP template variable or macro, not the \fBtest\fP state element, from the file \fBlib.sls\fP\&. In the case that the included file performs checks again grains, or something else that requires context, passing the context into the included file is required: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C {% from \(aqlib.sls\(aq import test with context %} .ft P .fi .UNINDENT .UNINDENT .SS Including Context During Include/Import .sp By adding \fBwith context\fP to the include/import directive, the current context can be passed to an included/imported template. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C {% import \(aqopenssl/vars.sls\(aq as ssl with context %} .ft P .fi .UNINDENT .UNINDENT .SS Macros .sp \fI\%Macros\fP are helpful for eliminating redundant code. Macros are most useful as mini\-templates to repeat blocks of strings with a few parameterized variables. Be aware that stripping whitespace from the template block, as well as contained blocks, may be necessary to emulate a variable return from the macro. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C # init.sls {% from \(aqlib.sls\(aq import pythonpkg with context %} python\-virtualenv: pkg.installed: \- name: {{ pythonpkg(\(aqvirtualenv\(aq) }} python\-fabric: pkg.installed: \- name: {{ pythonpkg(\(aqfabric\(aq) }} .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C # lib.sls {% macro pythonpkg(pkg) \-%} {%\- if grains[\(aqos\(aq] == \(aqFreeBSD\(aq \-%} py27\-{{ pkg }} {%\- elif grains[\(aqos\(aq] == \(aqDebian\(aq \-%} python\-{{ pkg }} {%\- endif \-%} {%\- endmacro %} .ft P .fi .UNINDENT .UNINDENT .sp This would define a \fI\%macro\fP that would return a string of the full package name, depending on the packaging system\(aqs naming convention. The whitespace of the macro was eliminated, so that the macro would return a string without line breaks, using \fI\%whitespace control\fP\&. .SS Template Inheritance .sp \fI\%Template inheritance\fP works fine from state files and files. The search path starts at the root of the state tree or pillar. .SS Filters .sp Saltstack extends \fI\%builtin filters\fP with these custom filters: .INDENT 0.0 .TP .B strftime Converts any time related object into a time based string. It requires a valid \fI\%strftime directives\fP\&. An \fI\%exhaustive list\fP can be found in the official Python documentation. .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C {% set curtime = None | strftime() %} .ft P .fi .UNINDENT .UNINDENT .sp Fuzzy dates require the \fI\%timelib\fP Python module is installed. .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C {{ "2002/12/25"|strftime("%y") }} {{ "1040814000"|strftime("%Y\-%m\-%d") }} {{ datetime|strftime("%u") }} {{ "tomorrow"|strftime }} .ft P .fi .UNINDENT .UNINDENT .TP .B sequence Ensure that parsed data is a sequence. .TP .B yaml_encode Serializes a single object into a YAML scalar with any necessary handling for escaping special characters. This will work for any scalar YAML data type: ints, floats, timestamps, booleans, strings, unicode. It will \fInot\fP work for multi\-objects such as sequences or maps. .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C {%\- set bar = 7 %} {%\- set baz = none %} {%\- set zip = true %} {%\- set zap = \(aqThe word of the day is "salty"\(aq %} {%\- load_yaml as foo %} bar: {{ bar|yaml_encode }} baz: {{ baz|yaml_encode }} baz: {{ zip|yaml_encode }} baz: {{ zap|yaml_encode }} {%\- endload %} .ft P .fi .UNINDENT .UNINDENT .sp In the above case \fB{{ bar }}\fP and \fB{{ foo.bar }}\fP should be identical and \fB{{ baz }}\fP and \fB{{ foo.baz }}\fP should be identical. .TP .B yaml_dquote Serializes a string into a properly\-escaped YAML double\-quoted string. This is useful when the contents of a string are unknown and may contain quotes or unicode that needs to be preserved. The resulting string will be emitted with opening and closing double quotes. .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C {%\- set bar = \(aq"The quick brown fox . . ."\(aq %} {%\- set baz = \(aqThe word of the day is "salty".\(aq %} {%\- load_yaml as foo %} bar: {{ bar|yaml_dquote }} baz: {{ baz|yaml_dquote }} {%\- endload %} .ft P .fi .UNINDENT .UNINDENT .sp In the above case \fB{{ bar }}\fP and \fB{{ foo.bar }}\fP should be identical and \fB{{ baz }}\fP and \fB{{ foo.baz }}\fP should be identical. If variable contents are not guaranteed to be a string then it is better to use \fByaml_encode\fP which handles all YAML scalar types. .TP .B yaml_squote Similar to the \fByaml_dquote\fP filter but with single quotes. Note that YAML only allows special escapes inside double quotes so \fByaml_squote\fP is not nearly as useful (viz. you likely want to use \fByaml_encode\fP or \fByaml_dquote\fP). .UNINDENT .SS Jinja in Files .sp .nf Jinja_ .fi can be used in the same way in managed files: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C # redis.sls /etc/redis/redis.conf: file.managed: \- source: salt://redis.conf \- template: jinja \- context: bind: 127.0.0.1 .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C # lib.sls {% set port = 6379 %} .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C # redis.conf {% from \(aqlib.sls\(aq import port with context %} port {{ port }} bind {{ bind }} .ft P .fi .UNINDENT .UNINDENT .sp As an example, configuration was pulled from the file context and from an external template file. .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 Macros and variables can be shared across templates. They should not be starting with one or more underscores, and should be managed by one of the following tags: \fImacro\fP, \fIset\fP, \fIload_yaml\fP, \fIload_json\fP, \fIimport_yaml\fP and \fIimport_json\fP\&. .UNINDENT .UNINDENT .SS Escaping Jinja .sp Occasionally, it may be necessary to escape Jinja syntax. There are two ways to to do this in Jinja. One is escaping individual variables or strings and the other is to escape entire blocks. .sp To escape a string commonly used in Jinja syntax such as \fB{{\fP, you can use the following syntax: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C {{ \(aq{{\(aq }} .ft P .fi .UNINDENT .UNINDENT .sp For larger blocks that contain Jinja syntax that needs to be escaped, you can use raw blocks: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C {% raw %} some text that contains jinja characters that need to be escaped {% endraw %} .ft P .fi .UNINDENT .UNINDENT .sp See the \fI\%Escaping\fP section of Jinja\(aqs documentation to learn more. .sp A real\-word example of needing to use raw tags to escape a larger block of code is when using \fBfile.managed\fP with the \fBcontents_pillar\fP option to manage files that contain something like consul\-template, which shares a syntax subset with Jinja. Raw blocks are necessary here because the Jinja in the pillar would be rendered before the file.managed is ever called, so the Jinja syntax must be escaped: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C {% raw %} \- contents_pillar: | job "example\-job" { task "example" { driver = "docker" config { image = "docker\-registry.service.consul:5000/example\-job:{{key "nomad/jobs/example\-job/version"}}" {% endraw %} .ft P .fi .UNINDENT .UNINDENT .SS Calling Salt Functions .sp The Jinja renderer provides a shorthand lookup syntax for the \fBsalt\fP dictionary of execution function\&. .sp New in version 2014.7.0. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C # The following two function calls are equivalent. {{ salt[\(aqcmd.run\(aq](\(aqwhoami\(aq) }} {{ salt.cmd.run(\(aqwhoami\(aq) }} .ft P .fi .UNINDENT .UNINDENT .SS Debugging .sp The \fBshow_full_context\fP function can be used to output all variables present in the current Jinja context. .sp New in version 2014.7.0. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C Context is: {{ show_full_context() }} .ft P .fi .UNINDENT .UNINDENT .SS Custom Execution Modules .sp Custom execution modules can be used to supplement or replace complex Jinja. Many tasks that require complex looping and logic are trivial when using Python in a Salt execution module. Salt execution modules are easy to write and distribute to Salt minions. .sp Functions in custom execution modules are available in the Salt execution module dictionary just like the built\-in execution modules: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C {{ salt[\(aqmy_custom_module.my_custom_function\(aq]() }} .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .IP \(bu 2 How to Convert Jinja Logic to an Execution Module .IP \(bu 2 Writing Execution Modules .UNINDENT .SS Tutorials Index .INDENT 0.0 .IP \(bu 2 Salt as a Cloud Controller .IP \(bu 2 Using Cron with Salt .IP \(bu 2 Automatic Updates / Frozen Deployments .IP \(bu 2 ESXi Proxy Minion .IP \(bu 2 Opening the Firewall up for Salt .IP \(bu 2 Git Fileserver Backend Walkthrough .IP \(bu 2 Halite .IP \(bu 2 HTTP Modules .IP \(bu 2 Using Salt at Scale .IP \(bu 2 LXC Management with Salt .IP \(bu 2 MinionFS Backend Walkthrough .IP \(bu 2 Remote Execution Tutorial .IP \(bu 2 Multi\-Master\-PKI Tutorial With Failover .IP \(bu 2 Multi Master Tutorial .IP \(bu 2 Pillar Walkthrough .IP \(bu 2 Packaging External Modules for Salt .IP \(bu 2 Salt Masterless Quickstart .IP \(bu 2 running salt as normal user tutorial .IP \(bu 2 Salt Bootstrap .IP \(bu 2 Standalone Minion .IP \(bu 2 How Do I Use Salt States? .IP \(bu 2 States tutorial, part 1 \- Basic Usage .IP \(bu 2 States tutorial, part 2 \- More Complex States, Requisites .IP \(bu 2 States tutorial, part 3 \- Templating, Includes, Extends .IP \(bu 2 States tutorial, part 4 .IP \(bu 2 How to Convert Jinja Logic to an Execution Module .IP \(bu 2 Using Salt with Stormpath .IP \(bu 2 Syslog\-ng usage .IP \(bu 2 The macOS (Maverick) Developer Step By Step Guide To Salt Installation .IP \(bu 2 SaltStack Walk\-through .IP \(bu 2 Writing Salt Tests .UNINDENT .SS 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 following links contain details on troubleshooting the most common issues encountered: .SS 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 firewall configuration 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 Live Salt\-Master Profiling .sp When faced with performance problems one can turn on master process profiling by sending it SIGUSR2. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C # killall \-SIGUSR2 salt\-master .ft P .fi .UNINDENT .UNINDENT .sp This will activate \fByappi\fP profiler inside salt\-master code, then after some time one must send SIGUSR2 again to stop profiling and save results to file. If run in foreground salt\-master will report filename for the results, which are usually located under \fB/tmp\fP on Unix\-based OSes and \fBc:\etemp\fP on windows. .sp Results can then be analyzed with \fI\%kcachegrind\fP or similar tool. .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 a \fBstate.apply\fP, or other long running commands do not return output. .sp 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. .sp Having keys accepted for Salt minions that no longer exist or are not reachable also increases the possibility of timeouts, since the Salt master waits for those systems to return command results. .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 configuration 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. .SS Salt Master Doesn\(aqt Return Anything While Running jobs .sp When a command being run via Salt takes a very long time to return (package installations, certain scripts, etc.) the master may drop you back to the shell. In most situations the job is still running but Salt has exceeded the set timeout before returning. Querying the job queue will provide the data of the job but is inconvenient. This can be resolved by either manually using the \fB\-t\fP option to set a longer timeout when running commands (by default it is 5 seconds) or by modifying the master configuration file: \fB/etc/salt/master\fP and setting the \fBtimeout\fP value to change the default timeout for all commands, and then restarting the salt\-master service. .SS Salt Master Auth Flooding .sp In large installations, care must be taken not to overwhealm the master with authentication requests. Several options can be set on the master which mitigate the chances of an authentication flood from causing an interruption in service. .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 recon_default: .sp The average number of seconds to wait between reconnection attempts. .INDENT 0.0 .TP .B recon_max: The maximum number of seconds to wait between reconnection attempts. .TP .B recon_randomize: A flag to indicate whether the recon_default value should be randomized. .TP .B acceptance_wait_time: The number of seconds to wait for a reply to each authentication request. .TP .B random_reauth_delay: The range of seconds across which the minions should attempt to randomize authentication attempts. .TP .B auth_timeout: The total time to wait for the authentication process to complete, regardless of the number of attempts. .UNINDENT .UNINDENT .UNINDENT .SS Running state locally .sp To debug the states, you can use call locally. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt\-call \-l trace \-\-local state.highstate .ft P .fi .UNINDENT .UNINDENT .sp The top.sls file is used to map what SLS modules get loaded onto what minions via the state system. .sp It is located in the file defined in the \fBfile_roots\fP variable of the salt master configuration file which is defined by found in \fBCONFIG_DIR/master\fP, normally \fB/etc/salt/master\fP .sp The default configuration for the \fBfile_roots\fP is: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C file_roots: base: \- /srv/salt .ft P .fi .UNINDENT .UNINDENT .sp So the top file is defaulted to the location \fB/srv/salt/top.sls\fP .SS Salt Master Umask .sp The salt master uses a cache to track jobs as they are published and returns come back. The recommended umask for a salt\-master is \fI022\fP, which is the default for most users on a system. Incorrect umasks can result in permission\-denied errors when the master tries to access files in its cache. .SS Troubleshooting the Salt Minion .sp In the event that your Salt minion is having issues, a variety of solutions and suggestions are available. Please refer to the following links for more information: .SS 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 firewall configuration 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. Tools like \fI\%tcptraceroute\fP can also be used to determine if an intermediate device or firewall is blocking the needed TCP ports. .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.apply\fP\&. .sp When initially creating your state tree, it is generally recommended to invoke highstates by running \fBstate.apply\fP directly from the minion with \fBsalt\-call\fP, rather than remotely from the master. This displays far more information about the execution than calling it remotely. For even more verbosity, increase the loglevel using the \fB\-l\fP argument: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C # salt\-call \-l debug state.apply .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 targeting system\&. .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. .SS Multiprocessing in Execution Modules .sp As is outlined in github issue #6300, Salt cannot use python\(aqs multiprocessing pipes and queues from execution modules. Multiprocessing from the execution modules is perfectly viable, it is just necessary to use Salt\(aqs event system to communicate back with the process. .sp The reason for this difficulty is that python attempts to pickle all objects in memory when communicating, and it cannot pickle function objects. Since the Salt loader system creates and manages function objects this causes the pickle operation to fail. .SS Salt Minion Doesn\(aqt Return Anything While Running Jobs Locally .sp When a command being run via Salt takes a very long time to return (package installations, certain scripts, etc.) the minion may drop you back to the shell. In most situations the job is still running but Salt has exceeded the set timeout before returning. Querying the job queue will provide the data of the job but is inconvenient. This can be resolved by either manually using the \fB\-t\fP option to set a longer timeout when running commands (by default it is 5 seconds) or by modifying the minion configuration file: \fB/etc/salt/minion\fP and setting the \fBtimeout\fP value to change the default timeout for all commands, and then restarting the salt\-minion service. .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 Modifying the minion timeout value is not required when running commands from a Salt Master. It is only required when running commands locally on the minion. .UNINDENT .UNINDENT .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 firewall configuration 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.apply\fP\&. .sp When initially creating your state tree, it is generally recommended to invoke \fBstate.apply\fP directly from the minion with \fBsalt\-call\fP, rather than remotely from the master. This displays far more information about the execution than calling it remotely. For even more verbosity, increase the loglevel using the \fB\-l\fP argument: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt\-call \-l debug state.apply .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 targeting system\&. .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 YAML idiosyncrasies has been compiled: .SS 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 Dictionaries .sp When \fI\%dicts\fP are nested within other data structures (particularly lists), the indentation logic sometimes changes. Examples of where this might happen include \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 those keys will be considered part of the same dictionary that contains the \fBcontext\fP key, and so the data 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 .sp Here is a more concrete example of how YAML actually handles these indentations, using the Python interpreter on the command line: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C >>> import yaml >>> yaml.safe_load(\(aq\(aq\(aqmystate: \&... file.managed: \&... \- context: \&... some: var\(aq\(aq\(aq) {\(aqmystate\(aq: {\(aqfile.managed\(aq: [{\(aqcontext\(aq: {\(aqsome\(aq: \(aqvar\(aq}}]}} >>> yaml.safe_load(\(aq\(aq\(aqmystate: \&... file.managed: \&... \- context: \&... some: var\(aq\(aq\(aq) {\(aqmystate\(aq: {\(aqfile.managed\(aq: [{\(aqsome\(aq: \(aqvar\(aq, \(aqcontext\(aq: None}]}} .ft P .fi .UNINDENT .UNINDENT .sp Note that in the second example, \fBsome\fP is added as another key in the same dictionary, whereas in the first example, it\(aqs the start of a new dictionary. That\(aqs the distinction. \fBcontext\fP is a common example because it is a keyword arg for many functions, and should contain a dictionary. .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. Pillars will be parsed twice by salt, so you\(aqll need to wrap your values in multiple quotes, for example \(aq"false"\(aq. .SS The \(aq%\(aq Sign .sp The \fI%\fP symbol has a special meaning in YAML, it needs to be passed as a string literal: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C cheese: ssh_auth.present: \- user: tbortels \- source: salt://ssh_keys/chease.pub \- config: \(aq%h/.ssh/authorized_keys\(aq .ft P .fi .UNINDENT .UNINDENT .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 .sp Alternatively you can toggle the \fIyaml_utf8\fP setting in your master configuration file. This is still an experimental setting but it should manage the right encoding conversion in salt after yaml states compilations. .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 .sp Additionally, numbers formatted like \fBXXXX\-XX\-XX\fP will also be converted (or YAML will attempt to convert them, and error out if it doesn\(aqt think the date is a real one). Thus, for example, if a minion were to have an ID of \fB4017\-16\-20\fP the minion would not start because YAML would complain that the date was out of range. The workaround is the same, surround the offending string with quotes: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C >>> import yaml >>> yaml.safe_load(\(aq4017\-16\-20\(aq) Traceback (most recent call last): File "", line 1, in File "/usr/local/lib/python2.7/site\-packages/yaml/__init__.py", line 93, in safe_load return load(stream, SafeLoader) File "/usr/local/lib/python2.7/site\-packages/yaml/__init__.py", line 71, in load return loader.get_single_data() File "/usr/local/lib/python2.7/site\-packages/yaml/constructor.py", line 39, in get_single_data return self.construct_document(node) File "/usr/local/lib/python2.7/site\-packages/yaml/constructor.py", line 43, in construct_document data = self.construct_object(node) File "/usr/local/lib/python2.7/site\-packages/yaml/constructor.py", line 88, in construct_object data = constructor(self, node) File "/usr/local/lib/python2.7/site\-packages/yaml/constructor.py", line 312, in construct_yaml_timestamp return datetime.date(year, month, day) ValueError: month must be in 1..12 >>> yaml.safe_load(\(aq"4017\-16\-20"\(aq) \(aq4017\-16\-20\(aq .ft P .fi .UNINDENT .UNINDENT .SS Keys Limited to 1024 Characters .sp Simple keys are limited to a single line and cannot be longer that 1024 characters. This is a limitation from PyYaml, as seen in a comment in \fI\%PyYAML\(aqs code\fP, and applies to anything parsed by YAML in Salt. .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 macOS 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. .SS Debugging the Master and Minion .sp A list of common master and minion troubleshooting steps provide a starting point for resolving issues you may encounter. .SS 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\%I think I found a bug! What should I do?\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.apply. 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\%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 .IP \(bu 2 \fI\%Is it possible to deploy a file to a specific minion, without other minions having access to it?\fP .IP \(bu 2 \fI\%What is the best way to restart a Salt daemon using Salt?\fP .INDENT 2.0 .IP \(bu 2 \fI\%Linux/Unix\fP .IP \(bu 2 \fI\%Windows\fP .UNINDENT .IP \(bu 2 \fI\%Salting the Salt Master\fP .IP \(bu 2 \fI\%Is Targeting using Grain Data Secure?\fP .IP \(bu 2 \fI\%Why Did the Value for a Grain Change on Its Own?\fP .UNINDENT .UNINDENT .SS Is Salt open\-core? .sp No. Salt is 100% committed to being open\-source, including all of our APIs. It is developed under the \fI\%Apache 2.0 license\fP, allowing it to be used in both open and proprietary projects. .sp To expand on this a little: .sp There is much argument over the actual definition of "open core". From our standpoint, Salt is open source because .INDENT 0.0 .IP 1. 3 It is a standalone product that anyone is free to use. .IP 2. 3 It is developed in the open with contributions accepted from the community for the good of the project. .IP 3. 3 There are no features of Salt itself that are restricted to separate proprietary products distributed by SaltStack, Inc. .IP 4. 3 Because of our Apache 2.0 license, Salt can be used as the foundation for a project or even a proprietary tool. .IP 5. 3 Our APIs are open and documented (any lack of documentation is an oversight as opposed to an intentional decision by SaltStack the company) and available for use by anyone. .UNINDENT .sp SaltStack the company does make proprietary products which use Salt and its libraries, like company is free to do, but we do so via the APIs, NOT by forking Salt and creating a different, closed\-source version of it for paying customers. .SS I think I found a bug! What should I do? .sp The salt\-users mailing list as well as the salt IRC channel can both be helpful resources to confirm if others are seeing the issue and to assist with immediate debugging. .sp To report a bug to the Salt project, please follow the instructions in reporting a bug\&. .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 here\&. .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.apply\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 documentation 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 .sp Also, if the Master is under heavy load, it is possible that the CLI will exit without displaying return data for all targeted Minions. However, this doesn\(aqt mean that the Minions did not return; this only means that the Salt CLI timed out waiting for a response. Minions will still send their return data back to the Master once the job completes. If any expected Minions are missing from the CLI output, the \fBjobs.list_jobs\fP runner can be used to show the job IDs of the jobs that have been run, and the \fBjobs.lookup_jid\fP runner can be used to get the return data for that job. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt\-run jobs.list_jobs salt\-run jobs.lookup_jid 20130916125524463507 .ft P .fi .UNINDENT .UNINDENT .sp If you find that you are often missing Minion return data on the CLI, only to find it with the jobs runners, then this may be a sign that the \fBworker_threads\fP value may need to be increased in the master config file. Additionally, running your Salt CLI commands with the \fB\-t\fP option will make Salt wait longer for the return data before the CLI command exits. For instance, the below command will wait up to 60 seconds for the Minions to return: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt \-t 60 \(aq*\(aq test.ping .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 here\&. .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 Why aren\(aqt my custom modules/states/etc. available on my Minions? .sp Custom modules are synced to Minions when \fBsaltutil.sync_modules\fP, or \fBsaltutil.sync_all\fP is run. Custom modules are also synced by \fBstate.apply\fP when run without any arguments. .sp Similarly, custom states are synced to Minions when \fBstate.apply\fP, \fBsaltutil.sync_states\fP, or \fBsaltutil.sync_all\fP is run. .sp Custom states are also synced by \fBstate.apply\fP when run without any arguments. .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 This depends on the versions. In general, it is recommended that Master and Minion versions match. .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. .sp Recent examples of backwards compatibility breakage include the 0.17.1 release (where all backwards compatibility was broken due to a security fix), and the 2014.1.0 release (which retained compatibility between 2014.1.0 masters and 0.17 minions, but broke compatibility for 2014.1.0 minions and older masters). .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 backup_mode, 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!). .SS Is it possible to deploy a file to a specific minion, without other minions having access to it? .sp The Salt fileserver does not yet support access control, but it is still possible to do this. As of Salt 2015.5.0, the \fBfile_tree\fP external pillar is available, and allows the contents of a file to be loaded as Pillar data. This external pillar is capable of assigning Pillar values both to individual minions, and to nodegroups\&. See the \fBdocumentation\fP for details on how to set this up. .sp Once the external pillar has been set up, the data can be pushed to a minion via a \fBfile.managed\fP state, using the \fBcontents_pillar\fP argument: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C /etc/my_super_secret_file: file.managed: \- user: secret \- group: secret \- mode: 600 \- contents_pillar: secret_files:my_super_secret_file .ft P .fi .UNINDENT .UNINDENT .sp In this example, the source file would be located in a directory called \fBsecret_files\fP underneath the file_tree path for the minion. The syntax for specifying the pillar variable is the same one used for \fBpillar.get\fP, with a colon representing a nested dictionary. .sp \fBWARNING:\fP .INDENT 0.0 .INDENT 3.5 Deploying binary contents using the \fBfile.managed\fP state is only supported in Salt 2015.8.4 and newer. .UNINDENT .UNINDENT .SS What is the best way to restart a Salt daemon using Salt? .sp Updating the salt\-minion package requires a restart of the salt\-minion service. But restarting the service while in the middle of a state run interrupts the process of the minion running states and sending results back to the master. It\(aqs a tricky problem to solve, and we\(aqre working on it, but in the meantime one way of handling this (on Linux and UNIX\-based operating systems) is to use \fBat\fP (a job scheduler which predates cron) to schedule a restart of the service. \fBat\fP is not installed by default on most distros, and requires a service to be running (usually called \fBatd\fP) in order to schedule jobs. Here\(aqs an example of how to upgrade the salt\-minion package at the end of a Salt run, and schedule a service restart for one minute after the package update completes. .SS Linux/Unix .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt\-minion: pkg.installed: \- name: salt\-minion \- version: 2014.1.7\-3.el6 \- order: last service.running: \- name: salt\-minion \- require: \- pkg: salt\-minion cmd.run: \- name: echo service salt\-minion restart | at now + 1 minute \- onchanges: \- pkg: salt\-minion .ft P .fi .UNINDENT .UNINDENT .sp To ensure that \fBat\fP is installed and \fBatd\fP is running, the following states can be used (be sure to double\-check the package name and service name for the distro the minion is running, in case they differ from the example below. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C at: pkg.installed: \- name: at service.running: \- name: atd \- enable: True .ft P .fi .UNINDENT .UNINDENT .sp An alternative to using the \fBatd\fP daemon is to fork and disown the process. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C restart_minion: cmd.run: \- name: | exec 0>&\- # close stdin exec 1>&\- # close stdout exec 2>&\- # close stderr nohup /bin/sh \-c \(aqsleep 10 && salt\-call \-\-local service.restart salt\-minion\(aq & \- python_shell: True \- order: last .ft P .fi .UNINDENT .UNINDENT .SS Windows .sp For Windows machines, restarting the minion can be accomplished using the following state: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C schedule\-start: cmd.run: \- name: \(aqstart powershell "Restart\-Service \-Name salt\-minion"\(aq \- order: last .ft P .fi .UNINDENT .UNINDENT .sp or running immediately from the command line: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt \-G kernel:Windows cmd.run \(aqstart powershell "Restart\-Service \-Name salt\-minion"\(aq .ft P .fi .UNINDENT .UNINDENT .SS Salting the Salt Master .sp In order to configure a master server via states, the Salt master can also be "salted" in order to enforce state on the Salt master as well as the Salt minions. Salting the Salt master requires a Salt minion to be installed on the same machine as the Salt master. Once the Salt minion is installed, the minion configuration file must be pointed to the local Salt master: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C master: 127.0.0.1 .ft P .fi .UNINDENT .UNINDENT .sp Once the Salt master has been "salted" with a Salt minion, it can be targeted just like any other minion. If the minion on the salted master is running, the minion can be targeted via any usual \fBsalt\fP command. Additionally, the \fBsalt\-call\fP command can execute operations to enforce state on the salted master without requiring the minion to be running. .sp More information about salting the Salt master can be found in the salt\-formula for salt itself: .sp \fI\%https://github.com/saltstack\-formulas/salt\-formula\fP .SS Is Targeting using Grain Data Secure? .sp Because grains can be set by users that have access to the minion configuration files on the local system, grains are considered less secure than other identifiers in Salt. Use caution when targeting sensitive operations or setting pillar values based on grain data. .sp When possible, you should target sensitive operations and data using the Minion ID. If the Minion ID of a system changes, the Salt Minion\(aqs public key must be re\-accepted by an administrator on the Salt Master, making it less vulnerable to impersonation attacks. .SS Why Did the Value for a Grain Change on Its Own? .sp This is usually the result of an upstream change in an OS distribution that replaces or removes something that Salt was using to detect the grain. Fortunately, when this occurs, you can use Salt to fix it with a command similar to the following: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt \-G \(aqgrain:ChangedValue\(aq grains.setvals "{\(aqgrain\(aq: \(aqOldValue\(aq}" .ft P .fi .UNINDENT .UNINDENT .sp (Replacing \fIgrain\fP, \fIChangedValue\fP, and \fIOldValue\fP with the grain and values that you want to change / set.) .sp You should also \fI\%file an issue\fP describing the change so it can be fixed in Salt. .SS Salt Best Practices .sp Salt\(aqs extreme flexibility leads to many questions concerning the structure of configuration files. .sp This document exists to clarify these points through examples and code. .SS General rules .INDENT 0.0 .IP 1. 3 Modularity and clarity should be emphasized whenever possible. .IP 2. 3 Create clear relations between pillars and states. .IP 3. 3 Use variables when it makes sense but don\(aqt overuse them. .IP 4. 3 Store sensitive data in pillar. .IP 5. 3 Don\(aqt use grains for matching in your pillar top file for any sensitive pillars. .UNINDENT .SS Structuring States and Formulas .sp When structuring Salt States and Formulas it is important to begin with the directory structure. A proper directory structure clearly defines the functionality of each state to the user via visual inspection of the state\(aqs name. .sp Reviewing the \fI\%MySQL Salt Formula\fP it is clear to see the benefits to the end\-user when reviewing a sample of the available states: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C /srv/salt/mysql/files/ /srv/salt/mysql/client.sls /srv/salt/mysql/map.jinja /srv/salt/mysql/python.sls /srv/salt/mysql/server.sls .ft P .fi .UNINDENT .UNINDENT .sp This directory structure would lead to these states being referenced in a top file in the following way: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C base: \(aqweb*\(aq: \- mysql.client \- mysql.python \(aqdb*\(aq: \- mysql.server .ft P .fi .UNINDENT .UNINDENT .sp This clear definition ensures that the user is properly informed of what each state will do. .sp Another example comes from the \fI\%vim\-formula\fP: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C /srv/salt/vim/files/ /srv/salt/vim/absent.sls /srv/salt/vim/init.sls /srv/salt/vim/map.jinja /srv/salt/vim/nerdtree.sls /srv/salt/vim/pyflakes.sls /srv/salt/vim/salt.sls .ft P .fi .UNINDENT .UNINDENT .sp Once again viewing how this would look in a top file: .sp /srv/salt/top.sls: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C base: \(aqweb*\(aq: \- vim \- vim.nerdtree \- vim.pyflakes \- vim.salt \(aqdb*\(aq: \- vim.absent .ft P .fi .UNINDENT .UNINDENT .sp The usage of a clear top\-level directory as well as properly named states reduces the overall complexity and leads a user to both understand what will be included at a glance and where it is located. .sp In addition Formulas should be used as often as possible. .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 Formulas repositories on the saltstack\-formulas GitHub organization should not be pointed to directly from systems that automatically fetch new updates such as GitFS or similar tooling. Instead formulas repositories should be forked on GitHub or cloned locally, where unintended, automatic changes will not take place. .UNINDENT .UNINDENT .SS Structuring Pillar Files .sp Pillars are used to store secure and insecure data pertaining to minions. When designing the structure of the \fB/srv/pillar\fP directory, the pillars contained within should once again be focused on clear and concise data which users can easily review, modify, and understand. .sp The \fB/srv/pillar/\fP directory is primarily controlled by \fBtop.sls\fP\&. It should be noted that the pillar \fBtop.sls\fP is not used as a location to declare variables and their values. The \fBtop.sls\fP is used as a way to include other pillar files and organize the way they are matched based on environments or grains. .sp An example \fBtop.sls\fP may be as simple as the following: .sp /srv/pillar/top.sls: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C base: \(aq*\(aq: \- packages .ft P .fi .UNINDENT .UNINDENT .sp Any number of matchers can be added to the base environment. For example, here is an expanded version of the Pillar top file stated above: .sp /srv/pillar/top.sls: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C base: \(aq*\(aq: \- packages \(aqweb*\(aq: \- apache \- vim .ft P .fi .UNINDENT .UNINDENT .sp Or an even more complicated example, using a variety of matchers in numerous environments: .sp /srv/pillar/top.sls: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C base: \(aq*\(aq: \- apache dev: \(aqos:Debian\(aq: \- match: grain \- vim test: \(aq* and not G@os: Debian\(aq: \- match: compound \- emacs .ft P .fi .UNINDENT .UNINDENT .sp It is clear to see through these examples how the top file provides users with power but when used incorrectly it can lead to confusing configurations. This is why it is important to understand that the top file for pillar is not used for variable definitions. .sp Each SLS file within the \fB/srv/pillar/\fP directory should correspond to the states which it matches. .sp This would mean that the \fBapache\fP pillar file should contain data relevant to Apache. Structuring files in this way once again ensures modularity, and creates a consistent understanding throughout our Salt environment. Users can expect that pillar variables found in an Apache state will live inside of an Apache pillar: .sp \fB/srv/pillar/apache.sls\fP: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C apache: lookup: name: httpd config: tmpl: /etc/httpd/httpd.conf .ft P .fi .UNINDENT .UNINDENT .sp While this pillar file is simple, it shows how a pillar file explicitly relates to the state it is associated with. .SS Variable Flexibility .sp Salt allows users to define variables in SLS files. When creating a state variables should provide users with as much flexibility as possible. This means that variables should be clearly defined and easy to manipulate, and that sane defaults should exist in the event a variable is not properly defined. Looking at several examples shows how these different items can lead to extensive flexibility. .sp Although it is possible to set variables locally, this is generally not preferred: .sp \fB/srv/salt/apache/conf.sls\fP: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C {% set name = \(aqhttpd\(aq %} {% set tmpl = \(aqsalt://apache/files/httpd.conf\(aq %} include: \- apache apache_conf: file.managed: \- name: {{ name }} \- source: {{ tmpl }} \- template: jinja \- user: root \- watch_in: \- service: apache .ft P .fi .UNINDENT .UNINDENT .sp When generating this information it can be easily transitioned to the pillar where data can be overwritten, modified, and applied to multiple states, or locations within a single state: .sp \fB/srv/pillar/apache.sls\fP: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C apache: lookup: name: httpd config: tmpl: salt://apache/files/httpd.conf .ft P .fi .UNINDENT .UNINDENT .sp \fB/srv/salt/apache/conf.sls\fP: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C {% from "apache/map.jinja" import apache with context %} include: \- apache apache_conf: file.managed: \- name: {{ salt[\(aqpillar.get\(aq](\(aqapache:lookup:name\(aq) }} \- source: {{ salt[\(aqpillar.get\(aq](\(aqapache:lookup:config:tmpl\(aq) }} \- template: jinja \- user: root \- watch_in: \- service: apache .ft P .fi .UNINDENT .UNINDENT .sp This flexibility provides users with a centralized location to modify variables, which is extremely important as an environment grows. .SS Modularity Within States .sp Ensuring that states are modular is one of the key concepts to understand within Salt. When creating a state a user must consider how many times the state could be re\-used, and what it relies on to operate. Below are several examples which will iteratively explain how a user can go from a state which is not very modular to one that is: .sp \fB/srv/salt/apache/init.sls\fP: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C httpd: pkg.installed: [] service.running: \- enable: True /etc/httpd/httpd.conf: file.managed: \- source: salt://apache/files/httpd.conf \- template: jinja \- watch_in: \- service: httpd .ft P .fi .UNINDENT .UNINDENT .sp The example above is probably the worst\-case scenario when writing a state. There is a clear lack of focus by naming both the pkg/service, and managed file directly as the state ID. This would lead to changing multiple requires within this state, as well as others that may depend upon the state. .sp Imagine if a require was used for the \fBhttpd\fP package in another state, and then suddenly it\(aqs a custom package. Now changes need to be made in multiple locations which increases the complexity and leads to a more error prone configuration. .sp There is also the issue of having the configuration file located in the init, as a user would be unable to simply install the service and use the default conf file. .sp Our second revision begins to address the referencing by using \fB\- name\fP, as opposed to direct ID references: .sp \fB/srv/salt/apache/init.sls\fP: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C apache: pkg.installed: \- name: httpd service.running: \- name: httpd \- enable: True apache_conf: file.managed: \- name: /etc/httpd/httpd.conf \- source: salt://apache/files/httpd.conf \- template: jinja \- watch_in: \- service: apache .ft P .fi .UNINDENT .UNINDENT .sp The above init file is better than our original, yet it has several issues which lead to a lack of modularity. The first of these problems is the usage of static values for items such as the name of the service, the name of the managed file, and the source of the managed file. When these items are hard coded they become difficult to modify and the opportunity to make mistakes arises. It also leads to multiple edits that need to occur when changing these items (imagine if there were dozens of these occurrences throughout the state!). There is also still the concern of the configuration file data living in the same state as the service and package. .sp In the next example steps will be taken to begin addressing these issues. Starting with the addition of a map.jinja file (as noted in the Formula documentation), and modification of static values: .sp \fB/srv/salt/apache/map.jinja\fP: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C {% set apache = salt[\(aqgrains.filter_by\(aq]({ \(aqDebian\(aq: { \(aqserver\(aq: \(aqapache2\(aq, \(aqservice\(aq: \(aqapache2\(aq, \(aqconf\(aq: \(aq/etc/apache2/apache.conf\(aq, }, \(aqRedHat\(aq: { \(aqserver\(aq: \(aqhttpd\(aq, \(aqservice\(aq: \(aqhttpd\(aq, \(aqconf\(aq: \(aq/etc/httpd/httpd.conf\(aq, }, }, merge=salt[\(aqpillar.get\(aq](\(aqapache:lookup\(aq)) %} .ft P .fi .UNINDENT .UNINDENT .sp /srv/pillar/apache.sls: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C apache: lookup: config: tmpl: salt://apache/files/httpd.conf .ft P .fi .UNINDENT .UNINDENT .sp \fB/srv/salt/apache/init.sls\fP: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C {% from "apache/map.jinja" import apache with context %} apache: pkg.installed: \- name: {{ apache.server }} service.running: \- name: {{ apache.service }} \- enable: True apache_conf: file.managed: \- name: {{ apache.conf }} \- source: {{ salt[\(aqpillar.get\(aq](\(aqapache:lookup:config:tmpl\(aq) }} \- template: jinja \- user: root \- watch_in: \- service: apache .ft P .fi .UNINDENT .UNINDENT .sp The changes to this state now allow us to easily identify the location of the variables, as well as ensuring they are flexible and easy to modify. While this takes another step in the right direction, it is not yet complete. Suppose the user did not want to use the provided conf file, or even their own configuration file, but the default apache conf. With the current state setup this is not possible. To attain this level of modularity this state will need to be broken into two states. .sp \fB/srv/salt/apache/map.jinja\fP: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C {% set apache = salt[\(aqgrains.filter_by\(aq]({ \(aqDebian\(aq: { \(aqserver\(aq: \(aqapache2\(aq, \(aqservice\(aq: \(aqapache2\(aq, \(aqconf\(aq: \(aq/etc/apache2/apache.conf\(aq, }, \(aqRedHat\(aq: { \(aqserver\(aq: \(aqhttpd\(aq, \(aqservice\(aq: \(aqhttpd\(aq, \(aqconf\(aq: \(aq/etc/httpd/httpd.conf\(aq, }, }, merge=salt[\(aqpillar.get\(aq](\(aqapache:lookup\(aq)) %} .ft P .fi .UNINDENT .UNINDENT .sp \fB/srv/pillar/apache.sls\fP: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C apache: lookup: config: tmpl: salt://apache/files/httpd.conf .ft P .fi .UNINDENT .UNINDENT .sp \fB/srv/salt/apache/init.sls\fP: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C {% from "apache/map.jinja" import apache with context %} apache: pkg.installed: \- name: {{ apache.server }} service.running: \- name: {{ apache.service }} \- enable: True .ft P .fi .UNINDENT .UNINDENT .sp \fB/srv/salt/apache/conf.sls\fP: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C {% from "apache/map.jinja" import apache with context %} include: \- apache apache_conf: file.managed: \- name: {{ apache.conf }} \- source: {{ salt[\(aqpillar.get\(aq](\(aqapache:lookup:config:tmpl\(aq) }} \- template: jinja \- user: root \- watch_in: \- service: apache .ft P .fi .UNINDENT .UNINDENT .sp This new structure now allows users to choose whether they only wish to install the default Apache, or if they wish, overwrite the default package, service, configuration file location, or the configuration file itself. In addition to this the data has been broken between multiple files allowing for users to identify where they need to change the associated data. .SS Storing Secure Data .sp Secure data refers to any information that you would not wish to share with anyone accessing a server. This could include data such as passwords, keys, or other information. .sp As all data within a state is accessible by EVERY server that is connected it is important to store secure data within pillar. This will ensure that only those servers which require this secure data have access to it. In this example a use can go from an insecure configuration to one which is only accessible by the appropriate hosts: .sp \fB/srv/salt/mysql/testerdb.sls\fP: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C testdb: mysql_database.present: \- name: testerdb .ft P .fi .UNINDENT .UNINDENT .sp \fB/srv/salt/mysql/user.sls\fP: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C include: \- mysql.testerdb testdb_user: mysql_user.present: \- name: frank \- password: "test3rdb" \- host: localhost \- require: \- sls: mysql.testerdb .ft P .fi .UNINDENT .UNINDENT .sp Many users would review this state and see that the password is there in plain text, which is quite problematic. It results in several issues which may not be immediately visible. .sp The first of these issues is clear to most users \-\- the password being visible in this state. This means that any minion will have a copy of this, and therefore the password which is a major security concern as minions may not be locked down as tightly as the master server. .sp The other issue that can be encountered is access by users on the master. If everyone has access to the states (or their repository), then they are able to review this password. Keeping your password data accessible by only a few users is critical for both security and peace of mind. .sp There is also the issue of portability. When a state is configured this way it results in multiple changes needing to be made. This was discussed in the sections above but it is a critical idea to drive home. If states are not portable it may result in more work later! .sp Fixing this issue is relatively simple, the content just needs to be moved to the associated pillar: .sp \fB/srv/pillar/mysql.sls\fP: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C mysql: lookup: name: testerdb password: test3rdb user: frank host: localhost .ft P .fi .UNINDENT .UNINDENT .sp \fB/srv/salt/mysql/testerdb.sls\fP: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C testdb: mysql_database.present: \- name: {{ salt[\(aqpillar.get\(aq](\(aqmysql:lookup:name\(aq) }} .ft P .fi .UNINDENT .UNINDENT .sp \fB/srv/salt/mysql/user.sls\fP: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C include: \- mysql.testerdb testdb_user: mysql_user.present: \- name: {{ salt[\(aqpillar.get\(aq](\(aqmysql:lookup:user\(aq) }} \- password: {{ salt[\(aqpillar.get\(aq](\(aqmysql:lookup:password\(aq) }} \- host: {{ salt[\(aqpillar.get\(aq](\(aqmysql:lookup:host\(aq) }} \- require: \- sls: mysql.testerdb .ft P .fi .UNINDENT .UNINDENT .sp Now that the database details have been moved to the associated pillar file, only machines which are targeted via pillar will have access to these details. Access to users who should not be able to review these details can also be prevented while ensuring that they are still able to write states which take advantage of this information. .SH REMOTE EXECUTION .sp Running pre\-defined or arbitrary commands on remote hosts, also known as remote execution, is the core function of Salt. The following links explore modules and returners, which are two key elements of remote execution. .sp \fBSalt Execution Modules\fP .sp Salt execution modules are called by the remote execution system to perform a wide variety of tasks. These modules provide functionality such as installing packages, restarting a service, running a remote command, transferring files, and so on. .INDENT 0.0 .INDENT 3.5 .INDENT 0.0 .TP .B Full list of execution modules Contains: a list of core modules that ship with Salt. .TP .B Writing execution modules Contains: a guide on how to write Salt modules. .UNINDENT .UNINDENT .UNINDENT .SS Remote execution tutorial .sp \fBBefore continuing\fP make sure you have a working Salt installation by following the installation and the configuration instructions. .INDENT 0.0 .INDENT 3.5 .IP "Stuck?" .sp There are many ways to get help from the Salt community 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 master and at least one minion 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 salt manpage .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 Grains system .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 the full list of modules .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 Running Commands on Salt Minions .sp Salt can be controlled by a command line client by the root user on the Salt master. The Salt command line client uses the Salt client API to communicate with the Salt master server. The Salt client is straightforward and simple to use. .sp Using the Salt client commands can be easily sent to the minions. .sp Each of these commands accepts an explicit \fI\-\-config\fP option to point to either the master or minion configuration file. If this option is not provided and the default configuration file does not exist then Salt falls back to use the environment variables \fBSALT_MASTER_CONFIG\fP and \fBSALT_MINION_CONFIG\fP\&. .sp \fBSEE ALSO:\fP .INDENT 0.0 .INDENT 3.5 Configuration .UNINDENT .UNINDENT .SS Using the Salt Command .sp The Salt command needs a few components to send information to the Salt minions. The target minions need to be defined, the function to call and any arguments the function requires. .SS Defining the Target Minions .sp The first argument passed to salt, defines the target minions, the target minions are accessed via their hostname. The default target type is a bash glob: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*foo.com\(aq sys.doc .ft P .fi .UNINDENT .UNINDENT .sp Salt can also define the target minions with regular expressions: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt \-E \(aq.*\(aq cmd.run \(aqls \-l | grep foo\(aq .ft P .fi .UNINDENT .UNINDENT .sp Or to explicitly list hosts, salt can take a list: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt \-L foo.bar.baz,quo.qux cmd.run \(aqps aux | grep foo\(aq .ft P .fi .UNINDENT .UNINDENT .SS More Powerful Targets .sp See Targeting\&. .SS Calling the Function .sp The function to call on the specified target is placed after the target specification. .sp New in version 0.9.8. .sp Functions may also accept arguments, space\-delimited: .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\&. .sp Arguments are formatted as YAML: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq cmd.run \(aqecho "Hello: $FIRST_NAME"\(aq saltenv=\(aq{FIRST_NAME: "Joe"}\(aq .ft P .fi .UNINDENT .UNINDENT .sp Note: dictionaries must have curly braces around them (like the \fBsaltenv\fP keyword argument above). This was changed in 0.15.1: in the above example, the first argument used to be parsed as the dictionary \fB{\(aqecho "Hello\(aq: \(aq$FIRST_NAME"\(aq}\fP\&. This was generally not the expected behavior. .sp If you want to test what parameters are actually passed to a module, use the \fBtest.arg_repr\fP command: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq test.arg_repr \(aqecho "Hello: $FIRST_NAME"\(aq saltenv=\(aq{FIRST_NAME: "Joe"}\(aq .ft P .fi .UNINDENT .UNINDENT .SS Finding available minion functions .sp The Salt functions are self documenting, all of the function documentation can be retried from the minions via the \fBsys.doc()\fP function: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq sys.doc .ft P .fi .UNINDENT .UNINDENT .SS Compound Command Execution .sp If a series of commands needs to be sent to a single target specification then the commands can be sent in a single publish. This can make gathering groups of information faster, and lowers the stress on the network for repeated commands. .sp Compound command execution works by sending a list of functions and arguments instead of sending a single function and argument. The functions are executed on the minion in the order they are defined on the command line, and then the data from all of the commands are returned in a dictionary. This means that the set of commands are called in a predictable way, and the returned data can be easily interpreted. .sp Executing compound commands if done by passing a comma delimited list of functions, followed by a comma delimited list of arguments: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq cmd.run,test.ping,test.echo \(aqcat /proc/cpuinfo\(aq,,foo .ft P .fi .UNINDENT .UNINDENT .sp The trick to look out for here, is that if a function is being passed no arguments, then there needs to be a placeholder for the absent arguments. This is why in the above example, there are two commas right next to each other. \fBtest.ping\fP takes no arguments, so we need to add another comma, otherwise Salt would attempt to pass "foo" to \fBtest.ping\fP\&. .sp If you need to pass arguments that include commas, then make sure you add spaces around the commas that separate arguments. For example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq cmd.run,test.ping,test.echo \(aqecho "1,2,3"\(aq , , foo .ft P .fi .UNINDENT .UNINDENT .sp You may change the arguments separator using the \fB\-\-args\-separator\fP option: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt \-\-args\-separator=:: \(aq*\(aq some.fun,test.echo params with , comma :: foo .ft P .fi .UNINDENT .UNINDENT .SS CLI Completion .sp Shell completion scripts for the Salt CLI are available in the \fBpkg\fP Salt \fI\%source directory\fP\&. .SS Writing Execution Modules .sp Salt execution modules are the functions called by the \fBsalt\fP command. .SS Modules Are Easy to Write! .sp Writing Salt execution modules is straightforward. .sp A Salt execution module is a Python or \fI\%Cython\fP module placed in a directory called \fB_modules/\fP at the root of the Salt fileserver. When using the default fileserver backend (i.e. \fBroots .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 Zip Archives as Modules .sp Python 2.3 and higher allows developers to directly import zip archives containing Python code. By setting \fBenable_zip_modules\fP to \fBTrue\fP in the minion config, the Salt loader will be able to import \fB\&.zip\fP files in this fashion. This allows Salt module developers to package dependencies with their modules for ease of deployment, isolation, etc. .sp For a user, Zip Archive modules behave just like other modules. When executing a function from a module provided as the file \fBmy_module.zip\fP, a user would call a function within that module as \fBmy_module.\fP\&. .SS Creating a Zip Archive Module .sp A Zip Archive module is structured similarly to a simple \fI\%Python package\fP\&. The \fB\&.zip\fP file contains a single directory with the same name as the module. The module code traditionally in \fB.py\fP goes in \fB/__init__.py\fP\&. The dependency packages are subdirectories of \fB/\fP\&. .sp Here is an example directory structure for the \fBlumberjack\fP module, which has two library dependencies (\fBsleep\fP and \fBwork\fP) to be included. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C modules $ ls \-R lumberjack __init__.py sleep work lumberjack/sleep: __init__.py lumberjack/work: __init__.py .ft P .fi .UNINDENT .UNINDENT .sp The contents of \fBlumberjack/__init__.py\fP show how to import and use these included libraries. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C # Libraries included in lumberjack.zip from lumberjack import sleep, work def is_ok(person): \(aq\(aq\(aq Checks whether a person is really a lumberjack \(aq\(aq\(aq return sleep.all_night(person) and work.all_day(person) .ft P .fi .UNINDENT .UNINDENT .sp Then, create the zip: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C modules $ zip \-r lumberjack lumberjack adding: lumberjack/ (stored 0%) adding: lumberjack/__init__.py (deflated 39%) adding: lumberjack/sleep/ (stored 0%) adding: lumberjack/sleep/__init__.py (deflated 7%) adding: lumberjack/work/ (stored 0%) adding: lumberjack/work/__init__.py (deflated 7%) modules $ unzip \-l lumberjack.zip Archive: lumberjack.zip Length Date Time Name \-\-\-\-\-\-\-\- \-\-\-\- \-\-\-\- \-\-\-\- 0 08\-21\-15 20:08 lumberjack/ 348 08\-21\-15 20:08 lumberjack/__init__.py 0 08\-21\-15 19:53 lumberjack/sleep/ 83 08\-21\-15 19:53 lumberjack/sleep/__init__.py 0 08\-21\-15 19:53 lumberjack/work/ 81 08\-21\-15 19:21 lumberjack/work/__init__.py \-\-\-\-\-\-\-\- \-\-\-\-\-\-\- 512 6 files .ft P .fi .UNINDENT .UNINDENT .sp Once placed in \fBfile_roots\fP, Salt users can distribute and use \fBlumberjack.zip\fP like any other module. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C $ sudo salt minion1 saltutil.sync_modules minion1: \- modules.lumberjack $ sudo salt minion1 lumberjack.is_ok \(aqMichael Palin\(aq minion1: True .ft P .fi .UNINDENT .UNINDENT .SS Cross Calling Execution Modules .sp All of the Salt execution modules are available to each other and modules can call functions available in other execution modules. .sp The variable \fB__salt__\fP is packed into the modules after they are loaded into the Salt minion. .sp The \fB__salt__\fP variable is a \fI\%Python dictionary\fP containing all of the Salt functions. Dictionary keys are strings representing the names of the modules and the values are the functions themselves. .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 \fIrun\fP function in the \fBcmd\fP module and pass the argument \fBbar\fP to it. .SS Calling Execution Modules on the Salt Master .sp New in version 2016.11.0. .sp Execution modules can now also be called via the \fBsalt\-run\fP command using the salt runner\&. .SS Preloaded Execution Module Data .sp When interacting with execution modules often it is nice to be able to read information dynamically about the minion or to load in configuration parameters for a module. .sp Salt allows for different types of data to be loaded into the modules by the minion. .SS Grains Data .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 dictionary 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 \-\-output=pprint .ft P .fi .UNINDENT .UNINDENT .sp Any value in a grains dictionary can be accessed as any other Python dictionary. For example, the grain representing the minion ID is stored in the \fBid\fP key and from an execution module, the value would be stored in \fB__grains__[\(aqid\(aq]\fP\&. .SS Module Configuration .sp Since parameters for configuring a module may be desired, Salt allows for configuration information from the minion configuration file to be passed to execution 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 therefore \fBstrongly\fP recommended that the values passed in the configuration file match the module name. A value intended for the \fBtest\fP execution module should be named \fBtest.\fP\&. .sp The test execution 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 Strings and Unicode .sp An execution module author should always assume that strings fed to the module have already decoded from strings into Unicode. In Python 2, these will be of type \(aqUnicode\(aq and in Python 3 they will be of type \fBstr\fP\&. Calling from a state to other Salt sub\-systems, should pass Unicode (or bytes if passing binary data). In the rare event that a state needs to write directly to disk, Unicode should be encoded to a string immediately before writing to disk. An author may use \fB__salt_system_encoding__\fP to learn what the encoding type of the system is. For example, \fI\(aqmy_string\(aq.encode(__salt_system_encoding__\(aq)\fP\&. .SS Outputter Configuration .sp Since execution module functions can return different data, and the way the data is printed can greatly change the presentation, Salt allows for a specific outputter to be set on a function\-by\-function basis. .sp This is done be declaring an \fB__outputter__\fP dictionary in the global scope of the module. The \fB__outputter__\fP dictionary contains a mapping of function names to Salt outputters\&. .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 \fBtxt\fP outputter is used to display output from the \fBrun\fP function. .SS Virtual Modules .sp Virtual modules let you override the name of a module in order to use the same name to refer to one of several similar modules. The specific module that is loaded for a virtual name is selected based on the current platform or environment. .sp For example, packages are managed across platforms using the \fBpkg\fP module. \fBpkg\fP is a virtual module name that is an alias for the specific package manager module that is loaded on a specific system (for example, \fByumpkg\fP on RHEL/CentOS systems , and \fBaptpkg\fP on Ubuntu). .sp Virtual module names are set using the \fB__virtual__\fP function and the \fI\%virtual name\fP\&. .SS \fB__virtual__\fP Function .sp The \fB__virtual__\fP function returns either a \fI\%string\fP, \fI\%True\fP, \fI\%False\fP, or \fI\%False\fP with an \fI\%error string\fP\&. If a string is returned then the module is loaded using the name of the string as the virtual name. If \fBTrue\fP is returned the module is loaded using the current module name. If \fBFalse\fP is returned the module is not loaded. \fBFalse\fP lets the module perform system checks and prevent loading if dependencies are not met. .sp Since \fB__virtual__\fP is called before the module is loaded, \fB__salt__\fP will be unavailable as it will not have been packed into the module at this point in time. .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 Modules which return a string from \fB__virtual__\fP that is already used by a module that ships with Salt will _override_ the stock module. .UNINDENT .UNINDENT .SS Returning Error Information from \fB__virtual__\fP .sp Optionally, Salt plugin modules, such as execution, state, returner, beacon, etc. modules may additionally return a string containing the reason that a module could not be loaded. For example, an execution module called \fBcheese\fP and a corresponding state module also called \fBcheese\fP, both depending on a utility called \fBenzymes\fP should have \fB__virtual__\fP functions that handle the case when the dependency is unavailable. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C \(aq\(aq\(aq Cheese execution (or returner/beacon/etc.) module \(aq\(aq\(aq try: import enzymes HAS_ENZYMES = True except ImportError: HAS_ENZYMES = False def __virtual__(): \(aq\(aq\(aq only load cheese if enzymes are available \(aq\(aq\(aq if HAS_ENZYMES: return \(aqcheese\(aq else: return False, \(aqThe cheese execution module cannot be loaded: enzymes unavailable.\(aq .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C \(aq\(aq\(aq Cheese state module \(aq\(aq\(aq def __virtual__(): \(aq\(aq\(aq only load cheese if enzymes are available \(aq\(aq\(aq # predicate loading of the cheese state on the corresponding execution module if \(aqcheese.slice\(aq in __salt__: return \(aqcheese\(aq else: return False, \(aqThe cheese state module cannot be loaded: enzymes unavailable.\(aq .ft P .fi .UNINDENT .UNINDENT .SS Examples .sp The package manager modules are among the best examples of using the \fB__virtual__\fP function. A table of all the virtual \fBpkg\fP modules can be found here\&. .SS Overriding Virtual Module Providers .sp Salt often uses OS grains (\fBos\fP, \fBosrelease\fP, \fBos_family\fP, etc.) to determine which module should be loaded as the virtual module for \fBpkg\fP, \fBservice\fP, etc. Sometimes this OS detection is incomplete, with new distros popping up, existing distros changing init systems, etc. The virtual modules likely to be affected by this are in the list below (click each item for more information): .INDENT 0.0 .IP \(bu 2 pkg .IP \(bu 2 service .IP \(bu 2 user .IP \(bu 2 shadow .IP \(bu 2 group .UNINDENT .sp If Salt is using the wrong module for one of these, first of all, please \fI\%report it on the issue tracker\fP, so that this issue can be resolved for a future release. To make it easier to troubleshoot, please also provide the \fBgrains.items\fP output, taking care to redact any sensitive information. .sp Then, while waiting for the SaltStack development team to fix the issue, Salt can be made to use the correct module using the \fBproviders\fP option in the minion config file: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C providers: service: systemd pkg: aptpkg .ft P .fi .UNINDENT .UNINDENT .sp The above example will force the minion to use the \fBsystemd\fP module to provide service management, and the \fBaptpkg\fP module to provide package management. .SS \fB__virtualname__\fP .sp \fB__virtualname__\fP is a variable that is used by the documentation build system to know the virtual name of a module without calling the \fB__virtual__\fP function. Modules that return a string from the \fB__virtual__\fP function must also set the \fB__virtualname__\fP variable. .sp To avoid setting the virtual name string twice, you can implement \fB__virtual__\fP to return the value set for \fB__virtualname__\fP using a pattern similar to the following: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C # Define the module\(aqs virtual name __virtualname__ = \(aqpkg\(aq def __virtual__(): \(aq\(aq\(aq Confine this module to Mac OS with Homebrew. \(aq\(aq\(aq if salt.utils.which(\(aqbrew\(aq) and __grains__[\(aqos\(aq] == \(aqMacOS\(aq: return __virtualname__ return False .ft P .fi .UNINDENT .UNINDENT .SS Documentation .sp Salt execution modules are documented. 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 The \fBsys.doc\fP function simply prints out the docstrings found in the modules; when writing Salt execution modules, please follow the formatting conventions for docstrings as they appear in the other modules. .SS Adding Documentation to Salt Modules .sp It is strongly suggested that all Salt modules have documentation added. .sp To add documentation 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. .sp Documentation added to execution modules in docstrings will automatically be added to the online web\-based documentation. .SS Add Execution Module Metadata .sp When writing a Python docstring for an execution module, 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 Log Output .sp You can call the logger from custom modules to write messages to the minion logs. The following code snippet demonstrates writing log messages: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C import logging log = logging.getLogger(__name__) log.info(\(aqHere is Some Information\(aq) log.warning(\(aqYou Should Not Do That\(aq) log.error(\(aqIt Is Busted\(aq) .ft P .fi .UNINDENT .UNINDENT .SS Aliasing Functions .sp Sometimes one wishes to use a function name that would shadow a python built\-in. A common example would be \fBset()\fP\&. To support this, append an underscore to the function definition, \fBdef set_():\fP, and use the \fB__func_alias__\fP feature to provide an alias to the function. .sp \fB__func_alias__\fP is a dictionary where each key is the name of a function in the module, and each value is a string representing the alias for that function. When calling an aliased function from a different execution module, state module, or from the cli, the alias name should be used. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C __func_alias__ = { \(aqset_\(aq: \(aqset\(aq, \(aqlist_\(aq: \(aqlist\(aq, } .ft P .fi .UNINDENT .UNINDENT .SS Private Functions .sp In Salt, Python callable objects contained within an execution 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 .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 .SS Useful Decorators for Modules .SS Depends Decorator .sp When writing execution modules there are many times where some of the module will work on all hosts but some functions have an external dependency, such as a service that needs to be installed or a binary that needs to be present on the system. .sp Instead of trying to wrap much of the code in large try/except blocks, a decorator can be used. .sp If the dependencies passed to the decorator don\(aqt exist, then the salt minion will remove those functions from the module on that host. .sp If a \fBfallback_function\fP is defined, it will replace the function instead of removing it .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C import logging from salt.utils.decorators import depends log = logging.getLogger(__name__) try: import dependency_that_sometimes_exists except ImportError as e: log.trace(\(aqFailed to import dependency_that_sometimes_exists: {0}\(aq.format(e)) @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 .sp In addition to global dependencies the depends decorator also supports raw booleans. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C from salt.utils.decorators import depends HAS_DEP = False try: import dependency_that_sometimes_exists HAS_DEP = True except ImportError: pass @depends(HAS_DEP) def foo(): return True .ft P .fi .UNINDENT .UNINDENT .SH CONFIGURATION MANAGEMENT .sp Salt contains a robust and flexible configuration management framework, which is built on the remote execution core. This framework executes on the minions, allowing effortless, simultaneous configuration of tens of thousands of hosts, by rendering language specific state files. The following links provide resources to learn more about state and renderers. .INDENT 0.0 .TP \fBStates\fP Express the state of a host using small, easy to read, easy to understand configuration files. \fINo programming required\fP\&. .INDENT 7.0 .TP .B Full list of states Contains: list of install packages, create users, transfer files, start services, and so on. .TP .B Pillar System Contains: description of Salt\(aqs Pillar system. .TP .B Highstate data structure Contains: a dry vocabulary and technical representation of the configuration format that states represent. .TP .B Writing states Contains: a guide on how to write Salt state modules, easily extending Salt to directly manage more software. .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 Salt execution modules are different from state modules and cannot be called as a state in an SLS file. In other words, this will not work: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C moe: user.rename: \- new_name: larry \- onlyif: id moe .ft P .fi .UNINDENT .UNINDENT .sp You must use the \fBmodule\fP states to call execution modules directly. Here\(aqs an example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C rename_moe: module.run: \- m_name: moe \- new_name: larry \- onlyif: id moe .ft P .fi .UNINDENT .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP \fBRenderers\fP Renderers use state configuration files written in a variety of languages, templating engines, or files. Salt\(aqs configuration management system is, under the hood, language agnostic. .INDENT 7.0 .TP .B Full list of renderers Contains: a list of renderers. YAML is one choice, but many systems are available, from alternative templating engines to the PyDSL language for rendering sls formulas. .TP .B Renderers Contains: more information about renderers. Salt states are only concerned with the ultimate highstate data structure, not how the data structure was created. .UNINDENT .UNINDENT .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 Pillar 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 here\&. .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 third lines contain the state module function to be run, in the format \fB.\fP\&. The \fBpkg.installed\fP state module function ensures that a software package is installed via the system\(aqs native package manager. The \fBservice.running\fP state module function ensures that a given system daemon is running. .sp Finally, on line five, 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. .INDENT 0.0 .INDENT 3.5 .IP "Do not use dots in SLS file names or their directories" .sp The initial implementation of \fBtop.sls\fP and include\-declaration followed the python import model where a slash is represented as a period. This means that a SLS file with a period in the name ( besides the suffix period) can not be referenced. For example, webserver_1.0.sls is not referenceable because webserver_1.0 would refer to the directory/file webserver_1/0.sls .sp The same applies for any subdirectories, this is especially \(aqtricky\(aq when git repos are created. Another command that typically can\(aqt render it\(aqs output is \fB\(gastate.show_sls\(ga\fP of a file in a path that contains a dot. .UNINDENT .UNINDENT .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 States Tutorial\&. .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, \fBpydsl\fP & \fBpyobjects\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; and the \fBpyobjects\fP renderer gives you a \fI\%"Pythonic"\fP interface to building state data. .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 file state, as well as the \fI\%MooseFS 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, PyDSL, and the Pyobjects 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 HighState data structure\&. .sp Alternatively, using the \fBpydsl\fP renderer, the above example can be written more succinctly as: .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 The \fBpyobjects\fP renderer provides an \fI\%"Pythonic"\fP object based approach for building the state data. The above example could be written as: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C #!pyobjects include(\(aqpython\(aq) Pkg.installed("django") .ft P .fi .UNINDENT .UNINDENT .sp These 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.apply\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 to examine the output for errors: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt\-call state.apply \-l debug .ft P .fi .UNINDENT .UNINDENT .sp This should help troubleshoot the issue. The minion can also be started in the foreground in debug mode by running \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 Pillar Walkthrough .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 states reference\&. .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 installation and the configuration instructions. .INDENT 0.0 .INDENT 3.5 .IP "Stuck?" .sp There are many ways to get help from the Salt community 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 \fBState 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 top file 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 grains\&. 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 top file, 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 id\-declaration, 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 state\-declaration, 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 function\-declaration, defines which function in the \fBpkg state\fP module to call. .INDENT 0.0 .INDENT 3.5 .IP "Renderers" .sp States \fBsls\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 renderers 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.apply .ft P .fi .UNINDENT .UNINDENT .sp Our master is instructing all targeted minions to run \fBstate.apply\fP\&. When this function is executed without any SLS targets, a minion will download the top file and attempt to match the expressions within it. When the minion does match an expression the modules listed for it will be downloaded, compiled, and executed. .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 This action is referred to as a "highstate", and can be run using the \fBstate.highstate\fP function. However, to make the usage easier to understand ("highstate" is not necessarily an intuitive name), a \fBstate.apply\fP function was added in version 2015.5.0, which when invoked without any SLS names will trigger a highstate. \fBstate.highstate\fP still exists and can be used, but the documentation (as can be seen above) has been updated to reference \fBstate.apply\fP, so keep the following in mind as you read the documentation: .INDENT 0.0 .IP \(bu 2 \fBstate.apply\fP invoked without any SLS names will run \fBstate.highstate\fP .IP \(bu 2 \fBstate.apply\fP invoked with SLS names will run \fBstate.sls\fP .UNINDENT .UNINDENT .UNINDENT .sp Once completed, the minion will report back with a summary of all actions taken and all changes made. .sp \fBWARNING:\fP .INDENT 0.0 .INDENT 3.5 If you have created custom grain modules, they will not be available in the top file until after the first \fI\%highstate\fP\&. To make custom grains available on a minion\(aqs first \fI\%highstate\fP, it is recommended to use this example to ensure that the custom grains are synced when the minion starts. .UNINDENT .UNINDENT .INDENT 0.0 .INDENT 3.5 .IP "SLS File Namespace" .sp Note that in the \fI\%example\fP above, the SLS file \fBwebserver.sls\fP was referred to simply as \fBwebserver\fP\&. The namespace for SLS files when referenced in \fBtop.sls\fP or an include\-declaration 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 with a dot (following the Python import model) in Salt states and on the command line . \fBwebserver/dev.sls\fP on the filesystem is referred to as \fBwebserver.dev\fP in Salt .IP b. 3 Because slashes are represented as dots, SLS files can not contain dots in the name (other than the dot for the SLS suffix). The SLS file \fBwebserver_1.0.sls\fP can not be matched, and \fBwebserver_1.0\fP would match the directory/file \fBwebserver_1/0.sls\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 (\fB\-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.apply \-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. Part 2 will build on this example to cover more advanced \fBsls\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 part 1\&. It is recommended that you begin there. .UNINDENT .UNINDENT .sp In the last part 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 state\-declaration under an id\-declaration\&. 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.apply\fP once again and observe the output. .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 For those running RedhatOS derivatives (Centos, AWS), you will want to specify the service name to be httpd. More on state service here, \fBservice state\fP\&. With the example above, just add "\- name: httpd" above the require line and with the same spacing. .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 7\fP is the id\-declaration\&. In this example it is the location we want to install our custom HTML file. (\fBNote:\fP the default location that Apache serves may differ from the above on your OS or distro. \fB/srv/www\fP could also be a likely place to look.) .sp \fBLine 8\fP the state\-declaration\&. This example uses the Salt \fBfile state\fP\&. .sp \fBLine 9\fP is the function\-declaration\&. The \fBmanaged function\fP will download a file from the master and install it in the location specified. .sp \fBLine 10\fP is a function\-arg\-declaration which, in this example, passes the \fBsource\fP argument to the \fBmanaged function\fP\&. .sp \fBLine 11\fP is a requisite\-declaration\&. .sp \fBLine 12\fP is a requisite\-reference which refers to a state and an ID. In this example, it is referring to the \fBID declaration\fP from our example in part 1\&. 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.apply\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.apply .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 requisite\-declaration, “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 name\-declaration which explained in Part 3\&. .UNINDENT .UNINDENT .SS Next steps .sp In part 3 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 part 1 and part 2\&. 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 # Comments in yaml start with a hash symbol. # Since jinja rendering occurs before yaml parsing, if you want to include jinja # in the comments you may need to escape them using \(aqjinja\(aq comments to prevent # jinja from trying to render something which is not well\-defined jinja. # e.g. # {# iterate over the Three Stooges using a {% for %}..{% endfor %} loop # with the iterator variable {{ usr }} becoming the state ID. #} {% 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. Salt grains 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 Using Environment Variables in SLS modules .sp You can use \fBsalt[\(aqenviron.get\(aq](\(aqVARNAME\(aq)\fP to use an environment variable in a Salt state. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C MYENVVAR="world" salt\-call state.template test.sls .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C Create a file with contents from an environment variable: file.managed: \- name: /tmp/hello \- contents: {{ salt[\(aqenviron.get\(aq](\(aqMYENVVAR\(aq) }} .ft P .fi .UNINDENT .UNINDENT .sp Error checking: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C {% set myenvvar = salt[\(aqenviron.get\(aq](\(aqMYENVVAR\(aq) %} {% if myenvvar %} Create a file with contents from an environment variable: file.managed: \- name: /tmp/hello \- contents: {{ salt[\(aqenviron.get\(aq](\(aqMYENVVAR\(aq) }} {% else %} Fail \- no environment passed in: test: A. fail_without_changes {% 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 .sp The following example illustrates calling the \fBgroup_to_gid\fP function in the \fBfile\fP execution module with a single positional argument called \fBsome_group_that_exists\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 One way to think about this might be that the \fBgid\fP key is being assigned a value equivelent to the following python pseudo\-code: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C import salt.modules.file file.group_to_gid(\(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 .sp To examine the possible arguments to each execution module function, one can examine the \fImodule reference documentation \fP: .SS Advanced SLS module syntax .sp Lastly, we will cover some incredibly useful techniques for more complex State trees. .SS Include declaration .sp A previous example showed how to spread a Salt tree across several files. Similarly, requisites span multiple files by using an include\-declaration\&. 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 Extend declaration .sp You can modify previous declarations by using an extend\-declaration\&. 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 Name declaration .sp You can override the id\-declaration by using a name\-declaration\&. 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 Names declaration .sp Even more powerful is using a names\-declaration to override the id\-declaration 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 part 4 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 part 1, part 2, and part 3\&. 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\&. .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 When using multiple fileserver backends, the order in which they are listed in the \fBfileserver_backend\fP parameter also matters. If both \fBroots\fP and \fBgit\fP backends contain a file with the same relative path, and \fBroots\fP appears before \fBgit\fP in the \fBfileserver_backend\fP list, then the file in \fBroots\fP will "win", and the file in gitfs will be ignored. .sp A more thorough explanation of how Salt\(aqs modular fileserver works can be found here\&. We recommend reading this. .UNINDENT .UNINDENT .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 Requesting files from specific fileserver environments .sp See here for documentation on how to request files from specific 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.apply\fP: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt \-\-pillar \(aqwebserver_role:dev\(aq state.apply .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, by invoking \fBstate.apply\fP with the desired SLS target as an argument: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt \-\-pillar \(aqwebserver_role:dev\(aq state.apply 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.apply 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.apply 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 reference documentation and to look through examples of existing state trees. 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 active community and we\(aqd love to hear from you. .sp In addition, by continuing to the Orchestrate Runner docs, you can learn about the powerful orchestration of which Salt is capable. .SS State System Reference .sp Salt offers an interface to manage the configuration or "state" of the Salt minions. This interface is a fully capable mechanism used to enforce the state of systems from a central manager. .SS Mod Aggregate State Runtime Modifications .sp New in version 2014.7.0. .sp The mod_aggregate system was added in the 2014.7.0 release of Salt and allows for runtime modification of the executing state data. Simply put, it allows for the data used by Salt\(aqs state system to be changed on the fly at runtime, kind of like a configuration management JIT compiler or a runtime import system. All in all, it makes Salt much more dynamic. .SS How it Works .sp The best example is the \fBpkg\fP state. One of the major requests in Salt has long been adding the ability to install all packages defined at the same time. The mod_aggregate system makes this a reality. While executing Salt\(aqs state system, when a \fBpkg\fP state is reached the \fBmod_aggregate\fP function in the state module is called. For \fBpkg\fP this function scans all of the other states that are slated to run, and picks up the references to \fBname\fP and \fBpkgs\fP, then adds them to \fBpkgs\fP in the first state. The result is a single call to yum, apt\-get, pacman, etc as part of the first package install. .SS How to Use it .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 Since this option changes the basic behavior of the state runtime, after it is enabled states should be executed using \fItest=True\fP to ensure that the desired behavior is preserved. .UNINDENT .UNINDENT .SS In config files .sp The first way to enable aggregation is with a configuration option in either the master or minion configuration files. Salt will invoke \fBmod_aggregate\fP the first time it encounters a state module that has aggregate support. .sp If this option is set in the master config it will apply to all state runs on all minions, if set in the minion config it will only apply to said minion. .sp Enable for all states: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C state_aggregate: True .ft P .fi .UNINDENT .UNINDENT .sp Enable for only specific state modules: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C state_aggregate: \- pkg .ft P .fi .UNINDENT .UNINDENT .SS In states .sp The second way to enable aggregation is with the state\-level \fBaggregate\fP keyword. In this configuration, Salt will invoke the \fBmod_aggregate\fP function the first time it encounters this keyword. Any additional occurrences of the keyword will be ignored as the aggregation has already taken place. .sp The following example will trigger \fBmod_aggregate\fP when the \fBlamp_stack\fP state is processed resulting in a single call to the underlying package manager. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C lamp_stack: pkg.installed: \- pkgs: \- php \- mysql\-client \- aggregate: True memcached: pkg.installed: \- name: memcached .ft P .fi .UNINDENT .UNINDENT .SS Adding mod_aggregate to a State Module .sp Adding a mod_aggregate routine to an existing state module only requires adding an additional function to the state module called mod_aggregate. .sp The mod_aggregate function just needs to accept three parameters and return the low data to use. Since mod_aggregate is working on the state runtime level it does need to manipulate \fIlow data\fP\&. .sp The three parameters are \fIlow\fP, \fIchunks\fP, and \fIrunning\fP\&. The \fIlow\fP option is the low data for the state execution which is about to be called. The \fIchunks\fP is the list of all of the low data dictionaries which are being executed by the runtime and the \fIrunning\fP dictionary is the return data from all of the state executions which have already be executed. .sp This example, simplified from the pkg state, shows how to create mod_aggregate functions: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C def mod_aggregate(low, chunks, running): \(aq\(aq\(aq The mod_aggregate function which looks up all packages in the available low chunks and merges them into a single pkgs ref in the present low data \(aq\(aq\(aq pkgs = [] # What functions should we aggregate? agg_enabled = [ \(aqinstalled\(aq, \(aqlatest\(aq, \(aqremoved\(aq, \(aqpurged\(aq, ] # The \(galow\(ga data is just a dict with the state, function (fun) and # arguments passed in from the sls if low.get(\(aqfun\(aq) not in agg_enabled: return low # Now look into what other things are set to execute for chunk in chunks: # The state runtime uses "tags" to track completed jobs, it may # look familiar with the _|\- tag = salt.utils.gen_state_tag(chunk) if tag in running: # Already ran the pkg state, skip aggregation continue if chunk.get(\(aqstate\(aq) == \(aqpkg\(aq: if \(aq__agg__\(aq in chunk: continue # Check for the same function if chunk.get(\(aqfun\(aq) != low.get(\(aqfun\(aq): continue # Pull out the pkg names! if \(aqpkgs\(aq in chunk: pkgs.extend(chunk[\(aqpkgs\(aq]) chunk[\(aq__agg__\(aq] = True elif \(aqname\(aq in chunk: pkgs.append(chunk[\(aqname\(aq]) chunk[\(aq__agg__\(aq] = True if pkgs: if \(aqpkgs\(aq in low: low[\(aqpkgs\(aq].extend(pkgs) else: low[\(aqpkgs\(aq] = pkgs # The low has been modified and needs to be returned to the state # runtime for execution return low .ft P .fi .UNINDENT .UNINDENT .SS Altering States .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 This documentation has been moved here\&. .UNINDENT .UNINDENT .SS File State Backups .sp In 0.10.2 a new feature was added for backing up files that are replaced by the file.managed and file.recurse states. The new feature is called the backup mode. Setting the backup mode is easy, but it can be set in a number of places. .sp The backup_mode can be set in the minion config file: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C backup_mode: minion .ft P .fi .UNINDENT .UNINDENT .sp Or it can be set for each file: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C /etc/ssh/sshd_config: file.managed: \- source: salt://ssh/sshd_config \- backup: minion .ft P .fi .UNINDENT .UNINDENT .SS Backed\-up Files .sp The files will be saved in the minion cachedir under the directory named \fBfile_backup\fP\&. The files will be in the location relative to where they were under the root filesystem and be appended with a timestamp. This should make them easy to browse. .SS Interacting with Backups .sp Starting with version 0.17.0, it will be possible to list, restore, and delete previously\-created backups. .SS Listing .sp The backups for a given file can be listed using \fBfile.list_backups\fP: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C # salt foo.bar.com file.list_backups /tmp/foo.txt foo.bar.com: \-\-\-\-\-\-\-\-\-\- 0: \-\-\-\-\-\-\-\-\-\- Backup Time: Sat Jul 27 2013 17:48:41.738027 Location: /var/cache/salt/minion/file_backup/tmp/foo.txt_Sat_Jul_27_17:48:41_738027_2013 Size: 13 1: \-\-\-\-\-\-\-\-\-\- Backup Time: Sat Jul 27 2013 17:48:28.369804 Location: /var/cache/salt/minion/file_backup/tmp/foo.txt_Sat_Jul_27_17:48:28_369804_2013 Size: 35 .ft P .fi .UNINDENT .UNINDENT .SS Restoring .sp Restoring is easy using \fBfile.restore_backup\fP, just pass the path and the numeric id found with \fBfile.list_backups\fP: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C # salt foo.bar.com file.restore_backup /tmp/foo.txt 1 foo.bar.com: \-\-\-\-\-\-\-\-\-\- comment: Successfully restored /var/cache/salt/minion/file_backup/tmp/foo.txt_Sat_Jul_27_17:48:28_369804_2013 to /tmp/foo.txt result: True .ft P .fi .UNINDENT .UNINDENT .sp The existing file will be backed up, just in case, as can be seen if \fBfile.list_backups\fP is run again: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C # salt foo.bar.com file.list_backups /tmp/foo.txt foo.bar.com: \-\-\-\-\-\-\-\-\-\- 0: \-\-\-\-\-\-\-\-\-\- Backup Time: Sat Jul 27 2013 18:00:19.822550 Location: /var/cache/salt/minion/file_backup/tmp/foo.txt_Sat_Jul_27_18:00:19_822550_2013 Size: 53 1: \-\-\-\-\-\-\-\-\-\- Backup Time: Sat Jul 27 2013 17:48:41.738027 Location: /var/cache/salt/minion/file_backup/tmp/foo.txt_Sat_Jul_27_17:48:41_738027_2013 Size: 13 2: \-\-\-\-\-\-\-\-\-\- Backup Time: Sat Jul 27 2013 17:48:28.369804 Location: /var/cache/salt/minion/file_backup/tmp/foo.txt_Sat_Jul_27_17:48:28_369804_2013 Size: 35 .ft P .fi .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 Since no state is being run, restoring a file will not trigger any watches for the file. So, if you are restoring a config file for a service, it will likely still be necessary to run a \fBservice.restart\fP\&. .UNINDENT .UNINDENT .SS Deleting .sp Deleting backups can be done using \fBfile.delete_backup\fP: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C # salt foo.bar.com file.delete_backup /tmp/foo.txt 0 foo.bar.com: \-\-\-\-\-\-\-\-\-\- comment: Successfully removed /var/cache/salt/minion/file_backup/tmp/foo.txt_Sat_Jul_27_18:00:19_822550_2013 result: True .ft P .fi .UNINDENT .UNINDENT .SS Understanding State Compiler 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: \- name: httpd service.running: \- name: httpd \- watch: \- file: apache_conf \- pkg: apache apache_conf: file.managed: \- name: /etc/httpd/conf.d/httpd.conf \- 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": [ { "name": "httpd" }, "installed", { "order": 10000 } ], "service": [ { "name": "httpd" }, { "watch": [ { "file": "apache_conf" }, { "pkg": "apache" } ] }, "running", { "order": 10001 } ], "__sls__": "blah", "__env__": "base" }, "apache_conf": { "file": [ { "name": "/etc/httpd/conf.d/httpd.conf" }, { "source": "salt://apache/httpd.conf" }, "managed", { "order": 10002 } ], "__sls__": "blah", "__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": "httpd", "state": "pkg", "__id__": "apache", "fun": "installed", "__env__": "base", "__sls__": "blah", "order": 10000 }, { "name": "httpd", "watch": [ { "file": "apache_conf" }, { "pkg": "apache" } ], "state": "service", "__id__": "apache", "fun": "running", "__env__": "base", "__sls__": "blah", "order": 10001 }, { "name": "/etc/httpd/conf.d/httpd.conf", "source": "salt://apache/httpd.conf", "state": "file", "__id__": "apache_conf", "fun": "managed", "__env__": "base", "__sls__": "blah", "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 \fBstate_auto_order\fP to \fBFalse\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 \fIDefinition 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 \fBstate.apply 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 \fBorder\fP flag in states: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C apache: pkg.installed: \- name: httpd \- 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 \fBorder: last\fP or \fBorder: \-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 \fBstate_auto_order: False\fP the \fBorder\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, \fBrequire\fP then \fBwatch\fP then \fBprereq\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 \fBTrue\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 Extending External SLS Data .sp Sometimes a state defined in one SLS file will need to be modified from a separate SLS file. A good example of this is when an argument needs to be overwritten or when a service needs to watch an additional state. .SS The Extend Declaration .sp The standard way to extend is via the extend declaration. The extend declaration is a top level declaration like \fBinclude\fP and encapsulates ID declaration data included from other SLS files. A standard extend looks like this: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C include: \- http \- ssh extend: apache: file: \- name: /etc/httpd/conf/httpd.conf \- source: salt://http/httpd2.conf ssh\-server: service: \- watch: \- file: /etc/ssh/banner /etc/ssh/banner: file.managed: \- source: salt://ssh/banner .ft P .fi .UNINDENT .UNINDENT .sp A few critical things happened here, first off the SLS files that are going to be extended are included, then the extend dec is defined. Under the extend dec 2 IDs are extended, the apache ID\(aqs file state is overwritten with a new name and source. Then the ssh server is extended to watch the banner file in addition to anything it is already watching. .SS Extend is a Top Level Declaration .sp This means that \fBextend\fP can only be called once in an sls, if if is used twice then only one of the extend blocks will be read. So this is WRONG: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C include: \- http \- ssh extend: apache: file: \- name: /etc/httpd/conf/httpd.conf \- source: salt://http/httpd2.conf # Second extend will overwrite the first!! Only make one extend: ssh\-server: service: \- watch: \- file: /etc/ssh/banner .ft P .fi .UNINDENT .UNINDENT .SS The Requisite "in" Statement .sp Since one of the most common things to do when extending another SLS is to add states for a service to watch, or anything for a watcher to watch, the requisite in statement was added to 0.9.8 to make extending the watch and require lists easier. The ssh\-server extend statement above could be more cleanly defined like so: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C include: \- ssh /etc/ssh/banner: file.managed: \- source: salt://ssh/banner \- watch_in: \- service: ssh\-server .ft P .fi .UNINDENT .UNINDENT .SS Rules to Extend By .sp There are a few rules to remember when extending states: .INDENT 0.0 .IP 1. 3 Always include the SLS being extended with an include declaration .IP 2. 3 Requisites (watch and require) are appended to, everything else is overwritten .IP 3. 3 extend is a top level declaration, like an ID declaration, cannot be declared twice in a single SLS .IP 4. 3 Many IDs can be extended under the extend declaration .UNINDENT .SS Failhard Global Option .sp Normally, when a state fails Salt continues to execute the remainder of the defined states and will only refuse to execute states that require the failed state. .sp But the situation may exist, where you would want all state execution to stop if a single state execution fails. The capability to do this is called \fBfailing hard\fP\&. .SS State Level Failhard .sp A single state can have a failhard set, this means that if this individual state fails that all state execution will immediately stop. This is a great thing to do if there is a state that sets up a critical config file and setting a require for each state that reads the config would be cumbersome. A good example of this would be setting up a package manager early on: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C /etc/yum.repos.d/company.repo: file.managed: \- source: salt://company/yumrepo.conf \- user: root \- group: root \- mode: 644 \- order: 1 \- failhard: True .ft P .fi .UNINDENT .UNINDENT .sp In this situation, the yum repo is going to be configured before other states, and if it fails to lay down the config file, than no other states will be executed. .SS Global Failhard .sp It may be desired to have failhard be applied to every state that is executed, if this is the case, then failhard can be set in the master configuration file. Setting failhard in the master configuration file will result in failing hard when any minion gathering states from the master have a state fail. .sp This is NOT the default behavior, normally Salt will only fail states that require a failed state. .sp Using the global failhard is generally not recommended, since it can result in states not being executed or even checked. It can also be confusing to see states failhard if an admin is not actively aware that the failhard has been set. .sp To use the global failhard set failhard: True in the master configuration file. .SS Global State Arguments .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 This documentation has been moved here\&. .UNINDENT .UNINDENT .SS Highstate data structure definitions .SS The Salt State Tree .sp A state tree is a collection of \fBSLS\fP files and directories that live under the directory specified in \fBfile_roots\fP\&. .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 Directory names or filenames in the state tree cannot contain a period, with the exception of the period in the .sls file suffix. .UNINDENT .UNINDENT .SS Top file .sp The main state file that instructs minions what environment and modules to use during state execution. .sp Configurable via \fBstate_top\fP\&. .sp \fBSEE ALSO:\fP .INDENT 0.0 .INDENT 3.5 A detailed description of the top file .UNINDENT .UNINDENT .SS Include declaration .sp Defines a list of \fI\%Module reference\fP strings to include in this \fBSLS\fP\&. .sp Occurs only in the top level of the SLS data structure. .sp Example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C include: \- edit.vim \- http.server .ft P .fi .UNINDENT .UNINDENT .SS Module reference .sp The name of a SLS module defined by a separate SLS file and residing on the Salt Master. A module named \fBedit.vim\fP is a reference to the SLS file \fBsalt://edit/vim.sls\fP\&. .SS ID declaration .sp Defines an individual highstate component. Always references a value of a dictionary containing keys referencing \fI\%State declaration\fP and \fI\%Requisite declaration\fP\&. Can be overridden by a \fI\%Name declaration\fP or a \fI\%Names declaration\fP\&. .sp Occurs on the top level or under the \fI\%Extend declaration\fP\&. .sp Must be unique across entire state tree. If the same ID declaration is used twice, only the first one matched will be used. All subsequent ID declarations with the same name will be ignored. .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 Naming gotchas .sp In Salt versions earlier than 0.9.7, ID declarations containing dots would result in unpredictable output. .UNINDENT .UNINDENT .SS Extend declaration .sp Extends a \fI\%Name declaration\fP from an included \fBSLS module\fP\&. The keys of the extend declaration always refer to an existing \fI\%ID declaration\fP which have been defined in included \fBSLS modules\fP\&. .sp Occurs only in the top level and defines a dictionary. .sp States cannot be extended more than once in a single state run. .sp Extend declarations are useful for adding\-to or overriding parts of a \fI\%State declaration\fP that is defined in another \fBSLS\fP file. In the following contrived example, the shown \fBmywebsite.sls\fP file is \fBinclude\fP \-ing and \fBextend\fP \-ing the \fBapache.sls\fP module in order to add a \fBwatch\fP declaration that will restart Apache whenever the Apache configuration file, \fBmywebsite\fP changes. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C include: \- apache extend: apache: service: \- watch: \- file: mywebsite mywebsite: file.managed: \- name: /var/www/mysite .ft P .fi .UNINDENT .UNINDENT .sp \fBSEE ALSO:\fP .INDENT 0.0 .INDENT 3.5 watch_in and require_in .sp Sometimes it is more convenient to use the watch_in or require_in syntax instead of extending another \fBSLS\fP file. .sp State Requisites .UNINDENT .UNINDENT .SS State declaration .sp A list which contains one string defining the \fI\%Function declaration\fP and any number of \fI\%Function arg declaration\fP dictionaries. .sp Can, optionally, contain a number of additional components like the name override components — \fI\%name\fP and \fI\%names\fP\&. Can also contain \fI\%requisite declarations\fP\&. .sp Occurs under an \fI\%ID declaration\fP\&. .SS Requisite declaration .sp A list containing \fI\%requisite references\fP\&. .sp Used to build the action dependency tree. While Salt states are made to execute in a deterministic order, this order is managed by requiring and watching other Salt states. .sp Occurs as a list component under a \fI\%State declaration\fP or as a key under an \fI\%ID declaration\fP\&. .SS Requisite reference .sp A single key dictionary. The key is the name of the referenced \fI\%State declaration\fP and the value is the ID of the referenced \fI\%ID declaration\fP\&. .sp Occurs as a single index in a \fI\%Requisite declaration\fP list. .SS Function declaration .sp The name of the function to call within the state. A state declaration can contain only a single function declaration. .sp For example, the following state declaration calls the \fBinstalled\fP function in the \fBpkg\fP state module: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C httpd: pkg.installed: [] .ft P .fi .UNINDENT .UNINDENT .sp The function can be declared inline with the state as a shortcut. The actual data structure is compiled to this form: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C httpd: pkg: \- installed .ft P .fi .UNINDENT .UNINDENT .sp Where the function is a string in the body of the state declaration. Technically when the function is declared in dot notation the compiler converts it to be a string in the state declaration list. Note that the use of the first example more than once in an ID declaration is invalid yaml. .sp INVALID: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C httpd: pkg.installed service.running .ft P .fi .UNINDENT .UNINDENT .sp When passing a function without arguments and another state declaration within a single ID declaration, then the long or "standard" format needs to be used since otherwise it does not represent a valid data structure. .sp VALID: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C httpd: pkg.installed: [] service.running: [] .ft P .fi .UNINDENT .UNINDENT .sp Occurs as the only index in the \fI\%State declaration\fP list. .SS Function arg declaration .sp A single key dictionary referencing a Python type which is to be passed to the named \fI\%Function declaration\fP as a parameter. The type must be the data type expected by the function. .sp Occurs under a \fI\%Function declaration\fP\&. .sp For example in the following state declaration \fBuser\fP, \fBgroup\fP, and \fBmode\fP are passed as arguments to the \fBmanaged\fP function in the \fBfile\fP state module: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C /etc/http/conf/http.conf: file.managed: \- user: root \- group: root \- mode: 644 .ft P .fi .UNINDENT .UNINDENT .SS Name declaration .sp Overrides the \fBname\fP argument of a \fI\%State declaration\fP\&. If \fBname\fP is not specified the \fI\%ID declaration\fP satisfies the \fBname\fP argument. .sp The name is always a single key dictionary referencing a string. .sp Overriding \fBname\fP is useful for a variety of scenarios. .sp For example, avoiding clashing ID declarations. The following two state declarations cannot both have \fB/etc/motd\fP as the ID declaration: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C motd_perms: file.managed: \- name: /etc/motd \- mode: 644 motd_quote: file.append: \- name: /etc/motd \- text: "Of all smells, bread; of all tastes, salt." .ft P .fi .UNINDENT .UNINDENT .sp Another common reason to override \fBname\fP is if the ID declaration is long and needs to be referenced in multiple places. In the example below it is much easier to specify \fBmywebsite\fP than to specify \fB/etc/apache2/sites\-available/mywebsite.com\fP multiple times: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C mywebsite: file.managed: \- name: /etc/apache2/sites\-available/mywebsite.com \- source: salt://mywebsite.com a2ensite mywebsite.com: cmd.wait: \- unless: test \-L /etc/apache2/sites\-enabled/mywebsite.com \- watch: \- file: mywebsite apache2: service.running: \- watch: \- file: mywebsite .ft P .fi .UNINDENT .UNINDENT .SS Names declaration .sp Expands the contents of the containing \fI\%State declaration\fP into multiple state declarations, each with its own name. .sp For example, given the following state declaration: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C python\-pkgs: pkg.installed: \- names: \- python\-django \- python\-crypto \- python\-yaml .ft P .fi .UNINDENT .UNINDENT .sp Once converted into the lowstate data structure the above state declaration will be expanded into the following three state declarations: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C python\-django: pkg.installed python\-crypto: pkg.installed python\-yaml: pkg.installed .ft P .fi .UNINDENT .UNINDENT .sp Other values can be overridden during the expansion by providing an additional dictionary level. .sp New in version 2014.7.0. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C ius: pkgrepo.managed: \- humanname: IUS Community Packages for Enterprise Linux 6 \- $basearch \- gpgcheck: 1 \- baseurl: http://mirror.rackspace.com/ius/stable/CentOS/6/$basearch \- gpgkey: http://dl.iuscommunity.org/pub/ius/IUS\-COMMUNITY\-GPG\-KEY \- names: \- ius \- ius\-devel: \- baseurl: http://mirror.rackspace.com/ius/development/CentOS/6/$basearch .ft P .fi .UNINDENT .UNINDENT .SS Large example .sp Here is the layout in yaml using the names of the highdata structure components. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C : \- \- : : [] # standard declaration : : \- \- \- \- \- : \- : \- \- # inline function and names : .: \- \- \- \- : \- \- \- \- : \- \- # multiple states for single id : : \- \- \- : \- : \- : \- \- \- : \- \- \- : \- .ft P .fi .UNINDENT .UNINDENT .SS Include and Exclude .sp Salt SLS files can include other SLS files and exclude SLS files that have been otherwise included. This allows for an SLS file to easily extend or manipulate other SLS files. .SS Include .sp When other SLS files are included, everything defined in the included SLS file will be added to the state run. When including define a list of SLS formulas to include: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C include: \- http \- libvirt .ft P .fi .UNINDENT .UNINDENT .sp The include statement will include SLS formulas from the same environment that the including SLS formula is in. But the environment can be explicitly defined in the configuration to override the running environment, therefore if an SLS formula needs to be included from an external environment named "dev" the following syntax is used: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C include: \- dev: http .ft P .fi .UNINDENT .UNINDENT .sp \fBNOTE\fP: \fBinclude\fP does not simply inject the states where you place it in the SLS file. If you need to guarantee order of execution, consider using requisites. .INDENT 0.0 .INDENT 3.5 .IP "Do not use dots in SLS file names or their directories" .sp The initial implementation of \fBtop.sls\fP and include\-declaration followed the python import model where a slash is represented as a period. This means that a SLS file with a period in the name ( besides the suffix period) can not be referenced. For example, webserver_1.0.sls is not referenceable because webserver_1.0 would refer to the directory/file webserver_1/0.sls .sp The same applies for any subdirectories, this is especially \(aqtricky\(aq when git repos are created. Another command that typically can\(aqt render it\(aqs output is \fB\(gastate.show_sls\(ga\fP of a file in a path that contains a dot. .UNINDENT .UNINDENT .SS Relative Include .sp In Salt 0.16.0, the capability to include SLS formulas which are relative to the running SLS formula was added. Simply precede the formula name with a \fB\&.\fP: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C include: \- .virt \- .virt.hyper .ft P .fi .UNINDENT .UNINDENT .sp In Salt 2015.8, the ability to include SLS formulas which are relative to the parents of the running SLS formula was added. In order to achieve this, precede the formula name with more than one \fB\&.\fP (dot). Much like Python\(aqs relative import abilities, two or more leading dots represent a relative include of the parent or parents of the current package, with each \fB\&.\fP representing one level after the first. .sp The following SLS configuration, if placed within \fBexample.dev.virtual\fP, would result in \fBexample.http\fP and \fBbase\fP being included respectively: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C include: \- ..http \- ...base .ft P .fi .UNINDENT .UNINDENT .SS Exclude .sp The exclude statement, added in Salt 0.10.3, allows an SLS to hard exclude another SLS file or a specific id. The component is excluded after the high data has been compiled, so nothing should be able to override an exclude. .sp Since the exclude can remove an id or an sls the type of component to exclude needs to be defined. An exclude statement that verifies that the running highstate does not contain the \fBhttp\fP sls and the \fB/etc/vimrc\fP id would look like this: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C exclude: \- sls: http \- id: /etc/vimrc .ft P .fi .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 The current state processing flow checks for duplicate IDs before processing excludes. An error occurs if duplicate IDs are present even if one of the IDs is targeted by an \fBexclude\fP\&. .UNINDENT .UNINDENT .SS State System Layers .sp The Salt state system is comprised of multiple layers. While using Salt does not require an understanding of the state layers, a deeper understanding of how Salt compiles and manages states can be very beneficial. .SS Function Call .sp The lowest layer of functionality in the state system is the direct state function call. State executions are executions of single state functions at the core. These individual functions are defined in state modules and can be called directly via the \fBstate.single\fP command. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq state.single pkg.installed name=\(aqvim\(aq .ft P .fi .UNINDENT .UNINDENT .SS Low Chunk .sp The low chunk is the bottom of the Salt state compiler. This is a data representation of a single function call. The low chunk is sent to the state caller and used to execute a single state function. .sp A single low chunk can be executed manually via the \fBstate.low\fP command. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq state.low \(aq{name: vim, state: pkg, fun: installed}\(aq .ft P .fi .UNINDENT .UNINDENT .sp The passed data reflects what the state execution system gets after compiling the data down from sls formulas. .SS Low State .sp The \fILow State\fP layer is the list of low chunks "evaluated" in order. To see what the low state looks like for a highstate, run: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq state.show_lowstate .ft P .fi .UNINDENT .UNINDENT .sp This will display the raw lowstate in the order which each low chunk will be evaluated. The order of evaluation is not necessarily the order of execution, since requisites are evaluated at runtime. Requisite execution and evaluation is finite; this means that the order of execution can be ascertained with 100% certainty based on the order of the low state. .SS High Data .sp High data is the data structure represented in YAML via SLS files. The High data structure is created by merging the data components rendered inside sls files (or other render systems). The High data can be easily viewed by executing the \fBstate.show_highstate\fP or \fBstate.show_sls\fP functions. Since this data is a somewhat complex data structure, it may be easier to read using the json, yaml, or pprint outputters: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq state.show_highstate \-\-out yaml salt \(aq*\(aq state.show_sls edit.vim \-\-out pprint .ft P .fi .UNINDENT .UNINDENT .SS SLS .sp Above "High Data", the logical layers are no longer technically required to be executed, or to be executed in a hierarchy. This means that how the High data is generated is optional and very flexible. The SLS layer allows for many mechanisms to be used to render sls data from files or to use the fileserver backend to generate sls and file data from external systems. .sp The SLS layer can be called directly to execute individual sls formulas. .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 SLS Formulas have historically been called "SLS files". This is because a single SLS was only constituted in a single file. Now the term "SLS Formula" better expresses how a compartmentalized SLS can be expressed in a much more dynamic way by combining pillar and other sources, and the SLS can be dynamically generated. .UNINDENT .UNINDENT .sp To call a single SLS formula named \fBedit.vim\fP, execute \fBstate.apply\fP and pass \fBedit.vim\fP as an argument: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq state.apply edit.vim .ft P .fi .UNINDENT .UNINDENT .SS HighState .sp Calling SLS directly logically assigns what states should be executed from the context of the calling minion. The Highstate layer is used to allow for full contextual assignment of what is executed where to be tied to groups of, or individual, minions entirely from the master. This means that the environment of a minion, and all associated execution data pertinent to said minion, can be assigned from the master without needing to execute or configure anything on the target minion. This also means that the minion can independently retrieve information about its complete configuration from the master. .sp To execute the highstate use \fBstate.apply\fP: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq state.apply .ft P .fi .UNINDENT .UNINDENT .SS Orchestrate .sp The orchestrate layer expresses the highest functional layer of Salt\(aqs automated logic systems. The Overstate allows for stateful and functional orchestration of routines from the master. The orchestrate defines in data execution stages which minions should execute states, or functions, and in what order using requisite logic. .SS The Orchestrate Runner .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 This documentation has been moved here\&. .UNINDENT .UNINDENT .SS Ordering States .sp The way in which configuration management systems are executed is a hotly debated topic in the configuration management world. Two major philosophies exist on the subject, to either execute in an imperative fashion where things are executed in the order in which they are defined, or in a declarative fashion where dependencies need to be mapped between objects. .sp Imperative ordering is finite and generally considered easier to write, but declarative ordering is much more powerful and flexible but generally considered more difficult to create. .sp Salt has been created to get the best of both worlds. States are evaluated in a finite order, which guarantees that states are always executed in the same order, and the states runtime is declarative, making Salt fully aware of dependencies via the \fIrequisite\fP system. .SS State Auto Ordering .sp Salt always executes states in a finite manner, meaning that they will always execute in the same order regardless of the system that is executing them. But in Salt 0.17.0, the \fBstate_auto_order\fP option was added. This option makes states get evaluated in the order in which they are defined in sls files, including the top.sls file. .sp The evaluation order makes it easy to know what order the states will be executed in, but it is important to note that the requisite system will override the ordering defined in the files, and the \fBorder\fP option described below will also override the order in which states are defined in sls files. .sp If the classic ordering is preferred (lexicographic), then set \fBstate_auto_order\fP to \fBFalse\fP in the master configuration file. Otherwise, \fBstate_auto_order\fP defaults to \fBTrue\fP\&. .SS Requisite Statements .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 The behavior of requisites changed in version 0.9.7 of Salt. This documentation applies to requisites in version 0.9.7 and later. .UNINDENT .UNINDENT .sp Often when setting up states any single action will require or depend on another action. Salt allows for the building of relationships between states with requisite statements. A requisite statement ensures that the named state is evaluated before the state requiring it. There are three types of requisite statements in Salt, \fBrequire\fP, \fBwatch\fP, and \fBprereq\fP\&. .sp These requisite statements are applied to a specific state declaration: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C httpd: pkg.installed: [] file.managed: \- name: /etc/httpd/conf/httpd.conf \- source: salt://httpd/httpd.conf \- require: \- pkg: httpd .ft P .fi .UNINDENT .UNINDENT .sp In this example, the \fBrequire\fP requisite is used to declare that the file /etc/httpd/conf/httpd.conf should only be set up if the pkg state executes successfully. .sp The requisite system works by finding the states that are required and executing them before the state that requires them. Then the required states can be evaluated to see if they have executed correctly. .sp Require statements can refer to any state defined in Salt. The basic examples are \fIpkg\fP, \fIservice\fP, and \fIfile\fP, but any used state can be referenced. .sp In addition to state declarations such as pkg, file, etc., \fBsls\fP type requisites are also recognized, and essentially allow \(aqchaining\(aq of states. This provides a mechanism to ensure the proper sequence for complex state formulas, especially when the discrete states are split or groups into separate sls files: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C include: \- network httpd: pkg.installed: [] service.running: \- require: \- pkg: httpd \- sls: network .ft P .fi .UNINDENT .UNINDENT .sp In this example, the httpd service running state will not be applied (i.e., the httpd service will not be started) unless both the httpd package is installed AND the network state is satisfied. .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 Requisite matching .sp Requisites match on both the ID Declaration and the \fBname\fP parameter. Therefore, if using the \fBpkgs\fP or \fBsources\fP argument to install a list of packages in a pkg state, it\(aqs important to note that it is impossible to match an individual package in the list, since all packages are installed as a single state. .UNINDENT .UNINDENT .SS Multiple Requisites .sp The requisite statement is passed as a list, allowing for the easy addition of more requisites. Both requisite types can also be separately declared: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C httpd: pkg.installed: [] service.running: \- enable: True \- watch: \- file: /etc/httpd/conf/httpd.conf \- require: \- pkg: httpd \- user: httpd \- group: httpd file.managed: \- name: /etc/httpd/conf/httpd.conf \- source: salt://httpd/httpd.conf \- require: \- pkg: httpd user.present: [] group.present: [] .ft P .fi .UNINDENT .UNINDENT .sp In this example, the httpd service is only going to be started if the package, user, group, and file are executed successfully. .SS Requisite Documentation .sp For detailed information on each of the individual requisites, please look here. .SS The Order Option .sp Before using the \fIorder\fP option, remember that the majority of state ordering should be done with a requisite\-declaration, and that a requisite declaration will override an \fIorder\fP option, so a state with order option should not require or required by other states. .sp The order option is used by adding an order number to a state declaration with the option \fIorder\fP: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C vim: pkg.installed: \- order: 1 .ft P .fi .UNINDENT .UNINDENT .sp By adding the order option to \fI1\fP this ensures that the vim package will be installed in tandem with any other state declaration set to the order \fI1\fP\&. .sp Any state declared without an order option will be executed after all states with order options are executed. .sp But this construct can only handle ordering states from the beginning. Certain circumstances will present a situation where it is desirable to send a state to the end of the line. To do this, set the order to \fBlast\fP: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C vim: pkg.installed: \- order: last .ft P .fi .UNINDENT .UNINDENT .SS State Providers .sp New in version 0.9.8. .sp Salt predetermines what modules should be mapped to what uses based on the properties of a system. These determinations are generally made for modules that provide things like package and service management. .sp Sometimes in states, it may be necessary to use an alternative module to provide the needed functionality. For instance, an very old Arch Linux system may not be running systemd, so instead of using the systemd service module, you can revert to the default service module: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C httpd: service.running: \- enable: True \- provider: service .ft P .fi .UNINDENT .UNINDENT .sp In this instance, the basic \fBservice\fP module (which manages \fBsysvinit\fP\-based services) will replace the \fBsystemd\fP module which is used by default on Arch Linux. .sp This change only affects this one state though. If it is necessary to make this override for most or every service, it is better to just override the provider in the minion config file, as described here\&. .sp Also, keep in mind that this only works for states with an identically\-named virtual module (\fBpkg\fP, \fBservice\fP, etc.). .SS Arbitrary Module Redirects .sp The provider statement can also be used for more powerful means, instead of overwriting or extending the module used for the named service an arbitrary module can be used to provide certain functionality. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C emacs: pkg.installed: \- provider: \- cmd: customcmd .ft P .fi .UNINDENT .UNINDENT .sp In this example, the state is being instructed to use a custom module to invoke commands. .sp Arbitrary module redirects can be used to dramatically change the behavior of a given state. .SS Requisites and Other Global State Arguments .SS Requisites .sp The Salt requisite system is used to create relationships between states. The core idea being that, when one state is dependent somehow on another, that inter\-dependency can be easily defined. These dependencies are expressed by declaring the relationships using state names and ID\(aqs or names. The generalized form of a requisite target is \fB : \fP\&. The specific form is defined as a Requisite Reference .sp Requisites come in two types: Direct requisites (such as \fBrequire\fP), and requisite_ins (such as \fBrequire_in\fP). The relationships are directional: a direct requisite requires something from another state. However, a requisite_in inserts a requisite into the targeted state pointing to the targeting state. The following example demonstrates a direct requisite: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C vim: pkg.installed: [] /etc/vimrc: file.managed: \- source: salt://edit/vimrc \- require: \- pkg: vim .ft P .fi .UNINDENT .UNINDENT .sp In the example above, the file \fB/etc/vimrc\fP depends on the vim package. .sp Requisite_in statements are the opposite. Instead of saying "I depend on something", requisite_ins say "Someone depends on me": .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C vim: pkg.installed: \- require_in: \- file: /etc/vimrc /etc/vimrc: file.managed: \- source: salt://edit/vimrc .ft P .fi .UNINDENT .UNINDENT .sp So here, with a requisite_in, the same thing is accomplished as in the first example, but the other way around. The vim package is saying "/etc/vimrc depends on me". This will result in a \fBrequire\fP being inserted into the \fB/etc/vimrc\fP state which targets the \fBvim\fP state. .sp In the end, a single dependency map is created and everything is executed in a finite and predictable order. .SS Requisite matching .sp Requisites need two pieces of information for matching: The state module name – e.g. \fBpkg\fP –, and the identifier – e.g. vim –, which can be either the ID (the first line in the stanza) or the \fB\- name\fP parameter. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C \- require: \- pkg: vim .ft P .fi .UNINDENT .UNINDENT .SS Omitting state module in requisites .sp New in version 2016.3.0. .sp In version 2016.3.0, the state module name was made optional. If the state module is omitted, all states matching the ID will be required, regardless of which module they are using. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C \- require: \- vim .ft P .fi .UNINDENT .UNINDENT .SS State target matching .sp In order to understand how state targets are matched, it is helpful to know how the state compiler is working\&. Consider the following example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C Deploy server package: file.managed: \- name: /usr/local/share/myapp.tar.xz \- source: salt://myapp.tar.xz Extract server package: archive.extracted: \- name: /usr/local/share/myapp \- source: /usr/local/share/myapp.tar.xz \- archive_format: tar \- onchanges: \- file: Deploy server package .ft P .fi .UNINDENT .UNINDENT .sp The first formula is converted to a dictionary which looks as follows (represented as YAML, some properties omitted for simplicity) as \fIHigh Data\fP: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C Deploy server package: file: \- managed \- name: /usr/local/share/myapp.tar.xz \- source: salt://myapp.tar.xz .ft P .fi .UNINDENT .UNINDENT .sp The \fBfile.managed\fP format used in the formula is essentially syntactic sugar: at the end, the target is \fBfile\fP, which is used in the \fBExtract server package\fP state above. .SS Identifier matching .sp Requisites match on both the ID Declaration and the \fBname\fP parameter. This means that, in the "Deploy server package" example above, a \fBrequire\fP requisite would match with with \fBDeploy server package\fP \fIor\fP \fB/usr/local/share/myapp.tar.xz\fP, so either of the following versions for "Extract server package" works: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C # (Archive arguments omitted for simplicity) # Match by ID declaration Extract server package: archive.extracted: \- onchanges: \- file: Deploy server package # Match by name parameter Extract server package: archive.extracted: \- onchanges: \- file: /usr/local/share/myapp.tar.xz .ft P .fi .UNINDENT .UNINDENT .SS Direct Requisite and Requisite_in types .sp There are several direct requisite statements that can be used in Salt: .INDENT 0.0 .IP \(bu 2 \fBrequire\fP .IP \(bu 2 \fBwatch\fP .IP \(bu 2 \fBprereq\fP .IP \(bu 2 \fBuse\fP .IP \(bu 2 \fBonchanges\fP .IP \(bu 2 \fBonfail\fP .UNINDENT .sp Each direct requisite also has a corresponding requisite_in: .INDENT 0.0 .IP \(bu 2 \fBrequire_in\fP .IP \(bu 2 \fBwatch_in\fP .IP \(bu 2 \fBprereq_in\fP .IP \(bu 2 \fBuse_in\fP .IP \(bu 2 \fBonchanges_in\fP .IP \(bu 2 \fBonfail_in\fP .UNINDENT .sp All of the requisites define specific relationships and always work with the dependency logic defined above. .SS require .sp The use of \fBrequire\fP demands that the required state executes before the dependent state. The state containing the \fBrequire\fP requisite is defined as the dependent state. The state specified in the \fBrequire\fP statement is defined as the required state. If the required state\(aqs execution succeeds, the dependent state will then execute. If the required state\(aqs execution fails, the dependent state will not execute. In the first example above, the file \fB/etc/vimrc\fP will only execute after the vim package is installed successfully. .SS Require an Entire SLS File .sp As of Salt 0.16.0, it is possible to require an entire sls file. Do this first by including the sls file and then setting a state to \fBrequire\fP the included sls file: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C include: \- foo bar: pkg.installed: \- require: \- sls: foo .ft P .fi .UNINDENT .UNINDENT .sp This will add all of the state declarations found in the given sls file. This means that every state in sls \fIfoo\fP will be required. This makes it very easy to batch large groups of states easily in any requisite statement. .SS watch .sp \fBwatch\fP statements are used to add additional behavior when there are changes in other states. .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 If a state should only execute when another state has changes, and otherwise do nothing, the new \fBonchanges\fP requisite should be used instead of \fBwatch\fP\&. \fBwatch\fP is designed to add \fIadditional\fP behavior when there are changes, but otherwise the state executes normally. .UNINDENT .UNINDENT .sp The state containing the \fBwatch\fP requisite is defined as the watching state. The state specified in the \fBwatch\fP statement is defined as the watched state. When the watched state executes, it will return a dictionary containing a key named "changes". Here are two examples of state return dictionaries, shown in json for clarity: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C { "local": { "file_|\-/tmp/foo_|\-/tmp/foo_|\-directory": { "comment": "Directory /tmp/foo updated", "__run_num__": 0, "changes": { "user": "bar" }, "name": "/tmp/foo", "result": true } } } { "local": { "pkgrepo_|\-salt\-minion_|\-salt\-minion_|\-managed": { "comment": "Package repo \(aqsalt\-minion\(aq already configured", "__run_num__": 0, "changes": {}, "name": "salt\-minion", "result": true } } } .ft P .fi .UNINDENT .UNINDENT .sp If the "result" of the watched state is \fBTrue\fP, the watching state \fIwill execute normally\fP, and if it is \fBFalse\fP, the watching state will never run. This part of \fBwatch\fP mirrors the functionality of the \fBrequire\fP requisite. .sp If the "result" of the watched state is \fBTrue\fP \fIand\fP the "changes" key contains a populated dictionary (changes occurred in the watched state), then the \fBwatch\fP requisite can add additional behavior. This additional behavior is defined by the \fBmod_watch\fP function within the watching state module. If the \fBmod_watch\fP function exists in the watching state module, it will be called \fIin addition to\fP the normal watching state. The return data from the \fBmod_watch\fP function is what will be returned to the master in this case; the return data from the main watching function is discarded. .sp If the "changes" key contains an empty dictionary, the \fBwatch\fP requisite acts exactly like the \fBrequire\fP requisite (the watching state will execute if "result" is \fBTrue\fP, and fail if "result" is \fBFalse\fP in the watched state). .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 Not all state modules contain \fBmod_watch\fP\&. If \fBmod_watch\fP is absent from the watching state module, the \fBwatch\fP requisite behaves exactly like a \fBrequire\fP requisite. .UNINDENT .UNINDENT .sp A good example of using \fBwatch\fP is with a \fBservice.running\fP state. When a service watches a state, then the service is reloaded/restarted when the watched state changes, in addition to Salt ensuring that the service is running. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C ntpd: service.running: \- watch: \- file: /etc/ntp.conf file.managed: \- name: /etc/ntp.conf \- source: salt://ntp/files/ntp.conf .ft P .fi .UNINDENT .UNINDENT .SS prereq .sp New in version 0.16.0. .sp \fBprereq\fP allows for actions to be taken based on the expected results of a state that has not yet been executed. The state containing the \fBprereq\fP requisite is defined as the pre\-requiring state. The state specified in the \fBprereq\fP statement is defined as the pre\-required state. .sp When a \fBprereq\fP requisite is evaluated, the pre\-required state reports if it expects to have any changes. It does this by running the pre\-required single state as a test\-run by enabling \fBtest=True\fP\&. This test\-run will return a dictionary containing a key named "changes". (See the \fBwatch\fP section above for examples of "changes" dictionaries.) .sp If the "changes" key contains a populated dictionary, it means that the pre\-required state expects changes to occur when the state is actually executed, as opposed to the test\-run. The pre\-requiring state will now actually run. If the pre\-requiring state executes successfully, the pre\-required state will then execute. If the pre\-requiring state fails, the pre\-required state will not execute. .sp If the "changes" key contains an empty dictionary, this means that changes are not expected by the pre\-required state. Neither the pre\-required state nor the pre\-requiring state will run. .sp The best way to define how \fBprereq\fP operates is displayed in the following practical example: When a service should be shut down because underlying code is going to change, the service should be off\-line while the update occurs. In this example, \fBgraceful\-down\fP is the pre\-requiring state and \fBsite\-code\fP is the pre\-required state. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C graceful\-down: cmd.run: \- name: service apache graceful \- prereq: \- file: site\-code site\-code: file.recurse: \- name: /opt/site_code \- source: salt://site/code .ft P .fi .UNINDENT .UNINDENT .sp In this case the apache server will only be shutdown if the site\-code state expects to deploy fresh code via the file.recurse call. The site\-code deployment will only be executed if the graceful\-down run completes successfully. .SS onfail .sp New in version 2014.7.0. .sp The \fBonfail\fP requisite allows for reactions to happen strictly as a response to the failure of another state. This can be used in a number of ways, such as executing a second attempt to set up a service or begin to execute a separate thread of states because of a failure. .sp The \fBonfail\fP requisite is applied in the same way as \fBrequire\fP as \fBwatch\fP: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C primary_mount: mount.mounted: \- name: /mnt/share \- device: 10.0.0.45:/share \- fstype: nfs backup_mount: mount.mounted: \- name: /mnt/share \- device: 192.168.40.34:/share \- fstype: nfs \- onfail: \- mount: primary_mount .ft P .fi .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 Beginning in the \fB2016.11.0\fP release of Salt, \fBonfail\fP uses OR logic for multiple listed \fBonfail\fP requisites. Prior to the \fB2016.11.0\fP release, \fBonfail\fP used AND logic. See \fI\%Issue #22370\fP for more information. .UNINDENT .UNINDENT .SS onchanges .sp New in version 2014.7.0. .sp The \fBonchanges\fP requisite makes a state only apply if the required states generate changes, and if the watched state\(aqs "result" is \fBTrue\fP\&. This can be a useful way to execute a post hook after changing aspects of a system. .sp If a state has multiple \fBonchanges\fP requisites then the state will trigger if any of the watched states changes. .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 One easy\-to\-make mistake is to use \fBonchanges_in\fP when \fBonchanges\fP is supposed to be used. For example, the below configuration is not correct: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C myservice: pkg.installed: \- name: myservice file.managed: \- name: /etc/myservice/myservice.conf \- source: salt://myservice/files/myservice.conf \- mode: 600 cmd.run: \- name: /usr/libexec/myservice/post\-changes\-hook.sh \- onchanges_in: \- file: /etc/myservice/myservice.conf .ft P .fi .UNINDENT .UNINDENT .sp This will set up a requisite relationship in which the \fBcmd.run\fP state always executes, and the \fBfile.managed\fP state only executes if the \fBcmd.run\fP state has changes (which it always will, since the \fBcmd.run\fP state includes the command results as changes). .sp It may semantically seem like the the \fBcmd.run\fP state should only run when there are changes in the file state, but remember that requisite relationships involve one state watching another state, and a \fI\%requisite_in\fP does the opposite: it forces the specified state to watch the state with the \fBrequisite_in\fP\&. .sp The correct usage would be: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C myservice: pkg.installed: \- name: myservice file.managed: \- name: /etc/myservice/myservice.conf \- source: salt://myservice/files/myservice.conf \- mode: 600 cmd.run: \- name: /usr/libexec/myservice/post\-changes\-hook.sh \- onchanges: \- file: /etc/myservice/myservice.conf .ft P .fi .UNINDENT .UNINDENT .UNINDENT .UNINDENT .SS use .sp The \fBuse\fP requisite is used to inherit the arguments passed in another id declaration. This is useful when many files need to have the same defaults. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C /etc/foo.conf: file.managed: \- source: salt://foo.conf \- template: jinja \- mkdirs: True \- user: apache \- group: apache \- mode: 755 /etc/bar.conf file.managed: \- source: salt://bar.conf \- use: \- file: /etc/foo.conf .ft P .fi .UNINDENT .UNINDENT .sp The \fBuse\fP statement was developed primarily for the networking states but can be used on any states in Salt. This makes sense for the networking state because it can define a long list of options that need to be applied to multiple network interfaces. .sp The \fBuse\fP statement does not inherit the requisites arguments of the targeted state. This means also a chain of \fBuse\fP requisites would not inherit inherited options. .SS The _in versions of requisites .sp All of the requisites also have corresponding requisite_in versions, which do the reverse of their normal counterparts. The examples below all use \fBrequire_in\fP as the example, but note that all of the \fB_in\fP requisites work the same way: They result in a normal requisite in the targeted state, which targets the state which has defines the requisite_in. Thus, a \fBrequire_in\fP causes the target state to \fBrequire\fP the targeting state. Similarly, a \fBwatch_in\fP causes the target state to \fBwatch\fP the targeting state. This pattern continues for the rest of the requisites. .sp If a state declaration needs to be required by another state declaration then \fBrequire_in\fP can accommodate it. Therefore, these two sls files would be the same in the end: .sp Using \fBrequire\fP .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C httpd: pkg.installed: [] service.running: \- require: \- pkg: httpd .ft P .fi .UNINDENT .UNINDENT .sp Using \fBrequire_in\fP .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C httpd: pkg.installed: \- require_in: \- service: httpd service.running: [] .ft P .fi .UNINDENT .UNINDENT .sp The \fBrequire_in\fP statement is particularly useful when assigning a require in a separate sls file. For instance it may be common for httpd to require components used to set up PHP or mod_python, but the HTTP state does not need to be aware of the additional components that require it when it is set up: .sp http.sls .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C httpd: pkg.installed: [] service.running: \- require: \- pkg: httpd .ft P .fi .UNINDENT .UNINDENT .sp php.sls .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C include: \- http php: pkg.installed: \- require_in: \- service: httpd .ft P .fi .UNINDENT .UNINDENT .sp mod_python.sls .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C include: \- http mod_python: pkg.installed: \- require_in: \- service: httpd .ft P .fi .UNINDENT .UNINDENT .sp Now the httpd server will only start if php or mod_python are first verified to be installed. Thus allowing for a requisite to be defined "after the fact". .SS Fire Event Notifications .sp New in version 2015.8.0. .sp The \fIfire_event\fP option in a state will cause the minion to send an event to the Salt Master upon completion of that individual state. .sp The following example will cause the minion to send an event to the Salt Master with a tag of \fIsalt/state_result/20150505121517276431/dasalt/nano\fP and the result of the state will be the data field of the event. Notice that the \fIname\fP of the state gets added to the tag. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C nano_stuff: pkg.installed: \- name: nano \- fire_event: True .ft P .fi .UNINDENT .UNINDENT .sp In the following example instead of setting \fIfire_event\fP to \fITrue\fP, \fIfire_event\fP is set to an arbitrary string, which will cause the event to be sent with this tag: \fIsalt/state_result/20150505121725642845/dasalt/custom/tag/nano/finished\fP .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C nano_stuff: pkg.installed: \- name: nano \- fire_event: custom/tag/nano/finished .ft P .fi .UNINDENT .UNINDENT .SS Altering States .sp The state altering system is used to make sure that states are evaluated exactly as the user expects. It can be used to double check that a state preformed exactly how it was expected to, or to make 100% sure that a state only runs under certain conditions. The use of unless or onlyif options help make states even more stateful. The \fBcheck_cmd\fP option helps ensure that the result of a state is evaluated correctly. .SS Reload .sp \fBreload_modules\fP is a boolean option that forces salt to reload its modules after a state finishes. \fBreload_pillar\fP and \fBreload_grains\fP can also be set. See Reloading Modules\&. .SS Unless .sp New in version 2014.7.0. .sp The \fBunless\fP requisite specifies that a state should only run when any of the specified commands return \fBFalse\fP\&. The \fBunless\fP requisite operates as NAND and is useful in giving more granular control over when a state should execute. .sp \fBNOTE\fP: Under the hood \fBunless\fP calls \fBcmd.retcode\fP with \fBpython_shell=True\fP\&. This means the commands referenced by \fBunless\fP will be parsed by a shell, so beware of side\-effects as this shell will be run with the same privileges as the salt\-minion. Also be aware that the boolean value is determined by the shell\(aqs concept of \fBTrue\fP and \fBFalse\fP, rather than Python\(aqs concept of \fBTrue\fP and \fBFalse\fP\&. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C vim: pkg.installed: \- unless: \- rpm \-q vim\-enhanced \- ls /usr/bin/vim .ft P .fi .UNINDENT .UNINDENT .sp In the example above, the state will only run if either the vim\-enhanced package is not installed (returns \fBFalse\fP) or if /usr/bin/vim does not exist (returns \fBFalse\fP). The state will run if both commands return \fBFalse\fP\&. .sp However, the state will not run if both commands return \fBTrue\fP\&. .sp Unless checks are resolved for each name to which they are associated. .sp For example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C deploy_app: cmd.run: \- names: \- first_deploy_cmd \- second_deploy_cmd \- unless: ls /usr/bin/vim .ft P .fi .UNINDENT .UNINDENT .sp In the above case, \fBsome_check\fP will be run prior to _each_ name \-\- once for \fBfirst_deploy_cmd\fP and a second time for \fBsecond_deploy_cmd\fP\&. .SS Onlyif .sp New in version 2014.7.0. .sp The \fBonlyif\fP requisite specifies that if each command listed in \fBonlyif\fP returns \fBTrue\fP, then the state is run. If any of the specified commands return \fBFalse\fP, the state will not run. .sp \fBNOTE\fP: Under the hood \fBonlyif\fP calls \fBcmd.retcode\fP with \fBpython_shell=True\fP\&. This means the commands referenced by \fBonlyif\fP will be parsed by a shell, so beware of side\-effects as this shell will be run with the same privileges as the salt\-minion. Also be aware that the boolean value is determined by the shell\(aqs concept of \fBTrue\fP and \fBFalse\fP, rather than Python\(aqs concept of \fBTrue\fP and \fBFalse\fP\&. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C stop\-volume: module.run: \- name: glusterfs.stop_volume \- m_name: work \- onlyif: \- gluster volume status work \- order: 1 remove\-volume: module.run: \- name: glusterfs.delete \- m_name: work \- onlyif: \- gluster volume info work \- watch: \- cmd: stop\-volume .ft P .fi .UNINDENT .UNINDENT .sp The above example ensures that the stop_volume and delete modules only run if the gluster commands return a 0 ret value. .SS Listen/Listen_in .sp New in version 2014.7.0. .sp listen and its counterpart listen_in trigger mod_wait functions for states, when those states succeed and result in changes, similar to how watch its counterpart watch_in. Unlike watch and watch_in, listen, and listen_in will not modify the order of states and can be used to ensure your states are executed in the order they are defined. All listen/listen_in actions will occur at the end of a state run, after all states have completed. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C restart\-apache2: service.running: \- name: apache2 \- listen: \- file: /etc/apache2/apache2.conf configure\-apache2: file.managed: \- name: /etc/apache2/apache2.conf \- source: salt://apache2/apache2.conf .ft P .fi .UNINDENT .UNINDENT .sp This example will cause apache2 to be restarted when the apache2.conf file is changed, but the apache2 restart will happen at the end of the state run. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C restart\-apache2: service.running: \- name: apache2 configure\-apache2: file.managed: \- name: /etc/apache2/apache2.conf \- source: salt://apache2/apache2.conf \- listen_in: \- service: apache2 .ft P .fi .UNINDENT .UNINDENT .sp This example does the same as the above example, but puts the state argument on the file resource, rather than the service resource. .SS check_cmd .sp New in version 2014.7.0. .sp Check Command is used for determining that a state did or did not run as expected. .sp \fBNOTE\fP: Under the hood \fBcheck_cmd\fP calls \fBcmd.retcode\fP with \fBpython_shell=True\fP\&. This means the commands referenced by unless will be parsed by a shell, so beware of side\-effects as this shell will be run with the same privileges as the salt\-minion. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C comment\-repo: file.replace: \- name: /etc/yum.repos.d/fedora.repo \- pattern: ^enabled=0 \- repl: enabled=1 \- check_cmd: \- ! grep \(aqenabled=0\(aq /etc/yum.repos.d/fedora.repo .ft P .fi .UNINDENT .UNINDENT .sp This will attempt to do a replace on all \fBenabled=0\fP in the .repo file, and replace them with \fBenabled=1\fP\&. The \fBcheck_cmd\fP is just a bash command. It will do a grep for \fBenabled=0\fP in the file, and if it finds any, it will return a 0, which will be inverted by the leading \fB!\fP, causing \fBcheck_cmd\fP to set the state as failed. If it returns a 1, meaning it didn\(aqt find any \fBenabled=0\fP, it will be inverted by the leading \fB!\fP, returning a 0, and declaring the function succeeded. .sp \fBNOTE\fP: This requisite \fBcheck_cmd\fP functions differently than the \fBcheck_cmd\fP of the \fBfile.managed\fP state. .SS Overriding Checks .sp There are two commands used for the above checks. .sp \fBmod_run_check\fP is used to check for \fBonlyif\fP and \fBunless\fP\&. If the goal is to override the global check for these to variables, include a \fBmod_run_check\fP in the salt/states/ file. .sp \fBmod_run_check_cmd\fP is used to check for the check_cmd options. To override this one, include a \fBmod_run_check_cmd\fP in the states file for the state. .SS Startup States .sp Sometimes it may be desired that the salt minion execute a state run when it is started. This alleviates the need for the master to initiate a state run on a new minion and can make provisioning much easier. .sp As of Salt 0.10.3 the minion config reads options that allow for states to be executed at startup. The options are \fIstartup_states\fP, \fIsls_list\fP, and \fItop_file\fP\&. .sp The \fIstartup_states\fP option can be passed one of a number of arguments to define how to execute states. The available options are: .INDENT 0.0 .TP .B highstate Execute \fBstate.apply\fP .TP .B sls Read in the \fBsls_list\fP option and execute the named sls files .TP .B top Read in the \fBtop_file\fP option and execute states based on that top file on the Salt Master .UNINDENT .SS Examples: .sp Execute \fBstate.apply\fP to run the highstate when starting the minion: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C startup_states: highstate .ft P .fi .UNINDENT .UNINDENT .sp Execute the sls files \fIedit.vim\fP and \fIhyper\fP: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C startup_states: sls sls_list: \- edit.vim \- hyper .ft P .fi .UNINDENT .UNINDENT .SS State Testing .sp Executing a Salt state run can potentially change many aspects of a system and it may be desirable to first see what a state run is going to change before applying the run. .sp Salt has a test interface to report on exactly what will be changed, this interface can be invoked on any of the major state run functions: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq state.apply test=True salt \(aq*\(aq state.apply mysls test=True salt \(aq*\(aq state.single test=True .ft P .fi .UNINDENT .UNINDENT .sp The test run is mandated by adding the \fBtest=True\fP option to the states. The return information will show states that will be applied in yellow and the result is reported as \fBNone\fP\&. .SS Default Test .sp If the value \fBtest\fP is set to \fBTrue\fP in the minion configuration file then states will default to being executed in test mode. If this value is set then states can still be run by calling test=False: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq state.apply test=False salt \(aq*\(aq state.apply mysls test=False salt \(aq*\(aq state.single test=False .ft P .fi .UNINDENT .UNINDENT .SS The Top File .SS Introduction .sp Most infrastructures are made up of groups of machines, each machine in the group performing a role similar to others. Those groups of machines work in concert with each other to create an application stack. .sp To effectively manage those groups of machines, an administrator needs to be able to create roles for those groups. For example, a group of machines that serve front\-end web traffic might have roles which indicate that those machines should all have the Apache webserver package installed and that the Apache service should always be running. .sp In Salt, the file which contains a mapping between groups of machines on a network and the configuration roles that should be applied to them is called a \fBtop file\fP\&. .sp Top files are named \fBtop.sls\fP by default and they are so\-named because they always exist in the "top" of a directory hierarchy that contains state files. That directory hierarchy is called a \fBstate tree\fP\&. .SS A Basic Example .sp Top files have three components: .INDENT 0.0 .IP \(bu 2 \fBEnvironment:\fP A state tree directory containing a set of state files to configure systems. .IP \(bu 2 \fBTarget:\fP A grouping of machines which will have a set of states applied to them. .IP \(bu 2 \fBState files:\fP A list of state files to apply to a target. Each state file describes one or more states to be configured and enforced on the targeted machines. .UNINDENT .sp The relationship between these three components is nested as follows: .INDENT 0.0 .IP \(bu 2 Environments contain targets .IP \(bu 2 Targets contain states .UNINDENT .sp Putting these concepts together, we can describe a scenario in which all minions with an ID that begins with \fBweb\fP have an \fBapache\fP state applied to them: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C base: # Apply SLS files from the directory root for the \(aqbase\(aq environment \(aqweb*\(aq: # All minions with a minion_id that begins with \(aqweb\(aq \- apache # Apply the state file named \(aqapache.sls\(aq .ft P .fi .UNINDENT .UNINDENT .SS Environments .sp Environments are directory hierarchies which contain a top files and a set of state files. .sp Environments can be used in many ways, however there is no requirement that they be used at all. In fact, the most common way to deploy Salt is with a single environment, called \fBbase\fP\&. It is recommended that users only create multiple environments if they have a use case which specifically calls for multiple versions of state trees. .SS Getting Started with Top Files .sp Each environment is defined inside a salt master configuration variable called, \fBfile_roots\fP . .sp In the most common single\-environment setup, only the \fBbase\fP environment is defined in \fBfile_roots\fP along with only one directory path for the state tree. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C file_roots: base: \- /srv/salt .ft P .fi .UNINDENT .UNINDENT .sp In the above example, the top file will only have a single environment to pull from. .sp Next is a simple single\-environment top file placed in \fB/srv/salt/top.sls\fP, illustrating that for the environment called \fBbase\fP, all minions will have the state files named \fBcore.sls\fP and \fBedit.sls\fP applied to them. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C base: \(aq*\(aq: \- core \- edit .ft P .fi .UNINDENT .UNINDENT .sp Assuming the \fBfile_roots\fP configuration from above, Salt will look in the \fB/srv/salt\fP directory for \fBcore.sls\fP and \fBedit.sls\fP\&. .SS Multiple Environments .sp In some cases, teams may wish to create versioned state trees which can be used to test Salt configurations in isolated sets of systems such as a staging environment before deploying states into production. .sp For this case, multiple environments can be used to accomplish this task. .sp To create multiple environments, the \fBfile_roots\fP option can be expanded: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C file_roots: dev: \- /srv/salt/dev qa: \- /srv/salt/qa prod: \- /srv/salt/prod .ft P .fi .UNINDENT .UNINDENT .sp In the above, we declare three environments: \fBdev\fP, \fBqa\fP and \fBprod\fP\&. Each environment has a single directory assigned to it. .sp Our top file references the environments: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C dev: \(aqwebserver*\(aq: \- webserver \(aqdb*\(aq: \- db qa: \(aqwebserver*\(aq: \- webserver \(aqdb*\(aq: \- db prod: \(aqwebserver*\(aq: \- webserver \(aqdb*\(aq: \- db .ft P .fi .UNINDENT .UNINDENT .sp As seen above, the top file now declares the three environments and for each, targets are defined to map globs of minion IDs to state files. For example, all minions which have an ID beginning with the string \fBwebserver\fP will have the webserver state from the requested environment assigned to it. .sp In this manner, a proposed change to a state could first be made in a state file in \fB/srv/salt/dev\fP and then be applied to development webservers before moving the state into QA by copying the state file into \fB/srv/salt/qa\fP\&. .SS Choosing an Environment to Target .sp The top file is used to assign a minion to an environment unless overridden using the methods described below. The environment in the top file must match valid fileserver environment (a.k.a. \fBsaltenv\fP) in order for any states to be applied to that minion. When using the default fileserver backend, environments are defined in \fBfile_roots\fP\&. .sp The states that will be applied to a minion in a given environment can be viewed using the \fBstate.show_top\fP function. .sp Minions may be pinned to a particular environment by setting the \fBenvironment\fP value in the minion configuration file. In doing so, a minion will only request files from the environment to which it is assigned. .sp The environment may also be dynamically selected at runtime by passing it to the \fBsalt\fP, \fBsalt\-call\fP or \fBsalt\-ssh\fP command. This is most commonly done with functions in the \fBstate\fP module by using the \fBsaltenv\fP argument. For example, to run a \fBhighstate\fP on all minions, using only the top file and SLS files in the \fBprod\fP environment, run: \fBsalt \(aq*\(aq state.highstate saltenv=prod\fP\&. .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 Not all functions accept \fBsaltenv\fP as an argument, see the documentation for an individual function documentation to verify. .UNINDENT .UNINDENT .SS Shorthand .sp If you assign only one SLS to a system, as in this example, a shorthand is also available: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C base: \(aq*\(aq: global dev: \(aqwebserver*\(aq: webserver \(aqdb*\(aq: db qa: \(aqwebserver*\(aq: webserver \(aqdb*\(aq: db prod: \(aqwebserver*\(aq: webserver \(aqdb*\(aq: db .ft P .fi .UNINDENT .UNINDENT .SS Advanced Minion Targeting .sp In addition to globs, minions can be specified in top files a few other ways. Some common ones are compound matches and node groups\&. .sp Below is a slightly more complex top file example, showing the different types of matches you can perform: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C # All files will be taken from the file path specified in the base # environment in the \(ga\(gafile_roots\(ga\(ga configuration value. base: # All minions get the following three state files applied \(aq*\(aq: \- ldap\-client \- networking \- salt.minion # All minions which have an ID that begins with the phrase # \(aqsalt\-master\(aq will have an SLS file applied that is named # \(aqmaster.sls\(aq and is in the \(aqsalt\(aq directory, underneath # the root specified in the \(ga\(gabase\(ga\(ga environment in the # configuration value for \(ga\(gafile_roots\(ga\(ga. \(aqsalt\-master*\(aq: \- salt.master # Minions that have an ID matching the following regular # expression will have the state file called \(aqweb.sls\(aq in the # nagios/mon directory applied. Additionally, minions matching # the regular expression will also have the \(aqserver.sls\(aq file # in the apache/ directory applied. # NOTE! # # Take note of the \(aqmatch\(aq directive here, which tells Salt # to treat the target string as a regex to be matched! \(aq^(memcache|web).(qa|prod).loc$\(aq: \- match: pcre \- nagios.mon.web \- apache.server # Minions that have a grain set indicating that they are running # the Ubuntu operating system will have the state file called # \(aqubuntu.sls\(aq in the \(aqrepos\(aq directory applied. # # Again take note of the \(aqmatch\(aq directive here which tells # Salt to match against a grain instead of a minion ID. \(aqos:Ubuntu\(aq: \- match: grain \- repos.ubuntu # Minions that are either RedHat or CentOS should have the \(aqepel.sls\(aq # state applied, from the \(aqrepos/\(aq directory. \(aqos:(RedHat|CentOS)\(aq: \- match: grain_pcre \- repos.epel # The three minions with the IDs of \(aqfoo\(aq, \(aqbar\(aq and \(aqbaz\(aq should # have \(aqdatabase.sls\(aq applied. \(aqfoo,bar,baz\(aq: \- match: list \- database # Any minion for which the pillar key \(aqsomekey\(aq is set and has a value # of that key matching \(aqabc\(aq will have the \(aqxyz.sls\(aq state applied. \(aqsomekey:abc\(aq: \- match: pillar \- xyz # All minions which begin with the strings \(aqnag1\(aq or any minion with # a grain set called \(aqrole\(aq with the value of \(aqmonitoring\(aq will have # the \(aqserver.sls\(aq state file applied from the \(aqnagios/\(aq directory. \(aqnag1* or G@role:monitoring\(aq: \- match: compound \- nagios.server .ft P .fi .UNINDENT .UNINDENT .SS How Top Files Are Compiled .sp When a highstate is executed and an environment is specified (either using the \fBenvironment\fP config option or by passing the saltenv when executing the highstate), then that environment\(aqs top file is the only top file used to assign states to minions, and only states from the specified environment will be run. .sp The remainder of this section applies to cases in which a highstate is executed without an environment specified. .sp With no environment specified, the minion will look for a top file in each environment, and each top file will be processed to determine the SLS files to run on the minions. By default, the top files from each environment will be merged together. In configurations with many environments, such as with GitFS where each branch and tag is treated as a distinct environment, this may cause unexpected results as SLS files from older tags cause defunct SLS files to be included in the highstate. In cases like this, it can be helpful to set \fBtop_file_merging_strategy\fP to \fBsame\fP to force each environment to use its own top file. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C top_file_merging_strategy: same .ft P .fi .UNINDENT .UNINDENT .sp Another option would be to set \fBstate_top_saltenv\fP to a specific environment, to ensure that any top files in other environments are disregarded: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C state_top_saltenv: base .ft P .fi .UNINDENT .UNINDENT .sp With GitFS, it can also be helpful to simply manage each environment\(aqs top file separately, and/or manually specify the environment when executing the highstate to avoid any complicated merging scenarios. \fBgitfs_env_whitelist\fP and \fBgitfs_env_blacklist\fP can also be used to hide unneeded branches and tags from GitFS to reduce the number of top files in play. .sp When using multiple environments, it is not necessary to create a top file for each environment. The easiest\-to\-maintain approach is to use a single top file placed in the \fBbase\fP environment. This is often infeasible with GitFS though, since branching/tagging can easily result in extra top files. However, when only the default (\fBroots\fP) fileserver backend is used, a single top file in the \fBbase\fP environment is the most common way of configuring a highstate\&. .sp The following minion configuration options affect how top files are compiled when no environment is specified, it is recommended to follow the below four links to learn more about how these options work: .INDENT 0.0 .IP \(bu 2 \fBstate_top_saltenv\fP .IP \(bu 2 \fBtop_file_merging_strategy\fP .IP \(bu 2 \fBenv_order\fP .IP \(bu 2 \fBdefault_top\fP .UNINDENT .SS Top File Compilation Examples .sp For the scenarios below, assume the following configuration: .sp \fB/etc/salt/master\fP: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C file_roots: base: \- /srv/salt/base dev: \- /srv/salt/dev qa: \- /srv/salt/qa .ft P .fi .UNINDENT .UNINDENT .sp \fB/srv/salt/base/top.sls\fP: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C base: \(aq*\(aq: \- base1 dev: \(aq*\(aq: \- dev1 qa: \(aq*\(aq: \- qa1 .ft P .fi .UNINDENT .UNINDENT .sp \fB/srv/salt/dev/top.sls\fP: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C base: \(aqminion1\(aq: \- base2 dev: \(aqminion2\(aq: \- dev2 qa: \(aq*\(aq: \- qa1 \- qa2 .ft P .fi .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 For the purposes of these examples, there is no top file in the \fBqa\fP environment. .UNINDENT .UNINDENT .SS Scenario 1 \- \fBdev\fP Environment Specified .sp In this scenario, the highstate was either invoked with \fBsaltenv=dev\fP or the minion has \fBenvironment: dev\fP set in the minion config file. The result will be that only the \fBdev2\fP SLS from the dev environment will be part of the highstate, and it will be applied to minion2, while minion1 will have no states applied to it. .sp If the \fBbase\fP environment were specified, the result would be that only the \fBbase1\fP SLS from the \fBbase\fP environment would be part of the highstate, and it would be applied to all minions. .sp If the \fBqa\fP environment were specified, the highstate would exit with an error. .SS Scenario 2 \- No Environment Specified, \fBtop_file_merging_strategy\fP is "merge" .sp In this scenario, assuming that the \fBbase\fP environment\(aqs top file was evaluated first, the \fBbase1\fP, \fBdev1\fP, and \fBqa1\fP states would be applied to all minions. If, for instance, the \fBqa\fP environment is not defined in \fB/srv/salt/base/top.sls\fP, then because there is no top file for the \fBqa\fP environment, no states from the \fBqa\fP environment would be applied. .SS Scenario 3 \- No Environment Specified, \fBtop_file_merging_strategy\fP is "same" .sp Changed in version 2016.11.0: In prior versions, "same" did not quite work as described below (see \fI\%here\fP). This has now been corrected. It was decided that changing something like top file handling in a point release had the potential to unexpectedly impact users\(aq top files too much, and it would be better to make this correction in a feature release. .sp In this scenario, \fBbase1\fP from the \fBbase\fP environment is applied to all minions. Additionally, \fBdev2\fP from the \fBdev\fP environment is applied to minion2. .sp If \fBdefault_top\fP is unset (or set to \fBbase\fP, which happens to be the default), then \fBqa1\fP from the \fBqa\fP environment will be applied to all minions. If \fBdefault_top\fP were set to \fBdev\fP, then both \fBqa1\fP and \fBqa2\fP from the \fBqa\fP environment would be applied to all minions. .SS Scenario 4 \- No Environment Specified, \fBtop_file_merging_strategy\fP is "merge_all" .sp New in version 2016.11.0. .sp In this scenario, all configured states in all top files are applied. From the \fBbase\fP environment, \fBbase1\fP would be applied to all minions, with \fBbase2\fP being applied only to \fBminion1\fP\&. From the \fBdev\fP environment, \fBdev1\fP would be applied to all minions, with \fBdev2\fP being applied only to \fBminion2\fP\&. Finally, from the \fBqa\fP environment, both the \fBqa1\fP and \fBqa2\fP states will be applied to all minions. Note that the \fBqa1\fP states would not be applied twice, even though \fBqa1\fP appears twice. .SS SLS Template Variable Reference .sp The template engines available to sls files and file templates come loaded with a number of context variables. These variables contain information and functions to assist in the generation of templates. See each variable below for its availability \-\- not all variables are available in all templating contexts. .SS Salt .sp The \fIsalt\fP variable is available to abstract the salt library functions. This variable is a python dictionary containing all of the functions available to the running salt minion. It is available in all salt templates. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C {% for file in salt[\(aqcmd.run\(aq](\(aqls \-1 /opt/to_remove\(aq).splitlines() %} /opt/to_remove/{{ file }}: file.absent {% endfor %} .ft P .fi .UNINDENT .UNINDENT .SS Opts .sp The \fIopts\fP variable abstracts the contents of the minion\(aqs configuration file directly to the template. The \fIopts\fP variable is a dictionary. It is available in all templates. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C {{ opts[\(aqcachedir\(aq] }} .ft P .fi .UNINDENT .UNINDENT .sp The \fBconfig.get\fP function also searches for values in the \fIopts\fP dictionary. .SS Pillar .sp The \fIpillar\fP dictionary can be referenced directly, and is available in all templates: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C {{ pillar[\(aqkey\(aq] }} .ft P .fi .UNINDENT .UNINDENT .sp Using the \fBpillar.get\fP function via the \fIsalt\fP variable is generally recommended since a default can be safely set in the event that the value is not available in pillar and dictionaries can be traversed directly: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C {{ salt[\(aqpillar.get\(aq](\(aqkey\(aq, \(aqfailover_value\(aq) }} {{ salt[\(aqpillar.get\(aq](\(aqstuff:more:deeper\(aq) }} .ft P .fi .UNINDENT .UNINDENT .SS Grains .sp The \fIgrains\fP dictionary makes the minion\(aqs grains directly available, and is available in all templates: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C {{ grains[\(aqos\(aq] }} .ft P .fi .UNINDENT .UNINDENT .sp The \fBgrains.get\fP function can be used to traverse deeper grains and set defaults: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C {{ salt[\(aqgrains.get\(aq](\(aqos\(aq) }} .ft P .fi .UNINDENT .UNINDENT .SS saltenv .sp The \fIsaltenv\fP variable is available in only in sls files when gathering the sls from an environment. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C {{ saltenv }} .ft P .fi .UNINDENT .UNINDENT .SS sls .sp The \fIsls\fP variable contains the sls reference value, and is only available in the actual SLS file (not in any files referenced in that SLS). The sls reference value is the value used to include the sls in top files or via the include option. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C {{ sls }} .ft P .fi .UNINDENT .UNINDENT .SS slspath .sp The \fIslspath\fP variable contains the path to the current sls file. The value of \fIslspath\fP in files referenced in the current sls depends on the reference method. For jinja includes \fIslspath\fP is the path to the current file. For salt includes \fIslspath\fP is the path to the included file. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C {{ slspath }} .ft P .fi .UNINDENT .UNINDENT .SS State Modules .sp State Modules are the components that map to actual enforcement and management of Salt states. .SS States are Easy to Write! .sp State Modules should be easy to write and straightforward. The information passed to the SLS data structures will map directly to the states modules. .sp Mapping the information from the SLS data is simple, this example should illustrate: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C /etc/salt/master: # maps to "name" file.managed: # maps to . \- e.g. "managed" in https://github.com/saltstack/salt/tree/develop/salt/states/file.py \- user: root # one of many options passed to the manage function \- group: root \- mode: 644 \- source: salt://salt/master .ft P .fi .UNINDENT .UNINDENT .sp Therefore this SLS data can be directly linked to a module, function, and arguments passed to that function. .sp This does issue the burden, that function names, state names and function arguments should be very human readable inside state modules, since they directly define the user interface. .INDENT 0.0 .INDENT 3.5 .IP "Keyword Arguments" .sp Salt passes a number of keyword arguments to states when rendering them, including the environment, a unique identifier for the state, and more. Additionally, keep in mind that the requisites for a state are part of the keyword arguments. Therefore, if you need to iterate through the keyword arguments in a state, these must be considered and handled appropriately. One such example is in the \fBpkgrepo.managed\fP state, which needs to be able to handle arbitrary keyword arguments and pass them to module execution functions. An example of how these keyword arguments can be handled can be found \fI\%here\fP\&. .UNINDENT .UNINDENT .SS Using Custom State Modules .sp Place your custom state modules inside a \fB_states\fP directory within the \fBfile_roots\fP specified by the master config file. These custom state modules can then be distributed in a number of ways. Custom state modules are distributed when \fBstate.apply\fP is run, or by executing the \fBsaltutil.sync_states\fP or \fBsaltutil.sync_all\fP functions. .sp Any custom states which have been synced to a minion, that are named the same as one of Salt\(aqs default set of states, will take the place of the default state with the same name. Note that a state\(aqs default name is its filename (i.e. \fBfoo.py\fP becomes state \fBfoo\fP), but that its name can be overridden by using a __virtual__ function\&. .SS Cross Calling Execution Modules from States .sp As with Execution Modules, State Modules can also make use of the \fB__salt__\fP and \fB__grains__\fP data. See cross calling execution modules\&. .sp It is important to note that the real work of state management should not be done in the state module unless it is needed. A good example is the pkg state module. This module does not do any package management work, it just calls the pkg execution module. This makes the pkg state module completely generic, which is why there is only one pkg state module and many backend pkg execution modules. .sp On the other hand some modules will require that the logic be placed in the state module, a good example of this is the file module. But in the vast majority of cases this is not the best approach, and writing specific execution modules to do the backend work will be the optimal solution. .SS Cross Calling State Modules .sp All of the Salt state modules are available to each other and state modules can call functions available in other state modules. .sp The variable \fB__states__\fP is packed into the modules after they are loaded into the Salt minion. .sp The \fB__states__\fP variable is a \fI\%Python dictionary\fP containing all of the state modules. Dictionary keys are strings representing the names of the modules and the values are the functions themselves. .sp Salt state modules can be cross\-called by accessing the value in the \fB__states__\fP dict: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C ret = __states__[\(aqfile.managed\(aq](name=\(aq/tmp/myfile\(aq, source=\(aqsalt://myfile\(aq) .ft P .fi .UNINDENT .UNINDENT .sp This code will call the \fImanaged\fP function in the \fBfile\fP state module and pass the arguments \fBname\fP and \fBsource\fP to it. .SS Return Data .sp A State Module must return a dict containing the following keys/values: .INDENT 0.0 .IP \(bu 2 \fBname:\fP The same value passed to the state as "name". .IP \(bu 2 \fBchanges:\fP A dict describing the changes made. Each thing changed should be a key, with its value being another dict with keys called "old" and "new" containing the old/new values. For example, the pkg state\(aqs \fBchanges\fP dict has one key for each package changed, with the "old" and "new" keys in its sub\-dict containing the old and new versions of the package. For example, the final changes dictionary for this scenario would look something like this: .INDENT 2.0 .INDENT 3.5 .sp .nf .ft C ret[\(aqchanges\(aq].update({\(aqmy_pkg_name\(aq: {\(aqold\(aq: \(aq\(aq, \(aqnew\(aq: \(aqmy_pkg_name\-1.0\(aq}}) .ft P .fi .UNINDENT .UNINDENT .IP \(bu 2 \fBresult:\fP A tristate value. \fBTrue\fP if the action was successful, \fBFalse\fP if it was not, or \fBNone\fP if the state was run in test mode, \fBtest=True\fP, and changes would have been made if the state was not run in test mode. .TS center; |l|l|l|. _ T{ T} T{ live mode T} T{ test mode T} _ T{ no changes T} T{ \fBTrue\fP T} T{ \fBTrue\fP T} _ T{ successful changes T} T{ \fBTrue\fP T} T{ \fBNone\fP T} _ T{ failed changes T} T{ \fBFalse\fP T} T{ \fBNone\fP T} _ .TE .sp \fBNOTE:\fP .INDENT 2.0 .INDENT 3.5 Test mode does not predict if the changes will be successful or not. .UNINDENT .UNINDENT .IP \(bu 2 \fBcomment:\fP A string containing a summary of the result. .UNINDENT .sp The return data can also, include the \fBpchanges\fP key, this stands for \fIpredictive changes\fP\&. The \fBpchanges\fP key informs the State system what changes are predicted to occur. .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 States should not return data which cannot be serialized such as frozensets. .UNINDENT .UNINDENT .SS Test State .sp All states should check for and support \fBtest\fP being passed in the options. This will return data about what changes would occur if the state were actually run. An example of such a check could look like this: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C # Return comment of changes if test. if __opts__[\(aqtest\(aq]: ret[\(aqresult\(aq] = None ret[\(aqcomment\(aq] = \(aqState Foo will execute with param {0}\(aq.format(bar) return ret .ft P .fi .UNINDENT .UNINDENT .sp Make sure to test and return before performing any real actions on the minion. .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 Be sure to refer to the \fBresult\fP table listed above and displaying any possible changes when writing support for \fBtest\fP\&. Looking for changes in a state is essential to \fBtest=true\fP functionality. If a state is predicted to have no changes when \fBtest=true\fP (or \fBtest: true\fP in a config file) is used, then the result of the final state \fBshould not\fP be \fBNone\fP\&. .UNINDENT .UNINDENT .SS Watcher Function .sp If the state being written should support the watch requisite then a watcher function needs to be declared. The watcher function is called whenever the watch requisite is invoked and should be generic to the behavior of the state itself. .sp The watcher function should accept all of the options that the normal state functions accept (as they will be passed into the watcher function). .sp A watcher function typically is used to execute state specific reactive behavior, for instance, the watcher for the service module restarts the named service and makes it useful for the watcher to make the service react to changes in the environment. .sp The watcher function also needs to return the same data that a normal state function returns. .SS Mod_init Interface .sp Some states need to execute something only once to ensure that an environment has been set up, or certain conditions global to the state behavior can be predefined. This is the realm of the mod_init interface. .sp A state module can have a function called \fBmod_init\fP which executes when the first state of this type is called. This interface was created primarily to improve the pkg state. When packages are installed the package metadata needs to be refreshed, but refreshing the package metadata every time a package is installed is wasteful. The mod_init function for the pkg state sets a flag down so that the first, and only the first, package installation attempt will refresh the package database (the package database can of course be manually called to refresh via the \fBrefresh\fP option in the pkg state). .sp The mod_init function must accept the \fBLow State Data\fP for the given executing state as an argument. The low state data is a dict and can be seen by executing the state.show_lowstate function. Then the mod_init function must return a bool. If the return value is True, then the mod_init function will not be executed again, meaning that the needed behavior has been set up. Otherwise, if the mod_init function returns False, then the function will be called the next time. .sp A good example of the mod_init function is found in the pkg state module: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C def mod_init(low): \(aq\(aq\(aq Refresh the package database here so that it only needs to happen once \(aq\(aq\(aq if low[\(aqfun\(aq] == \(aqinstalled\(aq or low[\(aqfun\(aq] == \(aqlatest\(aq: rtag = __gen_rtag() if not os.path.exists(rtag): open(rtag, \(aqw+\(aq).write(\(aq\(aq) return True else: return False .ft P .fi .UNINDENT .UNINDENT .sp The mod_init function in the pkg state accepts the low state data as \fBlow\fP and then checks to see if the function being called is going to install packages, if the function is not going to install packages then there is no need to refresh the package database. Therefore if the package database is prepared to refresh, then return True and the mod_init will not be called the next time a pkg state is evaluated, otherwise return False and the mod_init will be called next time a pkg state is evaluated. .SS Log Output .sp You can call the logger from custom modules to write messages to the minion logs. The following code snippet demonstrates writing log messages: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C import logging log = logging.getLogger(__name__) log.info(\(aqHere is Some Information\(aq) log.warning(\(aqYou Should Not Do That\(aq) log.error(\(aqIt Is Busted\(aq) .ft P .fi .UNINDENT .UNINDENT .SS Strings and Unicode .sp A state module author should always assume that strings fed to the module have already decoded from strings into Unicode. In Python 2, these will be of type \(aqUnicode\(aq and in Python 3 they will be of type \fBstr\fP\&. Calling from a state to other Salt sub\-systems, such as execution modules should pass Unicode (or bytes if passing binary data). In the rare event that a state needs to write directly to disk, Unicode should be encoded to a string immediately before writing to disk. An author may use \fB__salt_system_encoding__\fP to learn what the encoding type of the system is. For example, \fI\(aqmy_string\(aq.encode(__salt_system_encoding__\(aq)\fP\&. .SS Full State Module Example .sp The following is a simplistic example of a full state module and function. Remember to call out to execution modules to perform all the real work. The state module should only perform "before" and "after" checks. .INDENT 0.0 .IP 1. 3 Make a custom state module by putting the code into a file at the following path: \fB/srv/salt/_states/my_custom_state.py\fP\&. .IP 2. 3 Distribute the custom state module to the minions: .INDENT 3.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq saltutil.sync_states .ft P .fi .UNINDENT .UNINDENT .IP 3. 3 Write a new state to use the custom state by making a new state file, for instance \fB/srv/salt/my_custom_state.sls\fP\&. .IP 4. 3 Add the following SLS configuration to the file created in Step 3: .INDENT 3.0 .INDENT 3.5 .sp .nf .ft C human_friendly_state_id: # An arbitrary state ID declaration. my_custom_state: # The custom state module name. \- enforce_custom_thing # The function in the custom state module. \- name: a_value # Maps to the \(ga\(ganame\(ga\(ga parameter in the custom function. \- foo: Foo # Specify the required \(ga\(gafoo\(ga\(ga parameter. \- bar: False # Override the default value for the \(ga\(gabar\(ga\(ga parameter. .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS Example state module .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C import salt.exceptions def enforce_custom_thing(name, foo, bar=True): \(aq\(aq\(aq Enforce the state of a custom thing This state module does a custom thing. It calls out to the execution module \(ga\(gamy_custom_module\(ga\(ga in order to check the current system and perform any needed changes. name The thing to do something to foo A required argument bar : True An argument with a default value \(aq\(aq\(aq ret = { \(aqname\(aq: name, \(aqchanges\(aq: {}, \(aqresult\(aq: False, \(aqcomment\(aq: \(aq\(aq, \(aqpchanges\(aq: {}, } # Start with basic error\-checking. Do all the passed parameters make sense # and agree with each\-other? if bar == True and foo.startswith(\(aqFoo\(aq): raise salt.exceptions.SaltInvocationError( \(aqArgument "foo" cannot start with "Foo" if argument "bar" is True.\(aq) # Check the current state of the system. Does anything need to change? current_state = __salt__[\(aqmy_custom_module.current_state\(aq](name) if current_state == foo: ret[\(aqresult\(aq] = True ret[\(aqcomment\(aq] = \(aqSystem already in the correct state\(aq return ret # The state of the system does need to be changed. Check if we\(aqre running # in \(ga\(gatest=true\(ga\(ga mode. if __opts__[\(aqtest\(aq] == True: ret[\(aqcomment\(aq] = \(aqThe state of "{0}" will be changed.\(aq.format(name) ret[\(aqpchanges\(aq] = { \(aqold\(aq: current_state, \(aqnew\(aq: \(aqDescription, diff, whatever of the new state\(aq, } # Return \(ga\(gaNone\(ga\(ga when running with \(ga\(gatest=true\(ga\(ga. ret[\(aqresult\(aq] = None return ret # Finally, make the actual change and return the result. new_state = __salt__[\(aqmy_custom_module.change_state\(aq](name, foo) ret[\(aqcomment\(aq] = \(aqThe state of "{0}" was changed!\(aq.format(name) ret[\(aqchanges\(aq] = { \(aqold\(aq: current_state, \(aqnew\(aq: new_state, } ret[\(aqresult\(aq] = True return ret .ft P .fi .UNINDENT .UNINDENT .SS State Management .sp State management, also frequently called Software Configuration Management (SCM), is a program that puts and keeps a system into a predetermined state. It installs software packages, starts or restarts services or puts configuration files in place and watches them for changes. .sp Having a state management system in place allows one to easily and reliably configure and manage a few servers or a few thousand servers. It allows configurations to be kept under version control. .sp Salt States is an extension of the Salt Modules that we discussed in the previous remote execution tutorial. Instead of calling one\-off executions the state of a system can be easily defined and then enforced. .SS Understanding the Salt State System Components .sp The Salt state system is comprised of a number of components. As a user, an understanding of the SLS and renderer systems are needed. But as a developer, an understanding of Salt states and how to write the states is needed as well. .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 States are compiled and executed only on minions that have been targeted. To execute functions directly on masters, see runners\&. .UNINDENT .UNINDENT .SS Salt SLS System .sp The primary system used by the Salt state system is the SLS system. SLS stands for \fBS\fPa\fBL\fPt \fBS\fPtate. .sp The Salt States are files which contain the information about how to configure Salt minions. The states are laid out in a directory tree and can be written in many different formats. .sp The contents of the files and they way they are laid out is intended to be as simple as possible while allowing for maximum flexibility. The files are laid out in states and contains information about how the minion needs to be configured. .SS SLS File Layout .sp SLS files are laid out in the Salt file server. .sp A simple layout can look like this: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C top.sls ssh.sls sshd_config users/init.sls users/admin.sls salt/master.sls web/init.sls .ft P .fi .UNINDENT .UNINDENT .sp The \fBtop.sls\fP file is a key component. The \fBtop.sls\fP files is used to determine which SLS files should be applied to which minions. .sp The rest of the files with the \fB\&.sls\fP extension in the above example are state files. .sp Files without a \fB\&.sls\fP extensions are seen by the Salt master as files that can be downloaded to a Salt minion. .sp States are translated into dot notation. For example, the \fBssh.sls\fP file is seen as the ssh state and the \fBusers/admin.sls\fP file is seen as the users.admin state. .sp Files named \fBinit.sls\fP are translated to be the state name of the parent directory, so the \fBweb/init.sls\fP file translates to the \fBweb\fP state. .sp In Salt, everything is a file; there is no "magic translation" of files and file types. This means that a state file can be distributed to minions just like a plain text or binary file. .SS SLS Files .sp The Salt state files are simple sets of data. Since SLS files are just data they can be represented in a number of different ways. .sp The default format is YAML generated from a Jinja template. This allows for the states files to have all the language constructs of Python and the simplicity of YAML. .sp State files can then be complicated Jinja templates that translate down to YAML, or just plain and simple YAML files. .sp The State files are simply common data structures such as dictionaries and lists, constructed using a templating language such as YAML. .sp Here is an example of a Salt State: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C vim: pkg.installed: [] salt: pkg.latest: \- name: salt service.running: \- names: \- salt\-master \- salt\-minion \- require: \- pkg: salt \- watch: \- file: /etc/salt/minion /etc/salt/minion: file.managed: \- source: salt://salt/minion \- user: root \- group: root \- mode: 644 \- require: \- pkg: salt .ft P .fi .UNINDENT .UNINDENT .sp This short stanza will ensure that vim is installed, Salt is installed and up to date, the salt\-master and salt\-minion daemons are running and the Salt minion configuration file is in place. It will also ensure everything is deployed in the right order and that the Salt services are restarted when the watched file updated. .SS The Top File .sp The top file controls the mapping between minions and the states which should be applied to them. .sp The top file specifies which minions should have which SLS files applied and which environments they should draw those SLS files from. .sp The top file works by specifying environments on the top\-level. .sp Each environment contains globs to match minions. Finally, each glob contains a list of lists of Salt states to apply to matching minions: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C base: \(aq*\(aq: \- salt \- users \- users.admin \(aqsaltmaster.*\(aq: \- match: pcre \- salt.master .ft P .fi .UNINDENT .UNINDENT .sp This above example uses the base environment which is built into the default Salt setup. .sp The base environment has two globs. First, the \(aq*\(aq glob contains a list of SLS files to apply to all minions. .sp The second glob contains a regular expression that will match all minions with an ID matching saltmaster.* and specifies that for those minions, the salt.master state should be applied. .SS Reloading Modules .sp Some Salt states require that specific packages be installed in order for the module to load. As an example the \fBpip\fP state module requires the \fI\%pip\fP package for proper name and version parsing. .sp In most of the common cases, Salt is clever enough to transparently reload the modules. For example, if you install a package, Salt reloads modules because some other module or state might require just that package which was installed. .sp On some edge\-cases salt might need to be told to reload the modules. Consider the following state file which we\(aqll call \fBpep8.sls\fP: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C python\-pip: cmd.run: \- name: | easy_install \-\-script\-dir=/usr/bin \-U pip \- cwd: / pep8: pip.installed: \- require: \- cmd: python\-pip .ft P .fi .UNINDENT .UNINDENT .sp The above example installs \fI\%pip\fP using \fBeasy_install\fP from \fI\%setuptools\fP and installs \fI\%pep8\fP using \fBpip\fP, which, as told earlier, requires \fI\%pip\fP to be installed system\-wide. Let\(aqs execute this state: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt\-call state.apply pep8 .ft P .fi .UNINDENT .UNINDENT .sp The execution output would be something like: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C \-\-\-\-\-\-\-\-\-\- State: \- pip Name: pep8 Function: installed Result: False Comment: State pip.installed found in sls pep8 is unavailable Changes: Summary \-\-\-\-\-\-\-\-\-\-\-\- Succeeded: 1 Failed: 1 \-\-\-\-\-\-\-\-\-\-\-\- Total: 2 .ft P .fi .UNINDENT .UNINDENT .sp If we executed the state again the output would be: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C \-\-\-\-\-\-\-\-\-\- State: \- pip Name: pep8 Function: installed Result: True Comment: Package was successfully installed Changes: pep8==1.4.6: Installed Summary \-\-\-\-\-\-\-\-\-\-\-\- Succeeded: 2 Failed: 0 \-\-\-\-\-\-\-\-\-\-\-\- Total: 2 .ft P .fi .UNINDENT .UNINDENT .sp Since we installed \fI\%pip\fP using \fBcmd\fP, Salt has no way to know that a system\-wide package was installed. .sp On the second execution, since the required \fI\%pip\fP package was installed, the state executed correctly. .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 Salt does not reload modules on every state run because doing so would greatly slow down state execution. .UNINDENT .UNINDENT .sp So how do we solve this \fIedge\-case\fP? \fBreload_modules\fP! .sp \fBreload_modules\fP is a boolean option recognized by salt on \fBall\fP available states which forces salt to reload its modules once a given state finishes. .sp The modified state file would now be: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C python\-pip: cmd.run: \- name: | easy_install \-\-script\-dir=/usr/bin \-U pip \- cwd: / \- reload_modules: true pep8: pip.installed: \- require: \- cmd: python\-pip .ft P .fi .UNINDENT .UNINDENT .sp Let\(aqs run it, once: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt\-call state.apply pep8 .ft P .fi .UNINDENT .UNINDENT .sp The output is: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C \-\-\-\-\-\-\-\-\-\- State: \- pip Name: pep8 Function: installed Result: True Comment: Package was successfully installed Changes: pep8==1.4.6: Installed Summary \-\-\-\-\-\-\-\-\-\-\-\- Succeeded: 2 Failed: 0 \-\-\-\-\-\-\-\-\-\-\-\- Total: 2 .ft P .fi .UNINDENT .UNINDENT .SH UTILITY MODULES - CODE REUSE IN CUSTOM MODULES .sp New in version 2015.5.0. .sp Changed in version 2016.11.0: These can now be synced to the Master for use in custom Runners, and in custom execution modules called within Pillar SLS files. .sp When extending Salt by writing custom (state modules), execution modules, etc., sometimes there is a need for a function to be available to more than just one kind of custom module. For these cases, Salt supports what are called "utility modules". These modules are like normal execution modules, but instead of being invoked in Salt code using \fB__salt__\fP, the \fB__utils__\fP prefix is used instead. .sp For example, assuming the following simple utility module, saved to \fBsalt://_utils/foo.py\fP .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C # \-*\- coding: utf\-8 \-*\- \(aq\(aq\(aq My utils module \-\-\-\-\-\-\-\-\-\-\-\-\-\-\- This module contains common functions for use in my other custom types. \(aq\(aq\(aq def bar(): return \(aqbaz\(aq .ft P .fi .UNINDENT .UNINDENT .sp Once synced to a minion, this function would be available to other custom Salt types like so: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C # \-*\- coding: utf\-8 \-*\- \(aq\(aq\(aq My awesome execution module \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- \(aq\(aq\(aq def observe_the_awesomeness(): \(aq\(aq\(aq Prints information from my utility module CLI Example: .. code\-block:: bash salt \(aq*\(aq mymodule.observe_the_awesomeness \(aq\(aq\(aq print __utils__[\(aqfoo.bar\(aq]() .ft P .fi .UNINDENT .UNINDENT .sp Utility modules, like any other kind of Salt extension, support using a __virtual__ function to conditionally load them, or load them under a different namespace. For instance, if the utility module above were named \fBsalt://_utils/mymodule.py\fP it could be made to be loaded as the \fBfoo\fP utility module with a \fB__virtual__\fP function. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C # \-*\- coding: utf\-8 \-*\- \(aq\(aq\(aq My utils module \-\-\-\-\-\-\-\-\-\-\-\-\-\-\- This module contains common functions for use in my other custom types. \(aq\(aq\(aq def __virtual__(): \(aq\(aq\(aq Load as a different name \(aq\(aq\(aq return \(aqfoo\(aq def bar(): return \(aqbaz\(aq .ft P .fi .UNINDENT .UNINDENT .sp These are, of course, contrived examples, but they should serve to show some of the possibilities opened up by writing utility modules. Keep in mind though that States still have access to all of the execution modules, so it is not necessary to write a utility module to make a function available to both a state and an execution module. One good use case for utililty modules is one where it is necessary to invoke the same function from a custom outputter/returner, as well as an execution module. .sp Utility modules placed in \fBsalt://_utils/\fP will be synced to the minions when any of the following Salt functions are called: .INDENT 0.0 .IP \(bu 2 \fBstate.apply\fP .IP \(bu 2 \fBsaltutil.sync_utils\fP .IP \(bu 2 \fBsaltutil.sync_all\fP .UNINDENT .sp To sync to the Master, use either of the following: .INDENT 0.0 .IP \(bu 2 \fBsaltutil.sync_utils\fP .IP \(bu 2 \fBsaltutil.sync_all\fP .UNINDENT .SH EVENTS & REACTOR .SS Event System .sp The Salt Event 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 two primary components: .INDENT 0.0 .INDENT 3.5 .INDENT 0.0 .IP \(bu 2 The event sockets which publishes events. .IP \(bu 2 The event library which can listen to events and send events into the salt system. .UNINDENT .UNINDENT .UNINDENT .SS Event types .SS Salt Master Events .sp These events are fired on the Salt Master event bus. This list is \fBnot\fP comprehensive. .SS Authentication events .INDENT 0.0 .TP .B salt/auth Fired when a minion performs an authentication check with the master. .INDENT 7.0 .TP .B Variables .INDENT 7.0 .IP \(bu 2 \fBid\fP \-\- The minion ID. .IP \(bu 2 \fBact\fP \-\- The current status of the minion key: \fBaccept\fP, \fBpend\fP, \fBreject\fP\&. .IP \(bu 2 \fBpub\fP \-\- The minion public key. .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 Minions fire auth events on fairly regular basis for a number of reasons. Writing reactors to respond to events through the auth cycle can lead to infinite reactor event loops (minion tries to auth, reactor responds by doing something that generates another auth event, minion sends auth event, etc.). Consider reacting to \fBsalt/key\fP or \fBsalt/minion//start\fP or firing a custom event tag instead. .UNINDENT .UNINDENT .UNINDENT .SS Start events .INDENT 0.0 .TP .B salt/minion//start Fired every time a minion connects to the Salt master. .INDENT 7.0 .TP .B Variables \fBid\fP \-\- The minion ID. .UNINDENT .UNINDENT .SS Key events .INDENT 0.0 .TP .B salt/key Fired when accepting and rejecting minions keys on the Salt master. These happen as a result of actions undertaken by the \fIsalt\-key\fP command. .INDENT 7.0 .TP .B Variables .INDENT 7.0 .IP \(bu 2 \fBid\fP \-\- The minion ID. .IP \(bu 2 \fBact\fP \-\- The new status of the minion key: \fBaccept\fP, \fBdelete\fP, .UNINDENT .UNINDENT .UNINDENT .sp \fBWARNING:\fP .INDENT 0.0 .INDENT 3.5 If a master is in \fBauto_accept mode\fP, \fBsalt/key\fP events will not be fired when the keys are accepted. In addition, pre\-seeding keys (like happens through Salt\-Cloud) will not cause firing of these events. .UNINDENT .UNINDENT .SS Job events .INDENT 0.0 .TP .B salt/job//new Fired as a new job is sent out to minions. .INDENT 7.0 .TP .B Variables .INDENT 7.0 .IP \(bu 2 \fBjid\fP \-\- The job ID. .IP \(bu 2 \fBtgt\fP \-\- The target of the job: \fB*\fP, a minion ID, \fBG@os_family:RedHat\fP, etc. .IP \(bu 2 \fBtgt_type\fP \-\- The type of targeting used: \fBglob\fP, \fBgrain\fP, \fBcompound\fP, etc. .IP \(bu 2 \fBfun\fP \-\- The function to run on minions: \fBtest.ping\fP, \fBnetwork.interfaces\fP, etc. .IP \(bu 2 \fBarg\fP \-\- A list of arguments to pass to the function that will be called. .IP \(bu 2 \fBminions\fP \-\- A list of minion IDs that Salt expects will return data for this job. .IP \(bu 2 \fBuser\fP \-\- The name of the user that ran the command as defined in Salt\(aqs Publisher ACL or external auth. .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt/job//ret/ Fired each time a minion returns data for a job. .INDENT 7.0 .TP .B Variables .INDENT 7.0 .IP \(bu 2 \fBid\fP \-\- The minion ID. .IP \(bu 2 \fBjid\fP \-\- The job ID. .IP \(bu 2 \fBretcode\fP \-\- The return code for the job. .IP \(bu 2 \fBfun\fP \-\- The function the minion ran. E.g., \fBtest.ping\fP\&. .IP \(bu 2 \fBreturn\fP \-\- The data returned from the execution module. .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt/job//prog// Fired each time a each function in a state run completes execution. Must be enabled using the \fBstate_events\fP option. .INDENT 7.0 .TP .B Variables .INDENT 7.0 .IP \(bu 2 \fBdata\fP \-\- The data returned from the state module function. .IP \(bu 2 \fBid\fP \-\- The minion ID. .IP \(bu 2 \fBjid\fP \-\- The job ID. .UNINDENT .UNINDENT .UNINDENT .SS Runner Events .INDENT 0.0 .TP .B salt/run//new Fired as a runner begins execution .INDENT 7.0 .TP .B Variables .INDENT 7.0 .IP \(bu 2 \fBjid\fP \-\- The job ID. .IP \(bu 2 \fBfun\fP \-\- The name of the runner function, with \fBrunner.\fP prepended to it (e.g. \fBrunner.jobs.lookup_jid\fP) .IP \(bu 2 \fBfun_args\fP \-\- The arguments passed to the runner function (e.g. \fB[\(aq20160829225914848058\(aq]\fP) .IP \(bu 2 \fBuser\fP \-\- The user who executed the runner (e.g. \fBroot\fP) .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt/run//ret Fired when a runner function returns .INDENT 7.0 .TP .B Variables .INDENT 7.0 .IP \(bu 2 \fBjid\fP \-\- The job ID. .IP \(bu 2 \fBfun\fP \-\- The name of the runner function, with \fBrunner.\fP prepended to it (e.g. \fBrunner.jobs.lookup_jid\fP) .IP \(bu 2 \fBfun_args\fP \-\- The arguments passed to the runner function (e.g. \fB[\(aq20160829225914848058\(aq]\fP) .IP \(bu 2 \fBreturn\fP \-\- The data returned by the runner function .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt/run//args New in version 2016.11.0. .sp Fired by the \fBstate.orchestrate\fP runner .INDENT 7.0 .TP .B Variables .INDENT 7.0 .IP \(bu 2 \fBname\fP \-\- The ID declaration for the orchestration job (i.e. the line above \fBsalt.state\fP, \fBsalt.function\fP, \fBsalt.runner\fP, etc.) .IP \(bu 2 \fBtype\fP \-\- The type of orchestration job being run (e.g. \fBstate\fP) .IP \(bu 2 \fBtgt\fP \-\- The target expression (e.g. \fB*\fP). Included for \fBstate\fP and \fBfunction\fP types only. .IP \(bu 2 \fBargs\fP \-\- The args passed to the orchestration job. \fBNote:\fP for \fBstate\fP and \fBfunction\fP types, also includes an \fBexpr_form\fP which shows what kind of match (\fBglob\fP, \fBpcre\fP, etc.) was used. .UNINDENT .UNINDENT .UNINDENT .SS Presence Events .INDENT 0.0 .TP .B salt/presence/present Events fired on a regular interval about currently connected, newly connected, or recently disconnected minions. Requires the \fBpresence_events\fP setting to be enabled. .INDENT 7.0 .TP .B Variables \fBpresent\fP \-\- A list of minions that are currently connected to the Salt master. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt/presence/change Fired when the Presence system detects new minions connect or disconnect. .INDENT 7.0 .TP .B Variables .INDENT 7.0 .IP \(bu 2 \fBnew\fP \-\- A list of minions that have connected since the last presence event. .IP \(bu 2 \fBlost\fP \-\- A list of minions that have disconnected since the last presence event. .UNINDENT .UNINDENT .UNINDENT .SS Cloud Events .sp Unlike other Master events, \fBsalt\-cloud\fP events are not fired on behalf of a Salt Minion. Instead, \fBsalt\-cloud\fP events are fired on behalf of a VM. This is because the minion\-to\-be may not yet exist to fire events to or also may have been destroyed. .sp This behavior is reflected by the \fBname\fP variable in the event data for \fBsalt\-cloud\fP events as compared to the \fBid\fP variable for Salt Minion\-triggered events. .INDENT 0.0 .TP .B salt/cloud//creating Fired when salt\-cloud starts the VM creation process. .INDENT 7.0 .TP .B Variables .INDENT 7.0 .IP \(bu 2 \fBname\fP \-\- the name of the VM being created. .IP \(bu 2 \fBevent\fP \-\- description of the event. .IP \(bu 2 \fBprovider\fP \-\- the cloud provider of the VM being created. .IP \(bu 2 \fBprofile\fP \-\- the cloud profile for the VM being created. .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt/cloud//deploying Fired when the VM is available and salt\-cloud begins deploying Salt to the new VM. .INDENT 7.0 .TP .B Variables .INDENT 7.0 .IP \(bu 2 \fBname\fP \-\- the name of the VM being created. .IP \(bu 2 \fBevent\fP \-\- description of the event. .IP \(bu 2 \fBkwargs\fP \-\- options available as the deploy script is invoked: \fBconf_file\fP, \fBdeploy_command\fP, \fBdisplay_ssh_output\fP, \fBhost\fP, \fBkeep_tmp\fP, \fBkey_filename\fP, \fBmake_minion\fP, \fBminion_conf\fP, \fBname\fP, \fBparallel\fP, \fBpreseed_minion_keys\fP, \fBscript\fP, \fBscript_args\fP, \fBscript_env\fP, \fBsock_dir\fP, \fBstart_action\fP, \fBsudo\fP, \fBtmp_dir\fP, \fBtty\fP, \fBusername\fP .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt/cloud//requesting Fired when salt\-cloud sends the request to create a new VM. .INDENT 7.0 .TP .B Variables .INDENT 7.0 .IP \(bu 2 \fBevent\fP \-\- description of the event. .IP \(bu 2 \fBlocation\fP \-\- the location of the VM being requested. .IP \(bu 2 \fBkwargs\fP \-\- options available as the VM is being requested: \fBAction\fP, \fBImageId\fP, \fBInstanceType\fP, \fBKeyName\fP, \fBMaxCount\fP, \fBMinCount\fP, \fBSecurityGroup.1\fP .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt/cloud//querying Fired when salt\-cloud queries data for a new instance. .INDENT 7.0 .TP .B Variables .INDENT 7.0 .IP \(bu 2 \fBevent\fP \-\- description of the event. .IP \(bu 2 \fBinstance_id\fP \-\- the ID of the new VM. .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt/cloud//tagging Fired when salt\-cloud tags a new instance. .INDENT 7.0 .TP .B Variables .INDENT 7.0 .IP \(bu 2 \fBevent\fP \-\- description of the event. .IP \(bu 2 \fBtags\fP \-\- tags being set on the new instance. .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt/cloud//waiting_for_ssh Fired while the salt\-cloud deploy process is waiting for ssh to become available on the new instance. .INDENT 7.0 .TP .B Variables .INDENT 7.0 .IP \(bu 2 \fBevent\fP \-\- description of the event. .IP \(bu 2 \fBip_address\fP \-\- IP address of the new instance. .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt/cloud//deploy_script Fired once the deploy script is finished. .INDENT 7.0 .TP .B Variables \fBevent\fP \-\- description of the event. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt/cloud//created Fired once the new instance has been fully created. .INDENT 7.0 .TP .B Variables .INDENT 7.0 .IP \(bu 2 \fBname\fP \-\- the name of the VM being created. .IP \(bu 2 \fBevent\fP \-\- description of the event. .IP \(bu 2 \fBinstance_id\fP \-\- the ID of the new instance. .IP \(bu 2 \fBprovider\fP \-\- the cloud provider of the VM being created. .IP \(bu 2 \fBprofile\fP \-\- the cloud profile for the VM being created. .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt/cloud//destroying Fired when salt\-cloud requests the destruction of an instance. .INDENT 7.0 .TP .B Variables .INDENT 7.0 .IP \(bu 2 \fBname\fP \-\- the name of the VM being created. .IP \(bu 2 \fBevent\fP \-\- description of the event. .IP \(bu 2 \fBinstance_id\fP \-\- the ID of the new instance. .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt/cloud//destroyed Fired when an instance has been destroyed. .INDENT 7.0 .TP .B Variables .INDENT 7.0 .IP \(bu 2 \fBname\fP \-\- the name of the VM being created. .IP \(bu 2 \fBevent\fP \-\- description of the event. .IP \(bu 2 \fBinstance_id\fP \-\- the ID of the new instance. .UNINDENT .UNINDENT .UNINDENT .SS Listening for Events .sp Salt\(aqs Event Bus is used heavily within Salt and it is also written to integrate heavily with existing tooling and scripts. There is a variety of ways to consume it. .SS From the CLI .sp The quickest way to watch the event bus is by calling the \fBstate.event runner\fP: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt\-run state.event pretty=True .ft P .fi .UNINDENT .UNINDENT .sp That runner is designed to interact with the event bus from external tools and shell scripts. See the documentation for more examples. .SS Remotely via the REST API .sp Salt\(aqs event bus can be consumed \fBsalt.netapi.rest_cherrypy.app.Events\fP as an HTTP stream from external tools or services. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C curl \-SsNk https://salt\-api.example.com:8000/events?token=05A3 .ft P .fi .UNINDENT .UNINDENT .SS From Python .sp Python scripts can access the event bus only as the same system user that Salt is running as. .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.config import salt.utils.event opts = salt.config.client_config(\(aq/etc/salt/master\(aq) event = salt.utils.event.get_event( \(aqmaster\(aq, sock_dir=opts[\(aqsock_dir\(aq], transport=opts[\(aqtransport\(aq], opts=opts) data = event.get_event() .ft P .fi .UNINDENT .UNINDENT .sp Events will also use a "tag". Tags allow for events to be filtered by prefix. By default all events will be returned. If only authentication events are desired, then pass the tag "salt/auth". .sp The \fBget_event\fP method has a default poll time assigned of 5 seconds. To change this time set the "wait" option. .sp The following 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 data = event.get_event(wait=10, tag=\(aqsalt/auth\(aq) .ft P .fi .UNINDENT .UNINDENT .sp To retrieve the tag as well as the event data, pass \fBfull=True\fP: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C evdata = event.get_event(wait=10, tag=\(aqsalt/job\(aq, full=True) tag, data = evdata[\(aqtag\(aq], evdata[\(aqdata\(aq] .ft P .fi .UNINDENT .UNINDENT .sp Instead of looking for a single event, the \fBiter_events\fP method can be used to make a generator which will continually yield salt events. .sp The iter_events method also accepts a tag but not a wait time: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C for data in event.iter_events(tag=\(aqsalt/auth\(aq): print(data) .ft P .fi .UNINDENT .UNINDENT .sp And finally event tags can be globbed, such as they can be in the Reactor, using the fnmatch library. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C import fnmatch import salt.config import salt.utils.event opts = salt.config.client_config(\(aq/etc/salt/master\(aq) sevent = salt.utils.event.get_event( \(aqmaster\(aq, sock_dir=opts[\(aqsock_dir\(aq], transport=opts[\(aqtransport\(aq], opts=opts) while True: ret = sevent.get_event(full=True) if ret is None: continue if fnmatch.fnmatch(ret[\(aqtag\(aq], \(aqsalt/job/*/ret/*\(aq): do_something_with_job_return(ret[\(aqdata\(aq]) .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. .sp To fire a local event from the minion on the command line call the \fBevent.fire\fP execution function: .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 up to the master from the minion call the \fBevent.send\fP execution function. Remember YAML can be used at the CLI in function arguments: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt\-call event.send \(aqmyco/mytag/success\(aq \(aq{success: True, message: "It works!"}\(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 # Job on minion import salt.utils.event event = salt.utils.event.MinionEvent(**__opts__) for evdata in event.iter_events(tag=\(aqcustomtag/\(aq): return evdata # do your processing here... .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt minionname event.fire \(aq{"data": "message for the minion"}\(aq \(aqcustomtag/african/unladen\(aq .ft P .fi .UNINDENT .UNINDENT .SS Firing Events from Python .SS From Salt execution modules .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. This is easily done using the normal cross\-calling syntax: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C # /srv/salt/_modules/my_custom_module.py def do_something(): \(aq\(aq\(aq Do something and fire an event to the master when finished CLI Example:: salt \(aq*\(aq my_custom_module:do_something \(aq\(aq\(aq # do something! __salt__[\(aqevent.send\(aq](\(aqmyco/my_custom_module/finished\(aq, { \(aqfinished\(aq: True, \(aqmessage\(aq: "The something is finished!", }) .ft P .fi .UNINDENT .UNINDENT .SS From Custom Python Scripts .sp Firing events from custom Python code is quite simple and mirrors how it is done at the CLI: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C import salt.client caller = salt.client.Caller() caller.sminion.functions[\(aqevent.send\(aq]( \(aqmyco/myevent/success\(aq, { \(aqsuccess\(aq: True, \(aqmessage\(aq: "It works!", } ) .ft P .fi .UNINDENT .UNINDENT .SS Beacons .sp Beacons let you use the Salt event system to monitor non\-Salt processes. The beacon system allows the minion to hook into a variety of system processes and continually monitor these processes. When monitored activity occurs in a system process, an event is sent on the Salt event bus that can be used to trigger a reactor\&. .sp Salt beacons can currently monitor and send Salt events for many system activities, including: .INDENT 0.0 .IP \(bu 2 file system changes .IP \(bu 2 system load .IP \(bu 2 service status .IP \(bu 2 shell activity, such as user login .IP \(bu 2 network and disk usage .UNINDENT .sp See beacon modules for a current list. .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 Salt beacons are an event generation mechanism. Beacons leverage the Salt reactor system to make changes when beacon events occur. .UNINDENT .UNINDENT .SS Configuring Beacons .sp Salt beacons do not require any changes to the system components that are being monitored, everything is configured using Salt. .sp Beacons are typically enabled by placing a \fBbeacons:\fP top level block in \fB/etc/salt/minion\fP or any file in \fB/etc/salt/minion.d/\fP such as \fB/etc/salt/minion.d/beacons.conf\fP: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C beacons: inotify: /etc/important_file: {} /opt: {} .ft P .fi .UNINDENT .UNINDENT .sp The beacon system, like many others in Salt, can also be configured via the minion pillar, grains, or local config file. .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 The \fIinotify\fP beacon only works on OSes that have \fIinotify\fP kernel support. Currently this excludes FreeBSD, macOS, and Windows. .UNINDENT .UNINDENT .SS Beacon Monitoring Interval .sp Beacons monitor on a 1\-second interval by default. To set a different interval, provide an \fBinterval\fP argument to a beacon. The following beacons run on 5\- and 10\-second intervals: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C beacons: inotify: /etc/important_file: {} /opt: {} interval: 5 disable_during_state_run: True load: 1m: \- 0.0 \- 2.0 5m: \- 0.0 \- 1.5 15m: \- 0.1 \- 1.0 interval: 10 .ft P .fi .UNINDENT .UNINDENT .SS Avoiding Event Loops .sp It is important to carefully consider the possibility of creating a loop between a reactor and a beacon. For example, one might set up a beacon which monitors whether a file is read which in turn fires a reactor to run a state which in turn reads the file and re\-fires the beacon. .sp To avoid these types of scenarios, the \fBdisable_during_state_run\fP argument may be set. If a state run is in progress, the beacon will not be run on its regular interval until the minion detects that the state run has completed, at which point the normal beacon interval will resume. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C beacons: inotify: /etc/important_file: {} disable_during_state_run: True .ft P .fi .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 For beacon writers: If you need extra stuff to happen, like closing file handles for the \fBdisable_during_state_run\fP to actually work, you can add a \fIclose()\fP function to the beacon to run those extra things. See the \fIinotify\fP beacon. .UNINDENT .UNINDENT .SS Beacon Example .sp This example demonstrates configuring the \fBinotify\fP beacon to monitor a file for changes, and then restores the file to its original contents if a change was made. .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 The inotify beacon requires Pyinotify on the minion, install it using \fBsalt myminion pkg.install python\-inotify\fP\&. .UNINDENT .UNINDENT .SS Create Watched File .sp Create the file named \fB/etc/important_file\fP and add some simple content: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C important_config: True .ft P .fi .UNINDENT .UNINDENT .SS Add Beacon Configs to Minion .sp On the Salt minion, add the following configuration to \fB/etc/salt/minion.d/beacons.conf\fP: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C beacons: inotify: /etc/important_file: mask: \- modify disable_during_state_run: True .ft P .fi .UNINDENT .UNINDENT .sp Save the configuration file and restart the minion service. The beacon is now set up to notify salt upon modifications made to the file. .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 The \fBdisable_during_state_run: True\fP parameter \fI\%prevents\fP the inotify beacon from generating reactor events due to salt itself modifying the file. .UNINDENT .UNINDENT .SS View Events on the Master .sp On your Salt master, start the event runner using the following command: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt\-run state.event pretty=true .ft P .fi .UNINDENT .UNINDENT .sp This runner displays events as they are received by the master on the Salt event bus. To test the beacon you set up in the previous section, make and save a modification to \fB/etc/important_file\fP\&. You\(aqll see an event similar to the following on the event bus: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt/beacon/larry/inotify//etc/important_file { "_stamp": "2015\-09\-09T15:59:37.972753", "data": { "change": "IN_IGNORED", "id": "larry", "path": "/etc/important_file" }, "tag": "salt/beacon/larry/inotify//etc/important_file" } .ft P .fi .UNINDENT .UNINDENT .sp This indicates that the event is being captured and sent correctly. Now you can create a reactor to take action when this event occurs. .SS Create a Reactor .sp This reactor reverts the file named \fB/etc/important_file\fP to the contents provided by salt each time it is modified. .SS Reactor SLS .sp On your Salt master, create a file named \fB/srv/reactor/revert.sls\fP\&. .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 If the \fB/srv/reactor\fP directory doesn\(aqt exist, create it. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C mkdir \-p /srv/reactor .ft P .fi .UNINDENT .UNINDENT .UNINDENT .UNINDENT .sp Add the following to \fB/srv/reactor/revert.sls\fP: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C revert\-file: local.state.apply: \- tgt: {{ data[\(aqdata\(aq][\(aqid\(aq] }} \- arg: \- maintain_important_file .ft P .fi .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 In addition to \fI\%setting\fP \fBdisable_during_state_run: True\fP for an inotify beacon whose reaction is to modify the watched file, it is important to ensure the state applied is also idempotent\&. .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 The expression \fB{{ data[\(aqdata\(aq][\(aqid] }}\fP is correct as it matches the event structure \fI\%shown above\fP\&. .UNINDENT .UNINDENT .SS State SLS .sp Create the state sls file referenced by the reactor sls file. This state file will be located at \fB/srv/salt/maintain_important_file.sls\fP\&. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C important_file: file.managed: \- name: /etc/important_file \- contents: | important_config: True .ft P .fi .UNINDENT .UNINDENT .SS Master Config .sp Configure the master to map the inotify beacon event to the \fBrevert\fP reaction in \fB/etc/salt/master.d/reactor.conf\fP: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C reactor: \- salt/beacon/*/inotify//etc/important_file: \- /srv/reactor/revert.sls .ft P .fi .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 You can have only one top level \fBreactor\fP section, so if one already exists, add this code to the existing section. See Understanding the Structure of Reactor Formulas to learn more about reactor SLS syntax. .UNINDENT .UNINDENT .SS Start the Salt Master in Debug Mode .sp To help with troubleshooting, start the Salt master in debug mode: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C service salt\-master stop salt\-master \-l debug .ft P .fi .UNINDENT .UNINDENT .sp When debug logging is enabled, event and reactor data are displayed so you can discover syntax and other issues. .SS Trigger the Reactor .sp On your minion, make and save another change to \fB/etc/important_file\fP\&. On the Salt master, you\(aqll see debug messages that indicate the event was received and the \fBstate.apply\fP job was sent. When you inspect the file on the minion, you\(aqll see that the file contents have been restored to \fBimportant_config: True\fP\&. .sp All beacons are configured using a similar process of enabling the beacon, writing a reactor SLS (and state SLS if needed), and mapping a beacon event to the reactor SLS. .SS Writing Beacon Plugins .sp Beacon plugins use the standard Salt loader system, meaning that many of the constructs from other plugin systems holds true, such as the \fB__virtual__\fP function. .sp The important function in the Beacon Plugin is the \fBbeacon\fP function. When the beacon is configured to run, this function will be executed repeatedly by the minion. The \fBbeacon\fP function therefore cannot block and should be as lightweight as possible. The \fBbeacon\fP also must return a list of dicts, each dict in the list will be translated into an event on the master. .sp Beacons may also choose to implement a \fB__validate__\fP function which takes the beacon configuration as an argument and ensures that it is valid prior to continuing. This function is called automatically by the Salt loader when a beacon is loaded. .sp Please see the \fBinotify\fP beacon as an example. .SS The \fIbeacon\fP Function .sp The beacons system will look for a function named \fIbeacon\fP in the module. If this function is not present then the beacon will not be fired. This function is called on a regular basis and defaults to being called on every iteration of the minion, which can be tens to hundreds of times a second. This means that the \fIbeacon\fP function cannot block and should not be CPU or IO intensive. .sp The beacon function will be passed in the configuration for the executed beacon. This makes it easy to establish a flexible configuration for each called beacon. This is also the preferred way to ingest the beacon\(aqs configuration as it allows for the configuration to be dynamically updated while the minion is running by configuring the beacon in the minion\(aqs pillar. .SS The Beacon Return .sp The information returned from the beacon is expected to follow a predefined structure. The returned value needs to be a list of dictionaries (standard python dictionaries are preferred, no ordered dicts are needed). .sp The dictionaries represent individual events to be fired on the minion and master event buses. Each dict is a single event. The dict can contain any arbitrary keys but the \(aqtag\(aq key will be extracted and added to the tag of the fired event. .sp The return data structure would look something like this: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C [{\(aqchanges\(aq: [\(aq/foo/bar\(aq], \(aqtag\(aq: \(aqfoo\(aq}, {\(aqchanges\(aq: [\(aq/foo/baz\(aq], \(aqtag\(aq: \(aqbar\(aq}] .ft P .fi .UNINDENT .UNINDENT .SS Calling Execution Modules .sp Execution modules are still the preferred location for all work and system interaction to happen in Salt. For this reason the \fI__salt__\fP variable is available inside the beacon. .sp Please be careful when calling functions in \fI__salt__\fP, while this is the preferred means of executing complicated routines in Salt not all of the execution modules have been written with beacons in mind. Watch out for execution modules that may be CPU intense or IO bound. Please feel free to add new execution modules and functions to back specific beacons. .SS Distributing Custom Beacons .sp Custom beacons can be distributed to minions using \fBsaltutil\fP, see Dynamic Module Distribution\&. .SS Reactor System .sp Salt\(aqs Reactor system gives Salt the ability to trigger actions in response to an event. It is a simple interface to watching Salt\(aqs event bus for event tags that match a given pattern and then running one or more commands in response. .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 New in version 2014.7.0: Added Reactor support for \fBsalt://\fP file paths. .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 match tags \- /srv/reactor/destroy/*.sls # Globs can be used to match file names \- \(aqmyco/custom/event/tag\(aq: # React to custom event tags \- salt://reactor/mycustom.sls # Reactor files can come from the salt fileserver .ft P .fi .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 In the above example, \fBsalt://reactor/mycustom.sls\fP refers to the \fBbase\fP environment. To pull this file from a different environment, use the querystring syntax (e.g. \fBsalt://reactor/mycustom.sls?saltenv=reactor\fP). .UNINDENT .UNINDENT .sp Reactor sls files are similar to state and pillar sls files. They are by default yaml + Jinja templates and are passed familiar context variables. .sp They differ because of the addition 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: local.state.apply: \- 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.apply\fP\&. Similarly, a runner can be called: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C {% if data[\(aqdata\(aq][\(aqorchestrate\(aq] == \(aqrefresh\(aq %} orchestrate_run: runner.state.orchestrate {% endif %} .ft P .fi .UNINDENT .UNINDENT .sp This example will execute the state.orchestrate runner and initiate an orchestrate execution. .SS The Goal of Writing Reactor SLS Files .sp Reactor SLS files share the familiar syntax from Salt States but there are important differences. The goal of a Reactor file is to process a Salt event as quickly as possible and then to optionally start a \fBnew\fP process in response. .INDENT 0.0 .IP 1. 3 The Salt Reactor watches Salt\(aqs event bus for new events. .IP 2. 3 The event tag is matched against the list of event tags under the \fBreactor\fP section in the Salt Master config. .IP 3. 3 The SLS files for any matches are Rendered into a data structure that represents one or more function calls. .IP 4. 3 That data structure is given to a pool of worker threads for execution. .UNINDENT .sp Matching and rendering Reactor SLS files is done sequentially in a single process. Complex Jinja that calls out to slow Execution or Runner modules slows down the rendering and causes other reactions to pile up behind the current one. The worker pool is designed to handle complex and long\-running processes such as Salt Orchestrate. .sp tl;dr: Rendering Reactor SLS files MUST be simple and quick. The new process started by the worker threads can be long\-running. .SS Jinja Context .sp Reactor files only have access to a minimal Jinja context. \fBgrains\fP and \fBpillar\fP are not available. The \fBsalt\fP object is available for calling Runner and Execution modules but it should be used sparingly and only for quick tasks for the reasons mentioned above. .SS Advanced State System Capabilities .sp Reactor SLS files, by design, do not support Requisites, ordering, \fBonlyif\fP/\fBunless\fP conditionals and most other powerful constructs from Salt\(aqs State system. .sp Complex Master\-side operations are best performed by Salt\(aqs Orchestrate system so using the Reactor to kick off an Orchestrate run is a very common pairing. .sp For example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C # /etc/salt/master.d/reactor.conf # A custom event containing: {"foo": "Foo!", "bar: "bar*", "baz": "Baz!"} reactor: \- myco/custom/event: \- /srv/reactor/some_event.sls .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C # /srv/reactor/some_event.sls invoke_orchestrate_file: runner.state.orchestrate: \- mods: orch.do_complex_thing \- pillar: event_tag: {{ tag }} event_data: {{ data | json() }} .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C # /srv/salt/orch/do_complex_thing.sls {% set tag = salt.pillar.get(\(aqevent_tag\(aq) %} {% set data = salt.pillar.get(\(aqevent_data\(aq) %} # Pass data from the event to a custom runner function. # The function expects a \(aqfoo\(aq argument. do_first_thing: salt.runner: \- name: custom_runner.custom_function \- foo: {{ data.foo }} # Wait for the runner to finish then send an execution to minions. # Forward some data from the event down to the minion\(aqs state run. do_second_thing: salt.state: \- tgt: {{ data.bar }} \- sls: \- do_thing_on_minion \- pillar: baz: {{ data.baz }} \- require: \- salt: do_first_thing .ft P .fi .UNINDENT .UNINDENT .SS Beacons and Reactors .sp An event initiated by a beacon, when it arrives at the master will be wrapped inside a second event, such that the data object containing the beacon information will be \fBdata[\(aqdata\(aq]\fP, rather than \fBdata\fP\&. .sp For example, to access the \fBid\fP field of the beacon event in a reactor file, you will need to reference \fB{{ data[\(aqdata\(aq][\(aqid\(aq] }}\fP rather than \fB{{ data[\(aqid\(aq] }}\fP as for events initiated directly on the event bus. .sp See the beacon documentation for examples. .SS Fire an event .sp To fire an event from a minion call \fBevent.send\fP .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt\-call event.send \(aqfoo\(aq \(aq{orchestrate: refresh}\(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][\(aqorchestrate\(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 The best way to see exactly what events are fired and what data is available in each event is to use the \fBstate.event runner\fP\&. .sp \fBSEE ALSO:\fP .INDENT 0.0 .INDENT 3.5 Common Salt Events .UNINDENT .UNINDENT .sp Example usage: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt\-run state.event pretty=True .ft P .fi .UNINDENT .UNINDENT .sp Example output: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt/job/20150213001905721678/new { "_stamp": "2015\-02\-13T00:19:05.724583", "arg": [], "fun": "test.ping", "jid": "20150213001905721678", "minions": [ "jerry" ], "tgt": "*", "tgt_type": "glob", "user": "root" } salt/job/20150213001910749506/ret/jerry { "_stamp": "2015\-02\-13T00:19:11.136730", "cmd": "_return", "fun": "saltutil.find_job", "fun_args": [ "20150213001905721678" ], "id": "jerry", "jid": "20150213001910749506", "retcode": 0, "return": {}, "success": true } .ft P .fi .UNINDENT .UNINDENT .SS Debugging the Reactor .sp The best window into the Reactor is to run the master in the foreground with debug logging enabled. The output will include when the master sees the event, what the master does in response to that event, and it will also include the rendered SLS file (or any errors generated while rendering the SLS file). .INDENT 0.0 .IP 1. 3 Stop the master. .IP 2. 3 Start the master manually: .INDENT 3.0 .INDENT 3.5 .sp .nf .ft C salt\-master \-l debug .ft P .fi .UNINDENT .UNINDENT .IP 3. 3 Look for log entries in the form: .INDENT 3.0 .INDENT 3.5 .sp .nf .ft C [DEBUG ] Gathering reactors for tag foo/bar [DEBUG ] Compiling reactions for tag foo/bar [DEBUG ] Rendered data from file: /path/to/the/reactor_file.sls: <... Rendered output appears here. ...> .ft P .fi .UNINDENT .UNINDENT .sp The rendered output is the result of the Jinja parsing and is a good way to view the result of referencing Jinja variables. If the result is empty then Jinja produced an empty result and the Reactor will ignore it. .UNINDENT .SS Understanding the Structure of Reactor Formulas .sp \fBI.e., when to use \(gaarg\(ga and \(gakwarg\(ga and when to specify the function arguments directly.\fP .sp While the reactor system uses the same basic data structure as the state system, the functions that will be called using that data structure are different functions than are called via Salt\(aqs state system. The Reactor can call Runner modules using the \fIrunner\fP prefix, Wheel modules using the \fIwheel\fP prefix, and can also cause minions to run Execution modules using the \fIlocal\fP prefix. .sp Changed in version 2014.7.0: The \fBcmd\fP prefix was renamed to \fBlocal\fP for consistency with other parts of Salt. A backward\-compatible alias was added for \fBcmd\fP\&. .sp The Reactor runs on the master and calls functions that exist on the master. In the case of Runner and Wheel functions the Reactor can just call those functions directly since they exist on the master and are run on the master. .sp In the case of functions that exist on minions and are run on minions, the Reactor still needs to call a function on the master in order to send the necessary data to the minion so the minion can execute that function. .sp The Reactor calls functions exposed in Salt\(aqs Python API documentation\&. and thus the structure of Reactor files very transparently reflects the function signatures of those functions. .SS Calling Execution modules on Minions .sp The Reactor sends commands down to minions in the exact same way Salt\(aqs CLI interface does. It calls a function locally on the master that sends the name of the function as well as a list of any arguments and a dictionary of any keyword arguments that the minion should use to execute that function. .sp Specifically, the Reactor calls the async version of \fBthis function\fP\&. You can see that function has \(aqarg\(aq and \(aqkwarg\(aq parameters which are both values that are sent down to the minion. .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 \fBlocal\fP to use the \fBLocalClient\fP subsystem. The result is, to execute a remote command, a reactor formula would look like this: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C clean_tmp: local.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: local.cmd.run: \- tgt: \(aqos:Ubuntu\(aq \- expr_form: grain \- arg: \- rm \-rf /tmp/* clean_tmp: local.cmd.run: \- tgt: \(aqG@roles:hbase_master\(aq \- expr_form: compound \- arg: \- rm \-rf /tmp/* .ft P .fi .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 An easy mistake to make here is to use \fBtgt_type\fP instead of \fBexpr_form\fP, since the job cache and events all refer to the targeting method as \fBtgt_type\fP\&. As of the Nitrogen release of Salt, \fBexpr_form\fP will be deprecated in favor of using \fBtgt_type\fP, to help with this confusion. .UNINDENT .UNINDENT .sp Any other parameters in the \fBLocalClient().cmd()\fP method can be specified as well. .SS Executing Reactors from the Minion .sp The minion can be setup to use the Reactor via a reactor engine. This just sets up and listens to the minions event bus, instead of to the masters. .sp The biggest difference is that you have to use the caller method on the Reactor, which is the equivalent of salt\-call, to run your commands. .sp Reactor Engine setup .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C clean_tmp: caller.cmd.run: \- arg: \- rm \-rf /tmp/* .ft P .fi .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 Masterless Minions use this Reactor .sp This is the only way to run the Reactor if you use masterless minions. .UNINDENT .UNINDENT .SS Calling Runner modules and Wheel modules .sp Calling Runner modules and Wheel modules from the Reactor uses a more direct syntax since the function is being executed locally instead of sending a command to a remote system to be executed there. There are no \(aqarg\(aq or \(aqkwarg\(aq parameters (unless the Runner function or Wheel function accepts a parameter with either of those names.) .sp For example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C clear_the_grains_cache_for_all_minions: runner.cache.clear_grains .ft P .fi .UNINDENT .UNINDENT .sp If the \fBthe runner takes arguments\fP then they must be specified as keyword arguments. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C spin_up_more_web_machines: runner.cloud.profile: \- prof: centos_6 \- instances: \- web11 # These VM names would be generated via Jinja in a \- web12 # real\-world example. .ft P .fi .UNINDENT .UNINDENT .sp To determine the proper names for the arguments, check the documentation or source code for the runner function you wish to call. .SS Passing event data to Minions or Orchestrate as Pillar .sp An interesting trick to pass data from the Reactor script to \fBstate.apply\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.apply\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 \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: local.state.apply: \- tgt: \(aqhaproxy*\(aq \- arg: \- haproxy.refresh_pool \- kwarg: pillar: new_minion: {{ data[\(aqid\(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.apply haproxy.refresh_pool \(aqpillar={new_minion: minionid}\(aq .ft P .fi .UNINDENT .UNINDENT .sp This works with Orchestrate files as well: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C call_some_orchestrate_file: runner.state.orchestrate: \- mods: some_orchestrate_file \- pillar: stuff: things .ft P .fi .UNINDENT .UNINDENT .sp Which is equivalent to the following command at the CLI: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt\-run state.orchestrate some_orchestrate_file pillar=\(aq{stuff: things}\(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 Salt Mine\&. 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 \fBstate.apply\fP executed. On top of this, 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 every ten seconds by default. .sp \fB/srv/reactor/auth\-pending.sls\fP: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C {# Ink server failed 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: local.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.apply. #} highstate_run: local.state.apply: \- tgt: {{ data[\(aqid\(aq] }} \- ret: smtp .ft P .fi .UNINDENT .UNINDENT .sp The above will also return the highstate result data using the \fIsmtp_return\fP returner (use virtualname like when using from the command line with \fI\-\-return\fP). The returner needs to be configured on the minion for this to work. See \fBsalt.returners.smtp_return\fP documentation for that. .SS Syncing Custom Types on Minion Start .sp Salt will sync all custom types (by running a \fBsaltutil.sync_all\fP) on every highstate\&. However, there is a chicken\-and\-egg issue where, on the initial highstate, a minion will not yet have these custom types synced when the top file is first compiled. This can be worked around with a simple reactor which watches for \fBminion_start\fP events, which each minion fires when it first starts up and connects to the master. .sp On the master, create \fB/srv/reactor/sync_grains.sls\fP with the following contents: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C sync_grains: local.saltutil.sync_grains: \- tgt: {{ data[\(aqid\(aq] }} .ft P .fi .UNINDENT .UNINDENT .sp And in the master config file, add the following reactor configuration: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C reactor: \- \(aqminion_start\(aq: \- /srv/reactor/sync_grains.sls .ft P .fi .UNINDENT .UNINDENT .sp This will cause the master to instruct each minion to sync its custom grains when it starts, making these grains available when the initial highstate is executed. .sp Other types can be synced by replacing \fBlocal.saltutil.sync_grains\fP with \fBlocal.saltutil.sync_modules\fP, \fBlocal.saltutil.sync_all\fP, or whatever else suits the intended use case. .SH ORCHESTRATION .SS Orchestrate Runner .sp Orchestration is accomplished in salt primarily through the \fI\%Orchestrate Runner\fP\&. Added in version 0.17.0, this Salt Runner can use the full suite of requisites available in states, and can also execute states/functions using salt\-ssh. .SS The Orchestrate Runner .sp New in version 0.17.0. .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 Orchestrate Deprecates OverState .sp The Orchestrate Runner (originally called the state.sls runner) offers all the functionality of the OverState, but with some advantages: .INDENT 0.0 .IP \(bu 2 All requisites available in states can be used. .IP \(bu 2 The states/functions will also work on salt\-ssh minions. .UNINDENT .sp The Orchestrate Runner was added with the intent to eventually deprecate the OverState system, however the OverState will still be maintained until Salt 2015.8.0. .UNINDENT .UNINDENT .sp The orchestrate runner generalizes the Salt state system to a Salt master context. Whereas the \fBstate.sls\fP, \fBstate.highstate\fP, et al functions are concurrently and independently executed on each Salt minion, the \fBstate.orchestrate\fP runner is executed on the master, giving it a master\-level view and control over requisites, such as state ordering and conditionals. This allows for inter minion requisites, like ordering the application of states on different minions that must not happen simultaneously, or for halting the state run on all minions if a minion fails one of its states. .sp If you want to setup a load balancer in front of a cluster of web servers, for example, you can ensure the load balancer is setup before the web servers or stop the state run altogether if one of the minions does not set up correctly. .sp The \fBstate.sls\fP, \fBstate.highstate\fP, et al functions allow you to statefully manage each minion and the \fBstate.orchestrate\fP runner allows you to statefully manage your entire infrastructure. .SS Executing the Orchestrate Runner .sp The Orchestrate Runner command format is the same as for the \fBstate.sls\fP function, except that since it is a runner, it is executed with \fBsalt\-run\fP rather than \fBsalt\fP\&. Assuming you have a state.sls file called \fB/srv/salt/orch/webserver.sls\fP the following command run on the master will apply the states defined in that file. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt\-run state.orchestrate orch.webserver .ft P .fi .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 \fBstate.orch\fP is a synonym for \fBstate.orchestrate\fP .UNINDENT .UNINDENT .sp Changed in version 2014.1.1: The runner function was renamed to \fBstate.orchestrate\fP to avoid confusion with the \fBstate.sls\fP execution function. In versions 0.17.0 through 2014.1.0, \fBstate.sls\fP must be used. .SS Masterless Orchestration .sp New in version 2016.11.0. .sp To support salt orchestration on masterless minions, the Orchestrate Runner is available as an execution module. The syntax for masterless orchestration is exactly the same, but it uses the \fBsalt\-call\fP command and the minion configuration must contain the \fBfile_mode: local\fP option. Alternatively, use \fBsalt\-call \-\-local\fP on the command line. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt\-call \-\-local state.orchestrate orch.webserver .ft P .fi .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 Masterless orchestration supports only the \fBsalt.state\fP command in an sls file; it does not (currently) support the \fBsalt.function\fP command. .UNINDENT .UNINDENT .SS Examples .SS Function .sp To execute a function, use \fBsalt.function\fP: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C # /srv/salt/orch/cleanfoo.sls cmd.run: salt.function: \- tgt: \(aq*\(aq \- arg: \- rm \-rf /tmp/foo .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt\-run state.orchestrate orch.cleanfoo .ft P .fi .UNINDENT .UNINDENT .sp If you omit the "name" argument, the ID of the state will be the default name, or in the case of \fBsalt.function\fP, the execution module function to run. You can specify the "name" argument to avoid conflicting IDs: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C copy_some_file: salt.function: \- name: file.copy \- tgt: \(aq*\(aq \- arg: \- /path/to/file \- /tmp/copy_of_file \- kwarg: remove_existing: true .ft P .fi .UNINDENT .UNINDENT .SS State .sp To execute a state, use \fBsalt.state\fP\&. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C # /srv/salt/orch/webserver.sls install_nginx: salt.state: \- tgt: \(aqweb*\(aq \- sls: \- nginx .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt\-run state.orchestrate orch.webserver .ft P .fi .UNINDENT .UNINDENT .SS Highstate .sp To run a highstate, set \fBhighstate: True\fP in your state config: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C # /srv/salt/orch/web_setup.sls webserver_setup: salt.state: \- tgt: \(aqweb*\(aq \- highstate: True .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt\-run state.orchestrate orch.web_setup .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 requisites, 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 requisites, as is the default in SLS files since 0.17.0. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C bootstrap_servers: salt.function: \- name: cmd.run \- 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 .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 Remember, salt\-run is always executed on the master. .UNINDENT .UNINDENT .SH SALT SSH .SS Getting Started .sp Salt SSH is very easy to use, simply set up a basic roster file of the systems to connect to and run \fBsalt\-ssh\fP commands in a similar way as standard \fBsalt\fP commands. .INDENT 0.0 .IP \(bu 2 Salt ssh is considered production ready in version 2014.7.0 .IP \(bu 2 Python is required on the remote system (unless using the \fB\-r\fP option to send raw ssh commands) .IP \(bu 2 On many systems, the \fBsalt\-ssh\fP executable will be in its own package, usually named \fBsalt\-ssh\fP .IP \(bu 2 The Salt SSH system does not supersede 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. .IP \(bu 2 At the moment fileserver operations must be wrapped to ensure that the relevant files are delivered with the \fBsalt\-ssh\fP commands. The state module is an exception, which compiles the state run on the master, and in the process finds all the references to \fBsalt://\fP paths and copies those files down in the same tarball as the state run. However, needed fileserver wrappers are still under development. .UNINDENT .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 SSH roster docs 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 Deploy ssh key for salt\-ssh .sp By default, salt\-ssh will generate key pairs for ssh, the default path will be /etc/salt/pki/master/ssh/salt\-ssh.rsa .sp You can use ssh\-copy\-id, (the OpenSSH key deployment tool) to deploy keys to your servers. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C ssh\-copy\-id \-i /etc/salt/pki/master/ssh/salt\-ssh.rsa.pub user@server.demo.com .ft P .fi .UNINDENT .UNINDENT .sp One could also create a simple shell script, named salt\-ssh\-copy\-id.sh as follows: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C #!/bin/bash if [ \-z $1 ]; then echo $0 user@host.com exit 0 fi ssh\-copy\-id \-i /etc/salt/pki/master/ssh/salt\-ssh.rsa.pub $1 .ft P .fi .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 Be certain to chmod +x salt\-ssh\-copy\-id.sh. .UNINDENT .UNINDENT .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C \&./salt\-ssh\-copy\-id.sh user@server1.host.com \&./salt\-ssh\-copy\-id.sh user@server2.host.com .ft P .fi .UNINDENT .UNINDENT .sp Once keys are successfully deployed, salt\-ssh can be used to control them. .sp Alternatively ssh agent forwarding can be used by setting the priv to agent\-forwarding. .SS Calling Salt SSH .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 \fBsalt\-ssh\fP on RHEL/CentOS 5 .sp The \fBsalt\-ssh\fP command requires at least python 2.6, which is not installed by default on RHEL/CentOS 5. An easy workaround in this situation is to use the \fB\-r\fP option to run a raw shell command that installs python26: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt\-ssh centos\-5\-minion \-r \(aqyum \-y install epel\-release ; yum \-y install python26\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .UNINDENT .sp The \fBsalt\-ssh\fP command can be easily executed in the same way 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. .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 By default, Grains are settable through \fBsalt\-ssh\fP\&. By default, these grains will \fInot\fP be persisted across reboots. .sp See the "thin_dir" setting in Roster documentation for more details. .UNINDENT .UNINDENT .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 Minion Config .sp New in version 2015.5.1. .sp Minion config options can be defined globally using the master configuration option \fBssh_minion_opts\fP\&. It can also be defined on a per\-minion basis with the \fBminion_opts\fP entry in the roster. .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 recommended 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\&. .SS Define CLI Options with Saltfile .sp If you are commonly passing in CLI options to \fBsalt\-ssh\fP, you can create a \fBSaltfile\fP to automatically use these options. This is common if you\(aqre managing several different salt projects on the same server. .sp So you can \fBcd\fP into a directory that has a \fBSaltfile\fP with the following YAML contents: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt\-ssh: config_dir: path/to/config/dir ssh_max_procs: 30 ssh_wipe: True .ft P .fi .UNINDENT .UNINDENT .sp Instead of having to call \fBsalt\-ssh \-\-config\-dir=path/to/config/dir \-\-max\-procs=30 \-\-wipe \e* test.ping\fP you can call \fBsalt\-ssh \e* test.ping\fP\&. .sp Boolean\-style options should be specified in their YAML representation. .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 The option keys specified must match the destination attributes for the options specified in the parser \fBsalt.utils.parsers.SaltSSHOptionParser\fP\&. For example, in the case of the \fB\-\-wipe\fP command line option, its \fBdest\fP is configured to be \fBssh_wipe\fP and thus this is what should be configured in the \fBSaltfile\fP\&. Using the names of flags for this option, being \fBwipe: True\fP or \fBw: True\fP, will not work. .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 For the \fISaltfile\fP to be automatically detected it needs to be named \fISaltfile\fP with a capital \fIS\fP and be readable by the user running salt\-ssh. .UNINDENT .UNINDENT .SS Debugging salt\-ssh .sp One common approach for debugging \fBsalt\-ssh\fP is to simply use the tarball that salt ships to the remote machine and call \fBsalt\-call\fP directly. .sp To determine the location of \fBsalt\-call\fP, simply run \fBsalt\-ssh\fP with the \fB\-ltrace\fP flag and look for a line containing the string, \fBSALT_ARGV\fP\&. This contains the \fBsalt\-call\fP command that \fBsalt\-ssh\fP attempted to execute. .sp It is recommended that one modify this command a bit by removing the \fB\-l quiet\fP, \fB\-\-metadata\fP and \fB\-\-output json\fP to get a better idea of what\(aqs going on on the target system. .SS Salt Rosters .sp Salt rosters are pluggable 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 \fBSEE ALSO:\fP .INDENT 0.0 .INDENT 3.5 all\-salt.roster .UNINDENT .UNINDENT .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 referred to as \fBtargets\fP\&. The \fBtargets\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 \fBtargets\fP data structure. .SS Targets Data .sp The information which can be stored in a roster \fBtarget\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 sudo_user: # Str: Set this to execute Salt as a sudo user other than root. # This user must be in the same system group as the remote user # that is used to login and is specified above. Alternatively, # the user must be a super\-user. tty: # Boolean: Set this option to True if sudo is also set to # True and requiretty is also set on the target system priv: # File path to ssh private key, defaults to salt\-ssh.rsa # The priv can also be set to agent\-forwarding to not specify # a key, but use ssh agent forwarding timeout: # Number of seconds to wait for response when establishing # an SSH connection minion_opts: # Dictionary of minion opts thin_dir: # The target system\(aqs storage directory for Salt # components. Defaults to /tmp/salt\-. cmd_umask: # umask to enforce for the salt\-call command. Should be in # octal (so for 0o077 in YAML you would do 0077, or 63) .ft P .fi .UNINDENT .UNINDENT .SS thin_dir .sp Salt needs to upload a standalone environment to the target system, and this defaults to /tmp/salt\-. This directory will be cleaned up per normal systems operation. .sp If you need a persistent Salt environment, for instance to set persistent grains, this value will need to be changed. .SH SALT CLOUD .SS Configuration .sp Salt Cloud provides a powerful interface to interact with cloud hosts. This interface is tightly integrated with Salt, and new virtual machines are automatically connected to your Salt master after creation. .sp Since Salt Cloud is designed to be an automated system, most configuration is done using the following YAML configuration files: .INDENT 0.0 .IP \(bu 2 \fB/etc/salt/cloud\fP: The main configuration file, contains global settings that apply to all cloud hosts. See Salt Cloud Configuration\&. .IP \(bu 2 \fB/etc/salt/cloud.providers.d/*.conf\fP: Contains settings that configure a specific cloud host, such as credentials, region settings, and so on. Since configuration varies significantly between each cloud host, a separate file should be created for each cloud host. In Salt Cloud, a provider is synonymous with a cloud host (Amazon EC2, Google Compute Engine, Rackspace, and so on). See \fI\%Provider Specifics\fP\&. .IP \(bu 2 \fB/etc/salt/cloud.profiles.d/*.conf\fP: Contains settings that define a specific VM type. A profile defines the systems specs and image, and any other settings that are specific to this VM type. Each specific VM type is called a profile, and multiple profiles can be defined in a profile file. Each profile references a parent provider that defines the cloud host in which the VM is created (the provider settings are in the provider configuration explained above). Based on your needs, you might define different profiles for web servers, database servers, and so on. See \fI\%VM Profiles\fP\&. .UNINDENT .SS Configuration Inheritance .sp Configuration settings are inherited in order from the cloud config => providers => profile. [image] .sp For example, if you wanted to use the same image for all virtual machines for a specific provider, the image name could be placed in the provider file. This value is inherited by all profiles that use that provider, but is overridden if a image name is defined in the profile. .sp Most configuration settings can be defined in any file, the main difference being how that setting is inherited. .SS QuickStart .sp The Salt Cloud Quickstart walks you through defining a provider, a VM profile, and shows you how to create virtual machines using Salt Cloud. .sp Note that if you installed Salt via \fI\%Salt Bootstrap\fP, it may not have automatically installed salt\-cloud for you. Use your distribution\(aqs package manager to install the \fBsalt\-cloud\fP package from the same repo that you used to install Salt. These repos will automatically be setup by Salt Bootstrap. .sp If there is no salt\-cloud package, install with \fBpip install salt\-cloud\fP\&. .SS Using Salt Cloud .SS \fBsalt\-cloud\fP .sp Provision virtual machines in the cloud with Salt .SS Synopsis .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-m /etc/salt/cloud.map salt\-cloud \-m /etc/salt/cloud.map NAME salt\-cloud \-m /etc/salt/cloud.map NAME1 NAME2 salt\-cloud \-p PROFILE NAME salt\-cloud \-p PROFILE NAME1 NAME2 NAME3 NAME4 NAME5 NAME6 .ft P .fi .UNINDENT .UNINDENT .SS Description .sp Salt Cloud is the system used to provision virtual machines on various public clouds via a cleanly controlled profile and mapping system. .SS Options .INDENT 0.0 .TP .B \-\-version Print the version of Salt that is running. .UNINDENT .INDENT 0.0 .TP .B \-\-versions\-report Show program\(aqs dependencies and version number, and then exit .UNINDENT .INDENT 0.0 .TP .B \-h, \-\-help Show the help message and exit .UNINDENT .INDENT 0.0 .TP .B \-c CONFIG_DIR, \-\-config\-dir=CONFIG_dir The location of the Salt configuration directory. This directory contains the configuration files for Salt master and minions. The default location on most systems is \fB/etc/salt\fP\&. .UNINDENT .SS Execution Options .INDENT 0.0 .TP .B \-L LOCATION, \-\-location=LOCATION Specify which region to connect to. .UNINDENT .INDENT 0.0 .TP .B \-a ACTION, \-\-action=ACTION Perform an action that may be specific to this cloud provider. This argument requires one or more instance names to be specified. .UNINDENT .INDENT 0.0 .TP .B \-f , \-\-function= Perform an function that may be specific to this cloud provider, that does not apply to an instance. This argument requires a provider to be specified (i.e.: nova). .UNINDENT .INDENT 0.0 .TP .B \-p PROFILE, \-\-profile=PROFILE Select a single profile to build the named cloud VMs from. The profile must be defined in the specified profiles file. .UNINDENT .INDENT 0.0 .TP .B \-m MAP, \-\-map=MAP Specify a map file to use. If used without any other options, this option will ensure that all of the mapped VMs are created. If the named VM already exists then it will be skipped. .UNINDENT .INDENT 0.0 .TP .B \-H, \-\-hard When specifying a map file, the default behavior is to ensure that all of the VMs specified in the map file are created. If the \-\-hard option is set, then any VMs that exist on configured cloud providers that are not specified in the map file will be destroyed. Be advised that this can be a destructive operation and should be used with care. .UNINDENT .INDENT 0.0 .TP .B \-d, \-\-destroy Pass in the name(s) of VMs to destroy, salt\-cloud will search the configured cloud providers for the specified names and destroy the VMs. Be advised that this is a destructive operation and should be used with care. Can be used in conjunction with the \-m option to specify a map of VMs to be deleted. .UNINDENT .INDENT 0.0 .TP .B \-P, \-\-parallel Normally when building many cloud VMs they are executed serially. The \-P option will run each cloud vm build in a separate process allowing for large groups of VMs to be build at once. .sp Be advised that some cloud provider\(aqs systems don\(aqt seem to be well suited for this influx of vm creation. When creating large groups of VMs watch the cloud provider carefully. .UNINDENT .INDENT 0.0 .TP .B \-u, \-\-update\-bootstrap Update salt\-bootstrap to the latest stable bootstrap release. .UNINDENT .INDENT 0.0 .TP .B \-y, \-\-assume\-yes Default yes in answer to all confirmation questions. .UNINDENT .INDENT 0.0 .TP .B \-k, \-\-keep\-tmp Do not remove files from /tmp/ after deploy.sh finishes. .UNINDENT .INDENT 0.0 .TP .B \-\-show\-deploy\-args Include the options used to deploy the minion in the data returned. .UNINDENT .INDENT 0.0 .TP .B \-\-script\-args=SCRIPT_ARGS Script arguments to be fed to the bootstrap script when deploying the VM. .UNINDENT .SS Query Options .INDENT 0.0 .TP .B \-Q, \-\-query Execute a query and return some information about the nodes running on configured cloud providers .UNINDENT .INDENT 0.0 .TP .B \-F, \-\-full\-query Execute a query and print out all available information about all cloud VMs. Can be used in conjunction with \-m to display only information about the specified map. .UNINDENT .INDENT 0.0 .TP .B \-S, \-\-select\-query Execute a query and print out selected information about all cloud VMs. Can be used in conjunction with \-m to display only information about the specified map. .UNINDENT .INDENT 0.0 .TP .B \-\-list\-providers Display a list of configured providers. .UNINDENT .INDENT 0.0 .TP .B \-\-list\-profiles New in version 2014.7.0. .sp Display a list of configured profiles. Pass in a cloud provider to view the provider\(aqs associated profiles, such as \fBdigital_ocean\fP, or pass in \fBall\fP to list all the configured profiles. .UNINDENT .SS Cloud Providers Listings .INDENT 0.0 .TP .B \-\-list\-locations=LIST_LOCATIONS Display a list of locations available in configured cloud providers. Pass the cloud provider that available locations are desired on, aka "linode", or pass "all" to list locations for all configured cloud providers .UNINDENT .INDENT 0.0 .TP .B \-\-list\-images=LIST_IMAGES Display a list of images available in configured cloud providers. Pass the cloud provider that available images are desired on, aka "linode", or pass "all" to list images for all configured cloud providers .UNINDENT .INDENT 0.0 .TP .B \-\-list\-sizes=LIST_SIZES Display a list of sizes available in configured cloud providers. Pass the cloud provider that available sizes are desired on, aka "AWS", or pass "all" to list sizes for all configured cloud providers .UNINDENT .SS Cloud Credentials .INDENT 0.0 .TP .B \-\-set\-password= Configure password for a cloud provider and save it to the keyring. PROVIDER can be specified with or without a driver, for example: "\-\-set\-password bob rackspace" or more specific "\-\-set\-password bob rackspace:openstack" DEPRECATED! .UNINDENT .SS Output Options .INDENT 0.0 .TP .B \-\-out Pass in an alternative outputter to display the return of data. This outputter can be any of the available outputters: .INDENT 7.0 .INDENT 3.5 \fBgrains\fP, \fBhighstate\fP, \fBjson\fP, \fBkey\fP, \fBoverstatestage\fP, \fBpprint\fP, \fBraw\fP, \fBtxt\fP, \fByaml\fP .UNINDENT .UNINDENT .sp Some outputters are formatted only for data returned from specific functions; for instance, the \fBgrains\fP outputter will not work for non\-grains data. .sp If an outputter is used that does not support the data passed into it, then Salt will fall back on the \fBpprint\fP outputter and display the return data using the Python \fBpprint\fP standard library module. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 If using \fB\-\-out=json\fP, you will probably want \fB\-\-static\fP as well. Without the static option, you will get a separate JSON string per minion which makes JSON output invalid as a whole. This is due to using an iterative outputter. So if you want to feed it to a JSON parser, use \fB\-\-static\fP as well. .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B \-\-out\-indent OUTPUT_INDENT, \-\-output\-indent OUTPUT_INDENT Print the output indented by the provided value in spaces. Negative values disable indentation. Only applicable in outputters that support indentation. .UNINDENT .INDENT 0.0 .TP .B \-\-out\-file=OUTPUT_FILE, \-\-output\-file=OUTPUT_FILE Write the output to the specified file. .UNINDENT .INDENT 0.0 .TP .B \-\-no\-color Disable all colored output .UNINDENT .INDENT 0.0 .TP .B \-\-force\-color Force colored output .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 When using colored output the color codes are as follows: .sp \fBgreen\fP denotes success, \fBred\fP denotes failure, \fBblue\fP denotes changes and success and \fByellow\fP denotes a expected future change in configuration. .UNINDENT .UNINDENT .UNINDENT .SS Examples .sp To create 4 VMs named web1, web2, db1, and db2 from specified profiles: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-p fedora_rackspace web1 web2 db1 db2 .ft P .fi .UNINDENT .UNINDENT .sp To read in a map file and create all VMs specified therein: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-m /path/to/cloud.map .ft P .fi .UNINDENT .UNINDENT .sp To read in a map file and create all VMs specified therein in parallel: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-m /path/to/cloud.map \-P .ft P .fi .UNINDENT .UNINDENT .sp To delete any VMs specified in the map file: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-m /path/to/cloud.map \-d .ft P .fi .UNINDENT .UNINDENT .sp To delete any VMs NOT specified in the map file: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-m /path/to/cloud.map \-H .ft P .fi .UNINDENT .UNINDENT .sp To display the status of all VMs specified in the map file: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-m /path/to/cloud.map \-Q .ft P .fi .UNINDENT .UNINDENT .SS See also .sp \fBsalt\-cloud(7)\fP \fBsalt(7)\fP \fBsalt\-master(1)\fP \fBsalt\-minion(1)\fP .SS Salt Cloud basic usage .sp Salt Cloud needs, at least, one configured Provider and Profile to be functional. .SS Creating a VM .sp To create a VM with salt cloud, use command: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-p name_of_vm .ft P .fi .UNINDENT .UNINDENT .sp Assuming there is a profile configured as following: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C fedora_rackspace: provider: my\-rackspace\-config image: Fedora 17 size: 256 server script: bootstrap\-salt .ft P .fi .UNINDENT .UNINDENT .sp Then, the command to create new VM named \fBfedora_http_01\fP is: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-p fedora_rackspace fedora_http_01 .ft P .fi .UNINDENT .UNINDENT .SS Destroying a VM .sp To destroy a created\-by\-salt\-cloud VM, use command: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-d name_of_vm .ft P .fi .UNINDENT .UNINDENT .sp For example, to delete the VM created on above example, use: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-d fedora_http_01 .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: my\-rackspace\-config image: Fedora 17 size: 256 server script: bootstrap\-salt .ft P .fi .UNINDENT .UNINDENT .sp It should be noted that the \fBscript\fP option defaults to \fBbootstrap\-salt\fP, and does not normally need to be specified. Further examples in this document will not show the \fBscript\fP option. .sp A few key pieces of information need to be declared and can change based on the cloud provider. A number of additional parameters can also be inserted: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C centos_rackspace: provider: my\-rackspace\-config image: CentOS 6.2 size: 1024 server 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: my\-ec2\-config image: ami\-e565ba8c size: t1.micro minion: cheese: edam ubuntu_ec2: provider: my\-ec2\-config image: ami\-7e2da54e size: t1.micro minion: cheese: edam ubuntu_rackspace: provider: my\-rackspace\-config image: Ubuntu 12.04 LTS size: 256 server minion: cheese: edam fedora_rackspace: provider: my\-rackspace\-config image: Fedora 17 size: 256 server minion: cheese: edam cent_linode: provider: my\-linode\-config image: CentOS 6.2 64bit size: Linode 512 cent_gogrid: provider: my\-gogrid\-config image: 12834 size: 512MB cent_joyent: provider: my\-joyent\-config image: centos\-7 size: g4\-highram\-16G .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. The map file is designed to be run once to create these more complex scenarios using salt\-cloud. .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 \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 Due to limitations in the GoGrid API, instances cannot be provisioned in parallel with the GoGrid driver. Map files will work with GoGrid, but the \fB\-P\fP argument should not be used on maps referencing GoGrid instances. .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 .sp \fBWARNING:\fP .INDENT 0.0 .INDENT 3.5 Specifying Nodes with Maps on the Command Line Specifying the name of a node or nodes with the maps options on the command line is \fInot\fP supported. This is especially important to remember when using \fB\-\-destroy\fP with maps; \fBsalt\-cloud\fP will ignore any arguments passed in which are not directly relevant to the map file. \fIWhen using \(ga\(ga\-\-destroy\(ga\(ga with a map, every node in the map file will be deleted!\fP Maps don\(aqt provide any useful information for destroying individual nodes, and should not be used to destroy a subset of a map. .UNINDENT .UNINDENT .SS Setting up New Salt Masters .sp Bootstrapping a new master in the map is as simple as: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C fedora_small: \- web1: make_master: True \- web2 \- web3 .ft P .fi .UNINDENT .UNINDENT .sp Notice that \fBALL\fP bootstrapped minions from the map will answer to the newly created salt\-master. .sp To make any of the bootstrapped minions answer to the bootstrapping salt\-master as opposed to the newly created salt\-master, as an example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C fedora_small: \- web1: make_master: True minion: master: local_master: True \- web2 \- web3 .ft P .fi .UNINDENT .UNINDENT .sp The above says the minion running on the newly created salt\-master responds to the local master, ie, the master used to bootstrap these VMs. .sp Another example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C fedora_small: \- web1: make_master: True \- web2 \- web3: minion: master: local_master: True .ft P .fi .UNINDENT .UNINDENT .sp The above example makes the \fBweb3\fP minion answer to the local master, not the newly created master. .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 linode: \- start \- stop .ft P .fi .UNINDENT .UNINDENT .sp Another useful reference for viewing more salt\-cloud actions is the :ref:Salt Cloud Feature Matrix .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 .sp There are three universal salt\-cloud functions that are extremely useful for gathering information about instances on a provider basis: .INDENT 0.0 .IP \(bu 2 \fBlist_nodes\fP: Returns some general information about the instances for the given provider. .IP \(bu 2 \fBlist_nodes_full\fP: Returns all information about the instances for the given provider. .IP \(bu 2 \fBlist_nodes_select\fP: Returns select information about the instances for the given provider. .UNINDENT .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C $ salt\-cloud \-f list_nodes linode $ salt\-cloud \-f list_nodes_full linode $ salt\-cloud \-f list_nodes_select linode .ft P .fi .UNINDENT .UNINDENT .sp Another useful reference for viewing salt\-cloud functions is the Salt Cloud Feature Matrix\&. .SS Core Configuration .SS Install Salt Cloud .sp Salt Cloud is now part of Salt proper. It was merged in as of Salt version 2014.1.0\&. .sp On Ubuntu, install Salt Cloud by using following command: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C sudo add\-apt\-repository ppa:saltstack/salt sudo apt\-get update sudo apt\-get install salt\-cloud .ft P .fi .UNINDENT .UNINDENT .sp If using Salt Cloud on macOS, \fBcurl\-ca\-bundle\fP must be installed. Presently, this package is not available via \fBbrew\fP, but it is available using MacPorts: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C sudo port install curl\-ca\-bundle .ft P .fi .UNINDENT .UNINDENT .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: Installing Salt for development\&. .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 Thread Pool Size .sp When salt cloud is operating in parallel mode via the \fB\-P\fP argument, you can control the thread pool size by specifying the \fBpool_size\fP parameter with a positive integer value. .sp By default, the thread pool size will be set to the number of VMs that salt cloud is operating on. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C pool_size: 10 .ft P .fi .UNINDENT .UNINDENT .SS Minion Configuration .sp The default minion configuration is set up in this file. Minions created by salt\-cloud derive their configuration from this file. Almost all parameters found in Configuring the Salt Minion can be used here. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C minion: master: saltmaster.example.com .ft P .fi .UNINDENT .UNINDENT .sp In particular, this is the location to specify the location of the salt master and its listening port, if the port is not set to the default. .sp Similar to most other settings, Minion configuration settings are inherited across configuration files. For example, the master setting might be contained in the main \fBcloud\fP configuration file as demonstrated above, but additional settings can be placed in the provider or profile: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C ec2\-web: size: t1.micro minion: environment: test startup_states: sls sls_list: \- web .ft P .fi .UNINDENT .UNINDENT .SS Cloud Configuration Syntax .sp The data specific to interacting with public clouds is set up here\&. .sp Cloud provider configuration settings can live in several places. The first is in \fB/etc/salt/cloud\fP: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C # /etc/salt/cloud providers: my\-aws\-migrated\-config: id: HJGRYCILJLKJYG key: \(aqkdjgfsgm;woormgl/aserigjksjdhasdfgn\(aq keyname: test securitygroup: quick\-start private_key: /root/test.pem driver: ec2 .ft P .fi .UNINDENT .UNINDENT .sp Cloud provider configuration data can also be housed in \fB/etc/salt/cloud.providers\fP or any file matching \fB/etc/salt/cloud.providers.d/*.conf\fP\&. All files in any of these locations will be parsed for cloud provider data. .sp Using the example configuration above: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C # /etc/salt/cloud.providers # or could be /etc/salt/cloud.providers.d/*.conf my\-aws\-config: id: HJGRYCILJLKJYG key: \(aqkdjgfsgm;woormgl/aserigjksjdhasdfgn\(aq keyname: test securitygroup: quick\-start private_key: /root/test.pem driver: ec2 .ft P .fi .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 Salt Cloud provider configurations within \fB/etc/cloud.provider.d/ should not specify the \(ga\(gaproviders\fP starting key. .UNINDENT .UNINDENT .sp It is also possible to have multiple cloud configuration blocks within the same alias block. 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 driver: ec2 \- user: example_user apikey: 123984bjjas87034 driver: rackspace .ft P .fi .UNINDENT .UNINDENT .sp However, using this configuration method requires a change with profile configuration blocks. The provider alias needs to have the provider key value appended as in the following example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C rhel_aws_dev: provider: production\-config:ec2 image: ami\-e565ba8c size: t1.micro rhel_aws_prod: provider: production\-config:ec2 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: ec2\fP\&. .sp This data interactions with the \fBsalt\-cloud\fP binary regarding its \fB\-\-list\-location\fP, \fB\-\-list\-images\fP, and \fB\-\-list\-sizes\fP which needs a cloud provider as an argument. The argument used should be the configured cloud provider alias. If the provider alias has multiple entries, \fB: \fP should be used. .sp To allow for a more extensible configuration, \fB\-\-providers\-config\fP, which defaults to \fB/etc/salt/cloud.providers\fP, was added to the cli parser. It allows for the providers\(aq configuration to be added on a per\-file basis. .SS Pillar Configuration .sp It is possible to configure cloud providers using pillars. This is only used when inside the cloud module. You can setup a variable called \fBcloud\fP that contains your profile and provider to pass that information to the cloud servers instead of having to copy the full configuration to every minion. In your pillar file, you would use something like this: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C cloud: ssh_key_name: saltstack ssh_key_file: /root/.ssh/id_rsa update_cachedir: True diff_cache_events: True change_password: True providers: my\-nova: identity_url: https://identity.api.rackspacecloud.com/v2.0/ compute_region: IAD user: myuser api_key: apikey tenant: 123456 driver: nova my\-openstack: identity_url: https://identity.api.rackspacecloud.com/v2.0/tokens user: user2 apikey: apikey2 tenant: 654321 compute_region: DFW driver: openstack compute_name: cloudServersOpenStack profiles: ubuntu\-nova: provider: my\-nova size: performance1\-8 image: bb02b1a3\-bc77\-4d17\-ab5b\-421d89850fca script_args: git develop ubuntu\-openstack: provider: my\-openstack size: performance1\-8 image: bb02b1a3\-bc77\-4d17\-ab5b\-421d89850fca script_args: git develop .ft P .fi .UNINDENT .UNINDENT .SS Cloud Configurations .SS Scaleway .sp To use Salt Cloud with Scaleway, you need to get an \fBaccess key\fP and an \fBAPI token\fP\&. \fBAPI tokens\fP are unique identifiers associated with your Scaleway account. To retrieve your \fBaccess key\fP and \fBAPI token\fP, log\-in to the Scaleway control panel, open the pull\-down menu on your account name and click on "My Credentials" link. .sp If you do not have \fBAPI token\fP you can create one by clicking the "Create New Token" button on the right corner. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C my\-scaleway\-config: access_key: 15cf404d\-4560\-41b1\-9a0c\-21c3d5c4ff1f token: a7347ec8\-5de1\-4024\-a5e3\-24b77d1ba91d driver: scaleway .ft P .fi .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 In the cloud profile that uses this provider configuration, the syntax for the \fBprovider\fP required field would be \fBprovider: my\-scaleway\-config\fP\&. .UNINDENT .UNINDENT .SS Rackspace .sp Rackspace cloud requires two configuration options; a \fBuser\fP and an \fBapikey\fP: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C my\-rackspace\-config: user: example_user apikey: 123984bjjas87034 driver: rackspace .ft P .fi .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 In the cloud profile that uses this provider configuration, the syntax for the \fBprovider\fP required field would be \fBprovider: my\-rackspace\-config\fP\&. .UNINDENT .UNINDENT .SS Amazon AWS .sp A number of configuration options are required for Amazon AWS including \fBid\fP, \fBkey\fP, \fBkeyname\fP, \fBsecuritygroup\fP, and \fBprivate_key\fP: .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 driver: ec2 my\-aws\-default: id: HJGRYCILJLKJYG key: \(aqkdjgfsgm;woormgl/aserigjksjdhasdfgn\(aq keyname: test securitygroup: default private_key: /root/test.pem driver: ec2 .ft P .fi .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 In the cloud profile that uses this provider configuration, the syntax for the \fBprovider\fP required field would be either \fBprovider: my\-aws\-quick\-start\fP or \fBprovider: my\-aws\-default\fP\&. .UNINDENT .UNINDENT .SS Linode .sp Linode requires a single API key, but the default root password also needs to be set: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C my\-linode\-config: apikey: asldkgfakl;sdfjsjaslfjaklsdjf;askldjfaaklsjdfhasldsadfghdkf password: F00barbaz ssh_pubkey: ssh\-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIKHEOLLbeXgaqRQT9NBAopVz366SdYc0KKX33vAnq+2R user@host ssh_key_file: ~/.ssh/id_ed25519 driver: linode .ft P .fi .UNINDENT .UNINDENT .sp The password needs to be 8 characters and contain lowercase, uppercase, and numbers. .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 In the cloud profile that uses this provider configuration, the syntax for the \fBprovider\fP required field would be \fBprovider: my\-linode\-config\fP .UNINDENT .UNINDENT .SS Joyent Cloud .sp The Joyent cloud requires three configuration parameters: The username and password that are used to log into the Joyent system, as well as 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 my\-joyent\-config: user: fred password: saltybacon private_key: /root/joyent.pem driver: joyent .ft P .fi .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 In the cloud profile that uses this provider configuration, the syntax for the \fBprovider\fP required field would be \fBprovider: my\-joyent\-config\fP .UNINDENT .UNINDENT .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 \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 my\-gogrid\-config: apikey: asdff7896asdh789 sharedsecret: saltybacon driver: gogrid .ft P .fi .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 In the cloud profile that uses this provider configuration, the syntax for the \fBprovider\fP required field would be \fBprovider: my\-gogrid\-config\fP\&. .UNINDENT .UNINDENT .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 .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 driver: 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 driver: 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 .INDENT 0.0 .INDENT 3.5 In the cloud profile that uses this provider configuration, the syntax for the \fBprovider\fP required field would be either \fBprovider: my\-openstack\-hp\-config\fP or \fBprovider: my\-openstack\-rackspace\-config\fP\&. .UNINDENT .UNINDENT .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: .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 DigitalOcean .sp Using Salt for DigitalOcean requires a \fBclient_key\fP and an \fBapi_key\fP\&. These can be found in the DigitalOcean web interface, in the "My Settings" section, under the API Access tab. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C my\-digitalocean\-config: driver: digital_ocean personal_access_token: xxx location: New York 1 .ft P .fi .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 In the cloud profile that uses this provider configuration, the syntax for the \fBprovider\fP required field would be \fBprovider: my\-digital\-ocean\-config\fP\&. .UNINDENT .UNINDENT .SS Parallels .sp Using Salt with Parallels requires a \fBuser\fP, \fBpassword\fP and \fBURL\fP\&. These can be obtained from your cloud provider. .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/ driver: parallels .ft P .fi .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 In the cloud profile that uses this provider configuration, the syntax for the \fBprovider\fP required field would be \fBprovider: my\-parallels\-config\fP\&. .UNINDENT .UNINDENT .SS Proxmox .sp Using Salt with Proxmox requires a \fBuser\fP, \fBpassword\fP, and \fBURL\fP\&. These can be obtained from your cloud host. Both PAM and PVE users can be used. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C my\-proxmox\-config: driver: proxmox user: saltcloud@pve password: xyzzy url: your.proxmox.host .ft P .fi .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 In the cloud profile that uses this provider configuration, the syntax for the \fBprovider\fP required field would be \fBprovider: my\-proxmox\-config\fP\&. .UNINDENT .UNINDENT .SS LXC .sp The lxc driver uses saltify to install salt and attach the lxc container as a new lxc minion. As soon as we can, we manage baremetal operation over SSH. You can also destroy those containers via this driver. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C devhost10\-lxc: target: devhost10 driver: lxc .ft P .fi .UNINDENT .UNINDENT .sp And in the map file: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C devhost10\-lxc: provider: devhost10\-lxc from_container: ubuntu backing: lvm sudo: True size: 3g ip: 10.0.3.9 minion: master: 10.5.0.1 master_port: 4506 lxc_conf: \- lxc.utsname: superlxc .ft P .fi .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 In the cloud profile that uses this provider configuration, the syntax for the \fBprovider\fP required field would be \fBprovider: devhost10\-lxc\fP\&. .UNINDENT .UNINDENT .SS Saltify .sp The Saltify driver is a new, experimental driver designed to install Salt on a remote machine, virtual or bare metal, using SSH. This driver is useful for provisioning machines which are already installed, but not Salted. For more information about using this driver and for configuration examples, please see the Gettting Started with Saltify documentation. .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, i.e. \fB/etc/salt/salt/cloud.providers\fP or \fB/etc/salt/cloud.providers.d/*.conf\fP\&. .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 Extending cloud profiles and providers is not recursive. For example, a profile that is extended by a second profile is possible, but the second profile cannot be extended by a third profile. .sp Also, if a profile (or provider) is extending another profile and each contains a list of values, the lists from the extending profile will override the list from the original profile. The lists are not merged together. .UNINDENT .UNINDENT .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: t1.micro 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: \(aqt1.micro\(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: \(aqt1.micro\(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: \(aqt1.micro\(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: \(aqt1.micro\(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 driver: ec2 \- user: myuser@mycorp.com password: mypass ssh_key_name: mykey ssh_key_file: \(aq/etc/salt/ibm/mykey.pem\(aq location: Raleigh driver: 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, \(aqdriver\(aq: \(aqaws\(aq, \(aqsecuritygroup\(aq: \(aqquick\-start\(aq }, {\(aqlocation\(aq: \(aqRaleigh\(aq, \(aqpassword\(aq: \(aqmypass\(aq, \(aqdriver\(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, \(aqdriver\(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 Windows Configuration .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 \fIimpacket\fP and \fIwinexe\fP to set up the Windows Salt Minion installer. .sp \fIimpacket\fP is usually available as either the \fIimpacket\fP or the \fIpython\-impacket\fP package, depending on the distribution. More information on \fIimpacket\fP can be found at the project home: .INDENT 0.0 .IP \(bu 2 \fI\%impacket project home\fP .UNINDENT .sp \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 .UNINDENT .INDENT 0.0 .IP \(bu 2 \fI\%openSUSE Build Service\fP .UNINDENT .sp Optionally WinRM can be used instead of \fIwinexe\fP if the python module \fIpywinrm\fP is available and WinRM is supported on the target Windows version. Information on pywinrm can be found at the project home: .INDENT 0.0 .IP \(bu 2 \fI\%pywinrm project home\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. .sp If supported by the cloud provider, a PowerShell script may be used to open up this port automatically, using the cloud provider\(aqs \fIuserdata\fP\&. The following script would open up port 445, and apply the changes: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C New\-NetFirewallRule \-Name "SMB445" \-DisplayName "SMB445" \-Protocol TCP \-LocalPort 445 Set\-Item (dir wsman:\elocalhost\eListener\e*\ePort \-Recurse).pspath 445 \-Force Restart\-Service winrm .ft P .fi .UNINDENT .UNINDENT .sp For EC2, this script may be saved as a file, and specified in the provider or profile configuration as \fIuserdata_file\fP\&. For instance: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C userdata_file: /etc/salt/windows\-firewall.ps1 .ft P .fi .UNINDENT .UNINDENT .sp If you are using WinRM on EC2 the HTTPS port for the WinRM service must also be enabled in your userdata. By default EC2 Windows images only have insecure HTTP enabled. To enable HTTPS and basic authentication required by pywinrm consider the following userdata example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C New\-NetFirewallRule \-Name "SMB445" \-DisplayName "SMB445" \-Protocol TCP \-LocalPort 445 New\-NetFirewallRule \-Name "WINRM5986" \-DisplayName "WINRM5986" \-Protocol TCP \-LocalPort 5986 winrm quickconfig \-q winrm set winrm/config/winrs \(aq@{MaxMemoryPerShellMB="300"}\(aq winrm set winrm/config \(aq@{MaxTimeoutms="1800000"}\(aq winrm set winrm/config/service/auth \(aq@{Basic="true"}\(aq $SourceStoreScope = \(aqLocalMachine\(aq $SourceStorename = \(aqRemote Desktop\(aq $SourceStore = New\-Object \-TypeName System.Security.Cryptography.X509Certificates.X509Store \-ArgumentList $SourceStorename, $SourceStoreScope $SourceStore.Open([System.Security.Cryptography.X509Certificates.OpenFlags]::ReadOnly) $cert = $SourceStore.Certificates | Where\-Object \-FilterScript { $_.subject \-like \(aq*\(aq } $DestStoreScope = \(aqLocalMachine\(aq $DestStoreName = \(aqMy\(aq $DestStore = New\-Object \-TypeName System.Security.Cryptography.X509Certificates.X509Store \-ArgumentList $DestStoreName, $DestStoreScope $DestStore.Open([System.Security.Cryptography.X509Certificates.OpenFlags]::ReadWrite) $DestStore.Add($cert) $SourceStore.Close() $DestStore.Close() winrm create winrm/config/listener?Address=*+Transport=HTTPS \(ga@\(ga{Hostname=\(ga"($certId)\(ga"\(ga;CertificateThumbprint=\(ga"($cert.Thumbprint)\(ga"\(ga} Restart\-Service winrm .ft P .fi .UNINDENT .UNINDENT .sp No certificate store is available by default on EC2 images and creating one does not seem possible without an MMC (cannot be automated). To use the default EC2 Windows images the above copies the RDP store. .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: driver: softlayer user: MYUSER1138 apikey: \(aqe3b68aa711e6deadc62d5b76355674beef7cc3116062ddbacafe5f7e465bfdc9\(aq minion: master: saltmaster.example.com win_installer: /root/Salt\-Minion\-2014.7.0\-AMD64\-Setup.exe win_username: Administrator win_password: letmein smb_port: 445 .ft P .fi .UNINDENT .UNINDENT .sp The default Windows user is \fIAdministrator\fP, and the default Windows password is blank. .sp If WinRM is to be used \fBuse_winrm\fP needs to be set to \fITrue\fP\&. \fBwinrm_port\fP can be used to specify a custom port (must be HTTPS listener). .SS Auto\-Generated Passwords on EC2 .sp On EC2, when the \fIwin_password\fP is set to \fIauto\fP, Salt Cloud will query EC2 for an auto\-generated password. This password is expected to take at least 4 minutes to generate, adding additional time to the deploy process. .sp When the EC2 API is queried for the auto\-generated password, it will be returned in a message encrypted with the specified \fIkeyname\fP\&. This requires that the appropriate \fIprivate_key\fP file is also specified. Such a profile configuration might look like: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C windows\-server\-2012: provider: my\-ec2\-config image: ami\-c49c0dac size: m1.small securitygroup: windows keyname: mykey private_key: /root/mykey.pem userdata_file: /etc/salt/windows\-firewall.ps1 win_installer: /root/Salt\-Minion\-2014.7.0\-AMD64\-Setup.exe win_username: Administrator win_password: auto .ft P .fi .UNINDENT .UNINDENT .SS Cloud Provider Specifics .SS Getting Started With Aliyun ECS .sp The Aliyun ECS (Elastic Computer Service) is one of the most popular public cloud hosts in China. This cloud host can be used to manage aliyun instance using salt\-cloud. .sp \fI\%http://www.aliyun.com/\fP .SS Dependencies .sp This driver requires the Python \fBrequests\fP library to be installed. .SS Configuration .sp Using Salt for Aliyun ECS requires aliyun access key id and key secret. These can be found in the aliyun web interface, in the "User Center" section, under "My Service" 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\-aliyun\-config: # aliyun Access Key ID id: wDGEwGregedg3435gDgxd # aliyun Access Key Secret key: GDd45t43RDBTrkkkg43934t34qT43t4dgegerGEgg location: cn\-qingdao driver: aliyun .ft P .fi .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 Changed in version 2015.8.0. .sp The \fBprovider\fP parameter in cloud provider definitions was renamed to \fBdriver\fP\&. This change was made to avoid confusion with the \fBprovider\fP parameter that is used in cloud profile definitions. Cloud provider definitions now use \fBdriver\fP to refer to the Salt cloud module that provides the underlying functionality to connect to a cloud host, while cloud profiles continue to use \fBprovider\fP to refer to provider configurations that you define. .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 aliyun_centos: provider: my\-aliyun\-config size: ecs.t1.small location: cn\-qingdao securitygroup: G1989096784427999 image: centos6u3_64_20G_aliaegis_20130816.vhd .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\-aliyun\-config my\-aliyun\-config: \-\-\-\-\-\-\-\-\-\- aliyun: \-\-\-\-\-\-\-\-\-\- ecs.c1.large: \-\-\-\-\-\-\-\-\-\- CpuCoreCount: 8 InstanceTypeId: ecs.c1.large MemorySize: 16.0 \&...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\-aliyun\-config my\-aliyun\-config: \-\-\-\-\-\-\-\-\-\- aliyun: \-\-\-\-\-\-\-\-\-\- centos5u8_64_20G_aliaegis_20131231.vhd: \-\-\-\-\-\-\-\-\-\- Architecture: x86_64 Description: ImageId: centos5u8_64_20G_aliaegis_20131231.vhd ImageName: CentOS 5.8 64位 ImageOwnerAlias: system ImageVersion: 1.0 OSName: CentOS 5.8 64位 Platform: CENTOS5 Size: 20 Visibility: public \&...SNIP... .ft P .fi .UNINDENT .UNINDENT .sp Locations can be obtained using the \fB\-\-list\-locations\fP option for the \fBsalt\-cloud\fP command: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C my\-aliyun\-config: \-\-\-\-\-\-\-\-\-\- aliyun: \-\-\-\-\-\-\-\-\-\- cn\-beijing: \-\-\-\-\-\-\-\-\-\- LocalName: 北京 RegionId: cn\-beijing cn\-hangzhou: \-\-\-\-\-\-\-\-\-\- LocalName: 杭州 RegionId: cn\-hangzhou cn\-hongkong: \-\-\-\-\-\-\-\-\-\- LocalName: 香港 RegionId: cn\-hongkong cn\-qingdao: \-\-\-\-\-\-\-\-\-\- LocalName: 青岛 RegionId: cn\-qingdao .ft P .fi .UNINDENT .UNINDENT .sp Security Group can be obtained using the \fB\-f list_securitygroup\fP option for the \fBsalt\-cloud\fP command: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C # salt\-cloud \-\-location=cn\-qingdao \-f list_securitygroup my\-aliyun\-config my\-aliyun\-config: \-\-\-\-\-\-\-\-\-\- aliyun: \-\-\-\-\-\-\-\-\-\- G1989096784427999: \-\-\-\-\-\-\-\-\-\- Description: G1989096784427999 SecurityGroupId: G1989096784427999 .ft P .fi .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 Aliyun ECS REST API documentation is available from \fI\%Aliyun ECS API\fP\&. .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 More information about Azure is located at \fI\%http://www.windowsazure.com/\fP\&. .SS Dependencies .INDENT 0.0 .IP \(bu 2 \fI\%Microsoft Azure SDK for Python\fP >= 1.0.2 .IP \(bu 2 The python\-requests library, for Python < 2.7.9. .IP \(bu 2 A Microsoft Azure account .IP \(bu 2 OpenSSL (to generate the certificates) .IP \(bu 2 \fI\%Salt\fP .UNINDENT .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 The Azure driver is currently being updated to work with the new version of the Python Azure SDK, 1.0.0. However until that process is complete, this driver will not work with Azure 1.0.0. Please be sure you\(aqre running on a minimum version of 0.10.2 and less than version 1.0.0. .sp See \fI\%Issue #27980\fP for more information. .UNINDENT .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: driver: 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 # Optional management_host: management.core.windows.net .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 creating these files, the .cer file will need to be uploaded to Azure via the "Upload a Management Certificate" action of the "Management Certificates" tab within the "Settings" section of the management portal. .sp Optionally, a \fBmanagement_host\fP may be configured, if necessary for the region. .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 Changed in version 2015.8.0. .sp The \fBprovider\fP parameter in cloud provider definitions was renamed to \fBdriver\fP\&. This change was made to avoid confusion with the \fBprovider\fP parameter that is used in cloud profile definitions. Cloud provider definitions now use \fBdriver\fP to refer to the Salt cloud module that provides the underlying functionality to connect to a cloud host, while cloud profiles continue to use \fBprovider\fP to refer to provider configurations that you define. .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 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 virtual_network_name: azure\-virtual\-network subnet_name: azure\-subnet .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 newinstance 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 affinity_group .sp The name of the affinity group to create a VM in. Either a \fBlocation\fP or an \fBaffinity_group\fP may be specified, but not both. See Affinity Groups below. .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 service_name .sp The name of the service in which to create the VM. If this is not specified, then a service will be created with the same name as the VM. .SS virtual_network_name .sp Optional. The name of the virtual network for the VM to join. If this is not specified, then no virtual network will be joined. .SS subnet_name .sp Optional. The name of the subnet in the virtual network for the VM to join. Requires that a \fBvirtual_network_name\fP is specified. .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 Destroying VMs .sp There are certain options which can be specified in the global cloud configuration file (usually \fB/etc/salt/cloud\fP) which affect Salt Cloud\(aqs behavior when a VM is destroyed. .SS cleanup_disks .sp New in version 2015.8.0. .sp Default is \fBFalse\fP\&. When set to \fBTrue\fP, Salt Cloud will wait for the VM to be destroyed, then attempt to destroy the main disk that is associated with the VM. .SS cleanup_vhds .sp New in version 2015.8.0. .sp Default is \fBFalse\fP\&. Requires \fBcleanup_disks\fP to be set to \fBTrue\fP\&. When also set to \fBTrue\fP, Salt Cloud will ask Azure to delete the VHD associated with the disk that is also destroyed. .SS cleanup_services .sp New in version 2015.8.0. .sp Default is \fBFalse\fP\&. Requires \fBcleanup_disks\fP to be set to \fBTrue\fP\&. When also set to \fBTrue\fP, Salt Cloud will wait for the disk to be destroyed, then attempt to remove the service that is associated with the VM. Because the disk belongs to the service, the disk must be destroyed before the service can be. .SS Managing Hosted Services .sp New in version 2015.8.0. .sp An account can have one or more hosted services. A hosted service is required in order to create a VM. However, as mentioned above, if a hosted service is not specified when a VM is created, then one will automatically be created with the name of the name. The following functions are also available. .SS create_service .sp Create a hosted service. The following options are available. .SS name .sp Required. The name of the hosted service to create. .SS label .sp Required. A label to apply to the hosted service. .SS description .sp Optional. A longer description of the hosted service. .SS location .sp Required, if \fBaffinity_group\fP is not set. The location in which to create the hosted service. Either the \fBlocation\fP or the \fBaffinity_group\fP must be set, but not both. .SS affinity_group .sp Required, if \fBlocation\fP is not set. The affinity group in which to create the hosted service. Either the \fBlocation\fP or the \fBaffinity_group\fP must be set, but not both. .SS extended_properties .sp Optional. Dictionary containing name/value pairs of hosted service properties. You can have a maximum of 50 extended property name/value pairs. The maximum length of the Name element is 64 characters, only alphanumeric characters and underscores are valid in the Name, and the name must start with a letter. The value has a maximum length of 255 characters. .SS CLI Example .sp The following example illustrates creating a hosted service. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-f create_service my\-azure name=my\-service label=my\-service location=\(aqWest US\(aq .ft P .fi .UNINDENT .UNINDENT .SS show_service .sp Return details about a specific hosted service. Can also be called with \fBget_service\fP\&. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-f show_storage my\-azure name=my\-service .ft P .fi .UNINDENT .UNINDENT .SS list_services .sp List all hosted services associates with the subscription. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-f list_services my\-azure\-config .ft P .fi .UNINDENT .UNINDENT .SS delete_service .sp Delete a specific hosted service. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-f delete_service my\-azure name=my\-service .ft P .fi .UNINDENT .UNINDENT .SS Managing Storage Accounts .sp New in version 2015.8.0. .sp Salt Cloud can manage storage accounts associated with the account. The following functions are available. Deprecated marked as deprecated are marked as such as per the SDK documentation, but are still included for completeness with the SDK. .SS create_storage .sp Create a storage account. The following options are supported. .SS name .sp Required. The name of the storage account to create. .SS label .sp Required. A label to apply to the storage account. .SS description .sp Optional. A longer description of the storage account. .SS location .sp Required, if \fBaffinity_group\fP is not set. The location in which to create the storage account. Either the \fBlocation\fP or the \fBaffinity_group\fP must be set, but not both. .SS affinity_group .sp Required, if \fBlocation\fP is not set. The affinity group in which to create the storage account. Either the \fBlocation\fP or the \fBaffinity_group\fP must be set, but not both. .SS extended_properties .sp Optional. Dictionary containing name/value pairs of storage account properties. You can have a maximum of 50 extended property name/value pairs. The maximum length of the Name element is 64 characters, only alphanumeric characters and underscores are valid in the Name, and the name must start with a letter. The value has a maximum length of 255 characters. .SS geo_replication_enabled .sp Deprecated. Replaced by the account_type parameter. .SS account_type .sp Specifies whether the account supports locally\-redundant storage, geo\-redundant storage, zone\-redundant storage, or read access geo\-redundant storage. Possible values are: .INDENT 0.0 .IP \(bu 2 Standard_LRS .IP \(bu 2 Standard_ZRS .IP \(bu 2 Standard_GRS .IP \(bu 2 Standard_RAGRS .UNINDENT .SS CLI Example .sp The following example illustrates creating a storage account. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-f create_storage my\-azure name=my\-storage label=my\-storage location=\(aqWest US\(aq .ft P .fi .UNINDENT .UNINDENT .SS list_storage .sp List all storage accounts associates with the subscription. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-f list_storage my\-azure\-config .ft P .fi .UNINDENT .UNINDENT .SS show_storage .sp Return details about a specific storage account. Can also be called with \fBget_storage\fP\&. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-f show_storage my\-azure name=my\-storage .ft P .fi .UNINDENT .UNINDENT .SS update_storage .sp Update details concerning a storage account. Any of the options available in \fBcreate_storage\fP can be used, but the name cannot be changed. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-f update_storage my\-azure name=my\-storage label=my\-storage .ft P .fi .UNINDENT .UNINDENT .SS delete_storage .sp Delete a specific storage account. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-f delete_storage my\-azure name=my\-storage .ft P .fi .UNINDENT .UNINDENT .SS show_storage_keys .sp Returns the primary and secondary access keys for the specified storage account. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-f show_storage_keys my\-azure name=my\-storage .ft P .fi .UNINDENT .UNINDENT .SS regenerate_storage_keys .sp Regenerate storage account keys. Requires a key_type ("primary" or "secondary") to be specified. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-f regenerate_storage_keys my\-azure name=my\-storage key_type=primary .ft P .fi .UNINDENT .UNINDENT .SS Managing Disks .sp New in version 2015.8.0. .sp When a VM is created, a disk will also be created for it. The following functions are available for managing disks. Deprecated marked as deprecated are marked as such as per the SDK documentation, but are still included for completeness with the SDK. .SS show_disk .sp Return details about a specific disk. Can also be called with \fBget_disk\fP\&. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-f show_disk my\-azure name=my\-disk .ft P .fi .UNINDENT .UNINDENT .SS list_disks .sp List all disks associates with the account. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-f list_disks my\-azure .ft P .fi .UNINDENT .UNINDENT .SS update_disk .sp Update details for a disk. The following options are available. .SS name .sp Required. The name of the disk to update. .SS has_operating_system .sp Deprecated. .SS label .sp Required. The label for the disk. .SS media_link .sp Deprecated. The location of the disk in the account, including the storage container that it is in. This should not need to be changed. .SS new_name .sp Deprecated. If renaming the disk, the new name. .SS os .sp Deprecated. .SS CLI Example .sp The following example illustrates updating a disk. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-f update_disk my\-azure name=my\-disk label=my\-disk .ft P .fi .UNINDENT .UNINDENT .SS delete_disk .sp Delete a specific disk. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-f delete_disk my\-azure name=my\-disk .ft P .fi .UNINDENT .UNINDENT .SS Managing Service Certificates .sp New in version 2015.8.0. .sp Stored at the cloud service level, these certificates are used by your deployed services. For more information on service certificates, see the following link: .INDENT 0.0 .IP \(bu 2 \fI\%Manage Certificates\fP .UNINDENT .sp The following functions are available. .SS list_service_certificates .sp List service certificates associated with the account. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-f list_service_certificates my\-azure .ft P .fi .UNINDENT .UNINDENT .SS show_service_certificate .sp Show the data for a specific service certificate associated with the account. The \fBname\fP, \fBthumbprint\fP, and \fBthumbalgorithm\fP can be obtained from \fBlist_service_certificates\fP\&. Can also be called with \fBget_service_certificate\fP\&. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-f show_service_certificate my\-azure name=my_service_certificate \e thumbalgorithm=sha1 thumbprint=0123456789ABCDEF .ft P .fi .UNINDENT .UNINDENT .SS add_service_certificate .sp Add a service certificate to the account. This requires that a certificate already exists, which is then added to the account. For more information on creating the certificate itself, see: .INDENT 0.0 .IP \(bu 2 \fI\%Create a Service Certificate for Azure\fP .UNINDENT .sp The following options are available. .SS name .sp Required. The name of the hosted service that the certificate will belong to. .SS data .sp Required. The base\-64 encoded form of the pfx file. .SS certificate_format .sp Required. The service certificate format. The only supported value is pfx. .SS password .sp The certificate password. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-f add_service_certificate my\-azure name=my\-cert \e data=\(aq...CERT_DATA...\(aq certificate_format=pfx password=verybadpass .ft P .fi .UNINDENT .UNINDENT .SS delete_service_certificate .sp Delete a service certificate from the account. The \fBname\fP, \fBthumbprint\fP, and \fBthumbalgorithm\fP can be obtained from \fBlist_service_certificates\fP\&. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-f delete_service_certificate my\-azure \e name=my_service_certificate \e thumbalgorithm=sha1 thumbprint=0123456789ABCDEF .ft P .fi .UNINDENT .UNINDENT .SS Managing Management Certificates .sp New in version 2015.8.0. .sp A Azure management certificate is an X.509 v3 certificate used to authenticate an agent, such as Visual Studio Tools for Windows Azure or a client application that uses the Service Management API, acting on behalf of the subscription owner to manage subscription resources. Azure management certificates are uploaded to Azure and stored at the subscription level. The management certificate store can hold up to 100 certificates per subscription. These certificates are used to authenticate your Windows Azure deployment. .sp For more information on management certificates, see the following link. .INDENT 0.0 .IP \(bu 2 \fI\%Manage Certificates\fP .UNINDENT .sp The following functions are available. .SS list_management_certificates .sp List management certificates associated with the account. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-f list_management_certificates my\-azure .ft P .fi .UNINDENT .UNINDENT .SS show_management_certificate .sp Show the data for a specific management certificate associated with the account. The \fBname\fP, \fBthumbprint\fP, and \fBthumbalgorithm\fP can be obtained from \fBlist_management_certificates\fP\&. Can also be called with \fBget_management_certificate\fP\&. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-f show_management_certificate my\-azure name=my_management_certificate \e thumbalgorithm=sha1 thumbprint=0123456789ABCDEF .ft P .fi .UNINDENT .UNINDENT .SS add_management_certificate .sp Management certificates must have a key length of at least 2048 bits and should reside in the Personal certificate store. When the certificate is installed on the client, it should contain the private key of the certificate. To upload to the certificate to the Microsoft Azure Management Portal, you must export it as a .cer format file that does not contain the private key. For more information on creating management certificates, see the following link: .INDENT 0.0 .IP \(bu 2 \fI\%Create and Upload a Management Certificate for Azure\fP .UNINDENT .sp The following options are available. .SS public_key .sp A base64 representation of the management certificate public key. .SS thumbprint .sp The thumb print that uniquely identifies the management certificate. .SS data .sp The certificate\(aqs raw data in base\-64 encoded .cer format. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-f add_management_certificate my\-azure public_key=\(aq...PUBKEY...\(aq \e thumbprint=0123456789ABCDEF data=\(aq...CERT_DATA...\(aq .ft P .fi .UNINDENT .UNINDENT .SS delete_management_certificate .sp Delete a management certificate from the account. The \fBthumbprint\fP can be obtained from \fBlist_management_certificates\fP\&. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-f delete_management_certificate my\-azure thumbprint=0123456789ABCDEF .ft P .fi .UNINDENT .UNINDENT .SS Virtual Network Management .sp New in version 2015.8.0. .sp The following are functions for managing virtual networks. .SS list_virtual_networks .sp List input endpoints associated with the deployment. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-f list_virtual_networks my\-azure service=myservice deployment=mydeployment .ft P .fi .UNINDENT .UNINDENT .SS Managing Input Endpoints .sp New in version 2015.8.0. .sp Input endpoints are used to manage port access for roles. Because endpoints cannot be managed by the Azure Python SDK, Salt Cloud uses the API directly. With versions of Python before 2.7.9, the \fBrequests\-python\fP package needs to be installed in order for this to work. Additionally, the following needs to be set in the master\(aqs configuration file: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C backend: requests .ft P .fi .UNINDENT .UNINDENT .sp The following functions are available. .SS list_input_endpoints .sp List input endpoints associated with the deployment .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-f list_input_endpoints my\-azure service=myservice deployment=mydeployment .ft P .fi .UNINDENT .UNINDENT .SS show_input_endpoint .sp Show an input endpoint associated with the deployment .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-f show_input_endpoint my\-azure service=myservice \e deployment=mydeployment name=SSH .ft P .fi .UNINDENT .UNINDENT .SS add_input_endpoint .sp Add an input endpoint to the deployment. Please note that there may be a delay before the changes show up. The following options are available. .SS service .sp Required. The name of the hosted service which the VM belongs to. .SS deployment .sp Required. The name of the deployment that the VM belongs to. If the VM was created with Salt Cloud, the deployment name probably matches the VM name. .SS role .sp Required. The name of the role that the VM belongs to. If the VM was created with Salt Cloud, the role name probably matches the VM name. .SS name .sp Required. The name of the input endpoint. This typically matches the port that the endpoint is set to. For instance, port 22 would be called SSH. .SS port .sp Required. The public (Internet\-facing) port that is used for the endpoint. .SS local_port .sp Optional. The private port on the VM itself that will be matched with the port. This is typically the same as the \fBport\fP\&. If this value is not specified, it will be copied from \fBport\fP\&. .SS protocol .sp Required. Either \fBtcp\fP or \fBudp\fP\&. .SS enable_direct_server_return .sp Optional. If an internal load balancer exists in the account, it can be used with a direct server return. The default value is \fBFalse\fP\&. Please see the following article for an explanation of this option. .INDENT 0.0 .IP \(bu 2 \fI\%Load Balancing for Azure Infrastructure Services\fP .UNINDENT .SS timeout_for_tcp_idle_connection .sp Optional. The default value is \fB4\fP\&. Please see the following article for an explanation of this option. .INDENT 0.0 .IP \(bu 2 \fI\%Configurable Idle Timeout for Azure Load Balancer\fP .UNINDENT .SS CLI Example .sp The following example illustrates adding an input endpoint. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-f add_input_endpoint my\-azure service=myservice \e deployment=mydeployment role=myrole name=HTTP local_port=80 \e port=80 protocol=tcp enable_direct_server_return=False \e timeout_for_tcp_idle_connection=4 .ft P .fi .UNINDENT .UNINDENT .SS update_input_endpoint .sp Updates the details for a specific input endpoint. All options from \fBadd_input_endpoint\fP are supported. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-f update_input_endpoint my\-azure service=myservice \e deployment=mydeployment role=myrole name=HTTP local_port=80 \e port=80 protocol=tcp enable_direct_server_return=False \e timeout_for_tcp_idle_connection=4 .ft P .fi .UNINDENT .UNINDENT .SS delete_input_endpoint .sp Delete an input endpoint from the deployment. Please note that there may be a delay before the changes show up. The following items are required. .SS CLI Example .sp The following example illustrates deleting an input endpoint. .SS service .sp The name of the hosted service which the VM belongs to. .SS deployment .sp The name of the deployment that the VM belongs to. If the VM was created with Salt Cloud, the deployment name probably matches the VM name. .SS role .sp The name of the role that the VM belongs to. If the VM was created with Salt Cloud, the role name probably matches the VM name. .SS name .sp The name of the input endpoint. This typically matches the port that the endpoint is set to. For instance, port 22 would be called SSH. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-f delete_input_endpoint my\-azure service=myservice \e deployment=mydeployment role=myrole name=HTTP .ft P .fi .UNINDENT .UNINDENT .SS Managing Affinity Groups .sp New in version 2015.8.0. .sp Affinity groups allow you to group your Azure services to optimize performance. All services and VMs within an affinity group will be located in the same region. For more information on Affinity groups, see the following link: .INDENT 0.0 .IP \(bu 2 \fI\%Create an Affinity Group in the Management Portal\fP .UNINDENT .sp The following functions are available. .SS list_affinity_groups .sp List input endpoints associated with the account .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-f list_affinity_groups my\-azure .ft P .fi .UNINDENT .UNINDENT .SS show_affinity_group .sp Show an affinity group associated with the account .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-f show_affinity_group my\-azure service=myservice \e deployment=mydeployment name=SSH .ft P .fi .UNINDENT .UNINDENT .SS create_affinity_group .sp Create a new affinity group. The following options are supported. .SS name .sp Required. The name of the new affinity group. .SS location .sp Required. The region in which the affinity group lives. .SS label .sp Required. A label describing the new affinity group. .SS description .sp Optional. A longer description of the affinity group. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-f create_affinity_group my\-azure name=my_affinity_group \e label=my\-affinity\-group location=\(aqWest US\(aq .ft P .fi .UNINDENT .UNINDENT .SS update_affinity_group .sp Update an affinity group\(aqs properties .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-f update_affinity_group my\-azure name=my_group label=my_group .ft P .fi .UNINDENT .UNINDENT .SS delete_affinity_group .sp Delete a specific affinity group associated with the account .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-f delete_affinity_group my\-azure name=my_affinity_group .ft P .fi .UNINDENT .UNINDENT .SS Managing Blob Storage .sp New in version 2015.8.0. .sp Azure storage containers and their contents can be managed with Salt Cloud. This is not as elegant as using one of the other available clients in Windows, but it benefits Linux and Unix users, as there are fewer options available on those platforms. .SS Blob Storage Configuration .sp Blob storage must be configured differently than the standard Azure configuration. Both a \fBstorage_account\fP and a \fBstorage_key\fP must be specified either through the Azure provider configuration (in addition to the other Azure configuration) or via the command line. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C storage_account: mystorage storage_key: ffhj334fDSGFEGDFGFDewr34fwfsFSDFwe== .ft P .fi .UNINDENT .UNINDENT .SS storage_account .sp This is one of the storage accounts that is available via the \fBlist_storage\fP function. .SS storage_key .sp Both a primary and a secondary \fBstorage_key\fP can be obtained by running the \fBshow_storage_keys\fP function. Either key may be used. .SS Blob Functions .sp The following functions are made available through Salt Cloud for managing blog storage. .SS make_blob_url .sp Creates the URL to access a blob .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-f make_blob_url my\-azure container=mycontainer blob=myblob .ft P .fi .UNINDENT .UNINDENT .SS container .sp Name of the container. .SS blob .sp Name of the blob. .SS account .sp Name of the storage account. If not specified, derives the host base from the provider configuration. .SS protocol .sp Protocol to use: \(aqhttp\(aq or \(aqhttps\(aq. If not specified, derives the host base from the provider configuration. .SS host_base .sp Live host base URL. If not specified, derives the host base from the provider configuration. .SS list_storage_containers .sp List containers associated with the storage account .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-f list_storage_containers my\-azure .ft P .fi .UNINDENT .UNINDENT .SS create_storage_container .sp Create a storage container .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-f create_storage_container my\-azure name=mycontainer .ft P .fi .UNINDENT .UNINDENT .SS name .sp Name of container to create. .SS meta_name_values .sp Optional. A dict with name_value pairs to associate with the container as metadata. Example:{\(aqCategory\(aq:\(aqtest\(aq} .SS blob_public_access .sp Optional. Possible values include: container, blob .SS fail_on_exist .sp Specify whether to throw an exception when the container exists. .SS show_storage_container .sp Show a container associated with the storage account .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-f show_storage_container my\-azure name=myservice .ft P .fi .UNINDENT .UNINDENT .SS name .sp Name of container to show. .SS show_storage_container_metadata .sp Show a storage container\(aqs metadata .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-f show_storage_container_metadata my\-azure name=myservice .ft P .fi .UNINDENT .UNINDENT .SS name .sp Name of container to show. .SS lease_id .sp If specified, show_storage_container_metadata only succeeds if the container\(aqs lease is active and matches this ID. .SS set_storage_container_metadata .sp Set a storage container\(aqs metadata .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-f set_storage_container my\-azure name=mycontainer \e x_ms_meta_name_values=\(aq{"my_name": "my_value"}\(aq .ft P .fi .UNINDENT .UNINDENT .SS name .sp Name of existing container. meta_name_values \fB\(ga\(ga\(ga\(ga\(ga\(ga\(ga\(ga\(ga\(ga\(ga\(ga\fP A dict containing name, value for metadata. Example: {\(aqcategory\(aq:\(aqtest\(aq} lease_id \fB\(ga\(ga\(ga\(ga\fP If specified, set_storage_container_metadata only succeeds if the container\(aqs lease is active and matches this ID. .SS show_storage_container_acl .sp Show a storage container\(aqs acl .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-f show_storage_container_acl my\-azure name=myservice .ft P .fi .UNINDENT .UNINDENT .SS name .sp Name of existing container. .SS lease_id .sp If specified, show_storage_container_acl only succeeds if the container\(aqs lease is active and matches this ID. .SS set_storage_container_acl .sp Set a storage container\(aqs acl .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-f set_storage_container my\-azure name=mycontainer .ft P .fi .UNINDENT .UNINDENT .SS name .sp Name of existing container. .SS signed_identifiers .sp SignedIdentifers instance .SS blob_public_access .sp Optional. Possible values include: container, blob .SS lease_id .sp If specified, set_storage_container_acl only succeeds if the container\(aqs lease is active and matches this ID. .SS delete_storage_container .sp Delete a container associated with the storage account .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-f delete_storage_container my\-azure name=mycontainer .ft P .fi .UNINDENT .UNINDENT .SS name .sp Name of container to create. .SS fail_not_exist .sp Specify whether to throw an exception when the container exists. .SS lease_id .sp If specified, delete_storage_container only succeeds if the container\(aqs lease is active and matches this ID. .SS lease_storage_container .sp Lease a container associated with the storage account .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-f lease_storage_container my\-azure name=mycontainer .ft P .fi .UNINDENT .UNINDENT .SS name .sp Name of container to create. .SS lease_action .sp Required. Possible values: acquire|renew|release|break|change .SS lease_id .sp Required if the container has an active lease. .SS lease_duration .sp Specifies the duration of the lease, in seconds, or negative one (\-1) for a lease that never expires. A non\-infinite lease can be between 15 and 60 seconds. A lease duration cannot be changed using renew or change. For backwards compatibility, the default is 60, and the value is only used on an acquire operation. .SS lease_break_period .sp Optional. For a break operation, this is the proposed duration of seconds that the lease should continue before it is broken, between 0 and 60 seconds. This break period is only used if it is shorter than the time remaining on the lease. If longer, the time remaining on the lease is used. A new lease will not be available before the break period has expired, but the lease may be held for longer than the break period. If this header does not appear with a break operation, a fixed\-duration lease breaks after the remaining lease period elapses, and an infinite lease breaks immediately. .SS proposed_lease_id .sp Optional for acquire, required for change. Proposed lease ID, in a GUID string format. .SS list_blobs .sp List blobs associated with the container .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-f list_blobs my\-azure container=mycontainer .ft P .fi .UNINDENT .UNINDENT .SS container .sp The name of the storage container .SS prefix .sp Optional. Filters the results to return only blobs whose names begin with the specified prefix. .SS marker .sp Optional. A string value that identifies the portion of the list to be returned with the next list operation. The operation returns a marker value within the response body if the list returned was not complete. The marker value may then be used in a subsequent call to request the next set of list items. The marker value is opaque to the client. .SS maxresults .sp Optional. Specifies the maximum number of blobs to return, including all BlobPrefix elements. If the request does not specify maxresults or specifies a value greater than 5,000, the server will return up to 5,000 items. Setting maxresults to a value less than or equal to zero results in error response code 400 (Bad Request). .SS include .sp Optional. Specifies one or more datasets to include in the response. To specify more than one of these options on the URI, you must separate each option with a comma. Valid values are: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C snapshots: Specifies that snapshots should be included in the enumeration. Snapshots are listed from oldest to newest in the response. metadata: Specifies that blob metadata be returned in the response. uncommittedblobs: Specifies that blobs for which blocks have been uploaded, but which have not been committed using Put Block List (REST API), be included in the response. copy: Version 2012\-02\-12 and newer. Specifies that metadata related to any current or previous Copy Blob operation should be included in the response. .ft P .fi .UNINDENT .UNINDENT .SS delimiter .sp Optional. When the request includes this parameter, the operation returns a BlobPrefix element in the response body that acts as a placeholder for all blobs whose names begin with the same substring up to the appearance of the delimiter character. The delimiter may be a single character or a string. .SS show_blob_service_properties .sp Show a blob\(aqs service properties .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-f show_blob_service_properties my\-azure .ft P .fi .UNINDENT .UNINDENT .SS set_blob_service_properties .sp Sets the properties of a storage account\(aqs Blob service, including Windows Azure Storage Analytics. You can also use this operation to set the default request version for all incoming requests that do not have a version specified. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-f set_blob_service_properties my\-azure .ft P .fi .UNINDENT .UNINDENT .SS properties .sp a StorageServiceProperties object. .SS timeout .sp Optional. The timeout parameter is expressed in seconds. .SS show_blob_properties .sp Returns all user\-defined metadata, standard HTTP properties, and system properties for the blob. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-f show_blob_properties my\-azure container=mycontainer blob=myblob .ft P .fi .UNINDENT .UNINDENT .SS container .sp Name of existing container. .SS blob .sp Name of existing blob. .SS lease_id .sp Required if the blob has an active lease. .SS set_blob_properties .sp Set a blob\(aqs properties .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-f set_blob_properties my\-azure .ft P .fi .UNINDENT .UNINDENT .SS container .sp Name of existing container. .SS blob .sp Name of existing blob. .SS blob_cache_control .sp Optional. Modifies the cache control string for the blob. .SS blob_content_type .sp Optional. Sets the blob\(aqs content type. .SS blob_content_md5 .sp Optional. Sets the blob\(aqs MD5 hash. .SS blob_content_encoding .sp Optional. Sets the blob\(aqs content encoding. .SS blob_content_language .sp Optional. Sets the blob\(aqs content language. .SS lease_id .sp Required if the blob has an active lease. .SS blob_content_disposition .sp Optional. Sets the blob\(aqs Content\-Disposition header. The Content\-Disposition response header field conveys additional information about how to process the response payload, and also can be used to attach additional metadata. For example, if set to attachment, it indicates that the user\-agent should not display the response, but instead show a Save As dialog with a filename other than the blob name specified. .SS put_blob .sp Upload a blob .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-f put_blob my\-azure container=base name=top.sls blob_path=/srv/salt/top.sls salt\-cloud \-f put_blob my\-azure container=base name=content.txt blob_content=\(aqSome content\(aq .ft P .fi .UNINDENT .UNINDENT .SS container .sp Name of existing container. .SS name .sp Name of existing blob. .SS blob_path .sp The path on the local machine of the file to upload as a blob. Either this or blob_content must be specified. .SS blob_content .sp The actual content to be uploaded as a blob. Either this or blob_path must me specified. .SS cache_control .sp Optional. The Blob service stores this value but does not use or modify it. .SS content_language .sp Optional. Specifies the natural languages used by this resource. .SS content_md5 .sp Optional. An MD5 hash of the blob content. This hash is used to verify the integrity of the blob during transport. When this header is specified, the storage service checks the hash that has arrived with the one that was sent. If the two hashes do not match, the operation will fail with error code 400 (Bad Request). .SS blob_content_type .sp Optional. Set the blob\(aqs content type. .SS blob_content_encoding .sp Optional. Set the blob\(aqs content encoding. .SS blob_content_language .sp Optional. Set the blob\(aqs content language. .SS blob_content_md5 .sp Optional. Set the blob\(aqs MD5 hash. .SS blob_cache_control .sp Optional. Sets the blob\(aqs cache control. .SS meta_name_values .sp A dict containing name, value for metadata. .SS lease_id .sp Required if the blob has an active lease. .SS get_blob .sp Download a blob .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-f get_blob my\-azure container=base name=top.sls local_path=/srv/salt/top.sls salt\-cloud \-f get_blob my\-azure container=base name=content.txt return_content=True .ft P .fi .UNINDENT .UNINDENT .SS container .sp Name of existing container. .SS name .sp Name of existing blob. .SS local_path .sp The path on the local machine to download the blob to. Either this or return_content must be specified. .SS return_content .sp Whether or not to return the content directly from the blob. If specified, must be True or False. Either this or the local_path must be specified. .SS snapshot .sp Optional. The snapshot parameter is an opaque DateTime value that, when present, specifies the blob snapshot to retrieve. .SS lease_id .sp Required if the blob has an active lease. .SS progress_callback .sp callback for progress with signature function(current, total) where current is the number of bytes transferred so far, and total is the size of the blob. .SS max_connections .sp Maximum number of parallel connections to use when the blob size exceeds 64MB. Set to 1 to download the blob chunks sequentially. Set to 2 or more to download the blob chunks in parallel. This uses more system resources but will download faster. .SS max_retries .sp Number of times to retry download of blob chunk if an error occurs. .SS retry_wait .sp Sleep time in secs between retries. .SS Getting Started With Azure ARM .sp New in version 2016.11.0. .sp Azure is a cloud service by Microsoft providing virtual machines, SQL services, media services, and more. Azure ARM (aka, the Azure Resource Manager) is a next generatiom version of the Azure portal and API. This document describes how to use Salt Cloud to create a virtual machine on Azure ARM, with Salt installed. .sp More information about Azure is located at \fI\%http://www.windowsazure.com/\fP\&. .SS Dependencies .INDENT 0.0 .IP \(bu 2 \fI\%Microsoft Azure SDK for Python\fP >= 2.0rc5 .IP \(bu 2 \fI\%Microsoft Azure Storage SDK for Python\fP >= 0.32 .IP \(bu 2 The python\-requests library, for Python < 2.7.9. .IP \(bu 2 A Microsoft Azure account .IP \(bu 2 \fI\%Salt\fP .UNINDENT .SS Configuration .sp Set up the provider config at \fB/etc/salt/cloud.providers.d/azurearm.conf\fP: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C # Note: This example is for /etc/salt/cloud.providers.d/azurearm.conf my\-azurearm\-config: driver: azurearm master: limejack.com subscription_id: 01234567\-890a\-bcde\-f012\-34567890abdc # https://apps.dev.microsoft.com/#/appList username: @.onmicrosoft.com password: verybadpass location: westus resource_group: my_rg # Optional network_resource_group: my_net_rg cleanup_disks: True cleanup_vhds: True cleanup_data_disks: True cleanup_interfaces: True custom_data: \(aqThis is a Joseph test\(aq expire_publisher_cache: 604800 # 1 week expire_offer_cache: 604800 # 1 week expire_sku_cache: 604800 # 1 week expire_version_cache: 604800 # 1 week expire_group_cache: 86400 # 1 day expire_interface_cache: 3600 # 1 hour expire_network_cache: 3600 # 1 hour expire_subnet_cache: 3600 # 1 hour .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 azure\-ubuntu: provider: my\-azure\-config image: Canonical|UbuntuServer|14.04.5\-LTS|14.04.201612050 size: Standard_D1_v2 location: eastus ssh_username: azureuser ssh_password: verybadpass azure\-win2012: provider: my\-azure\-config image: MicrosoftWindowsServer|WindowsServer|2012\-R2\-Datacenter|latest size: Standard_D1_v2 location: westus win_username: azureuser win_password: verybadpass .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 newinstance test.ping .ft P .fi .UNINDENT .UNINDENT .SS Profile Options .sp The following options are currently available for Azure ARM. .SS provider .sp The name of the provider as configured in \fI/etc/salt/cloud.providers.d/azure.conf\fP\&. .SS image .sp Required. 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 .sp As you will see in \fB\-\-list\-images\fP, image names are comprised of the following fields, separated by the pipe (\fB|\fP) character: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C publisher: For example, Canonical or MicrosoftWindowsServer offer: For example, UbuntuServer or WindowsServer sku: Such as 14.04.5\-LTS or 2012\-R2\-Datacenter version: Such as 14.04.201612050 or latest .ft P .fi .UNINDENT .UNINDENT .sp It is possible to specify the URL of a custom image that you have access to, such as: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C https://.blob.core.windows.net/system/Microsoft.Compute/Images//template\-osDisk.01234567\-890a\-bcdef0123\-4567890abcde.vhd .ft P .fi .UNINDENT .UNINDENT .SS size .sp Required. 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 Required. 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 Required for Linux. The user to use to log into the newly\-created Linux VM to install Salt. .SS ssh_password .sp Required for Linux. The password to use to log into the newly\-created Linux VM to install Salt. .SS win_username .sp Required for Windows. The user to use to log into the newly\-created Windows VM to install Salt. .SS win_password .sp Required for Windows. The password to use to log into the newly\-created Windows VM to install Salt. .SS resource_group .sp Required. The resource group that all VM resources (VM, network interfaces, etc) will be created in. .SS network_resource_group .sp Optional. If specified, then the VM will be connected to the network resources in this group, rather than the group that it was created in. The VM interfaces and IPs will remain in the configured \fBresource_group\fP with the VM. .SS cleanup_disks .sp Optional. Default is \fBFalse\fP\&. If set to \fBTrue\fP, disks will be cleaned up when the VM that they belong to is deleted. .SS cleanup_vhds .sp Optional. Default is \fBFalse\fP\&. If set to \fBTrue\fP, VHDs will be cleaned up when the VM and disk that they belong to are deleted. Requires \fBcleanup_disks\fP to be set to \fBTrue\fP\&. .SS cleanup_data_disks .sp Optional. Default is \fBFalse\fP\&. If set to \fBTrue\fP, data disks (non\-root volumes) will be cleaned up whtn the VM that they are attached to is deleted. Requires \fBcleanup_disks\fP to be set to \fBTrue\fP\&. .SS cleanup_interfaces .sp Optional. Default is \fBFalse\fP\&. Normally when a VM is deleted, its associated interfaces and IPs are retained. This is useful if you expect the deleted VM to be recreated with the same name and network settings. If you would like interfaces and IPs to be deleted when their associated VM is deleted, set this to \fBTrue\fP\&. .SS custom_data .sp Any custom cloud data that needs to be specified. How this data is used depends on the operating system and image that is used. For instance, Linux images that use \fBcloud\-init\fP will import this data for use with that program. Some Windows images will create a file with a copy of this data, and others will ignore it. If a Windows image creates a file, then the location will depend upon the version of Windows. .SS expire_publisher_cache .sp Optional. Default is \fB604800\fP\&. When fetching image data using \fB\-\-list\-images\fP, a number of web calls need to be made to the Azure ARM API. This is normally very fast when performed using a VM that exists inside Azure itself, but can be very slow when made from an external connection. .sp By default, the publisher data will be cached, and only updated every \fB604800\fP seconds (7 days). If you need the publisher cache to be updated at a different frequency, change this setting. Setting it to \fB0\fP will turn off the publisher cache. .SS expire_offer_cache .sp Optional. Default is \fB604800\fP\&. See \fBexpire_publisher_cache\fP for details on why this exists. .sp By default, the offer data will be cached, and only updated every \fB604800\fP seconds (7 days). If you need the offer cache to be updated at a different frequency, change this setting. Setting it to \fB0\fP will turn off the publiser cache. .SS expire_sku_cache .sp Optional. Default is \fB604800\fP\&. See \fBexpire_publisher_cache\fP for details on why this exists. .sp By default, the sku data will be cached, and only updated every \fB604800\fP seconds (7 days). If you need the sku cache to be updated at a different frequency, change this setting. Setting it to \fB0\fP will turn off the sku cache. .SS expire_version_cache .sp Optional. Default is \fB604800\fP\&. See \fBexpire_publisher_cache\fP for details on why this exists. .sp By default, the version data will be cached, and only updated every \fB604800\fP seconds (7 days). If you need the version cache to be updated at a different frequency, change this setting. Setting it to \fB0\fP will turn off the version cache. .SS expire_group_cache .sp Optional. Default is \fB604800\fP\&. See \fBexpire_publisher_cache\fP for details on why this exists. .sp By default, the resource group data will be cached, and only updated every \fB604800\fP seconds (7 days). If you need the resource group cache to be updated at a different frequency, change this setting. Setting it to \fB0\fP will turn off the resource group cache. .SS expire_interface_cache .sp Optional. Default is \fB3600\fP\&. See \fBexpire_publisher_cache\fP for details on why this exists. .sp By default, the interface data will be cached, and only updated every \fB3600\fP seconds (1 hour). If you need the interface cache to be updated at a different frequency, change this setting. Setting it to \fB0\fP will turn off the interface cache. .SS expire_network_cache .sp Optional. Default is \fB3600\fP\&. See \fBexpire_publisher_cache\fP for details on why this exists. .sp By default, the network data will be cached, and only updated every \fB3600\fP seconds (1 hour). If you need the network cache to be updated at a different frequency, change this setting. Setting it to \fB0\fP will turn off the network cache. .SS expire_subnet_cache .sp Optional. Default is \fB3600\fP\&. See \fBexpire_publisher_cache\fP for details on why this exists. .sp By default, the subnet data will be cached, and only updated every \fB3600\fP seconds (1 hour). If you need the subnet cache to be updated at a different frequency, change this setting. Setting it to \fB0\fP will turn off the subnet cache. .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 Getting Started With DigitalOcean .sp DigitalOcean is a public cloud host that specializes in Linux instances. .SS Configuration .sp Using Salt for DigitalOcean requires a \fBpersonal_access_token\fP, an \fBssh_key_file\fP, and at least one SSH key name in \fBssh_key_names\fP\&. More \fBssh_key_names\fP can be added by separating each key with a comma. The \fBpersonal_access_token\fP can be found in the DigitalOcean web interface in the "Apps & API" section. The SSH key name can be found under the "SSH Keys" section. .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: driver: digital_ocean personal_access_token: xxx ssh_key_file: /path/to/ssh/key/file ssh_key_names: my\-key\-name,my\-key\-name\-2 location: New York 1 .ft P .fi .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 Changed in version 2015.8.0. .sp The \fBprovider\fP parameter in cloud provider definitions was renamed to \fBdriver\fP\&. This change was made to avoid confusion with the \fBprovider\fP parameter that is used in cloud profile definitions. Cloud provider definitions now use \fBdriver\fP to refer to the Salt cloud module that provides the underlying functionality to connect to a cloud host, while cloud profiles continue to use \fBprovider\fP to refer to provider configurations that you define. .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: 14.04 x64 size: 512MB location: New York 1 private_networking: True backups_enabled: True ipv6: True create_dns_record: True .ft P .fi .UNINDENT .UNINDENT .sp Locations can be obtained using the \fB\-\-list\-locations\fP option for the \fBsalt\-cloud\fP command: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C # salt\-cloud \-\-list\-locations my\-digitalocean\-config my\-digitalocean\-config: \-\-\-\-\-\-\-\-\-\- digital_ocean: \-\-\-\-\-\-\-\-\-\- Amsterdam 1: \-\-\-\-\-\-\-\-\-\- available: False features: [u\(aqbackups\(aq] name: Amsterdam 1 sizes: [] slug: ams1 \&...SNIP... .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: \-\-\-\-\-\-\-\-\-\- 10.1: \-\-\-\-\-\-\-\-\-\- created_at: 2015\-01\-20T20:04:34Z distribution: FreeBSD id: 10144573 min_disk_size: 20 name: 10.1 public: True \&...SNIP... .ft P .fi .UNINDENT .UNINDENT .SS Profile Specifics: .SS ssh_username .sp If using a FreeBSD image from Digital Ocean, you\(aqll need to set the \fBssh_username\fP setting to \fBfreebsd\fP in your profile configuration. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C digitalocean\-freebsd: provider: my\-digitalocean\-config image: 10.2 size: 512MB ssh_username: freebsd .ft P .fi .UNINDENT .UNINDENT .SS Miscellaneous Information .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 If your domain\(aqs DNS is managed with DigitalOcean, and your minion name matches your DigitalOcean managed DNS domain, you can automatically create A and AAA records for newly created droplets. Use \fBcreate_dns_record: True\fP in your config to enable this. Adding \fBdelete_dns_record: True\fP to also delete records when a droplet is destroyed is optional. Due to limitations in salt\-cloud design, the destroy code does not have access to the VM config data. WHETHER YOU ADD \fBcreate_dns_record: True\fP OR NOT, salt\-cloud WILL attempt to delete your DNS records if the minion name matches. This will prevent advertising any recycled IP addresses for destroyed minions. .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 If you need to perform the bootstrap using the local interface for droplets, this can be done by setting \fBssh_interface: private\fP in your config. By default the salt\-cloud script would run on the public interface however if firewall is preventing the connection to the Droplet over the public interface you might need to set this option to connect via private interface. Also, to use this feature \fBprivate_networking: True\fP must be set in the config. .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 Additional documentation is available from \fI\%DigitalOcean\fP\&. .UNINDENT .UNINDENT .SS Getting Started With Dimension Data Cloud .sp Dimension Data are a global IT Services company and form part of the NTT Group. Dimension Data provide IT\-as\-a\-Service to customers around the globe on their cloud platform (Compute as a Service). The CaaS service is available either on one of the public cloud instances or as a private instance on premises. .sp \fI\%http://cloud.dimensiondata.com/\fP .sp CaaS has its own non\-standard .nf \(gaAPI\(ga_ .fi , SaltStack provides a wrapper on top of this .nf \(gaAPI\(ga_ .fi with common methods with other IaaS solutions and Public cloud providers. Therefore, you can use use the Dimension Data module to communicate with both the public and private clouds. .SS Dependencies .sp This driver requires the Python \fBapache\-libcloud\fP and \fBnetaddr\fP library to be installed. .SS Configuration .sp When you instantiate a driver you need to pass the following arguments to the driver constructor: .INDENT 0.0 .IP \(bu 2 \fBuser_id\fP \- Your Dimension Data Cloud username .IP \(bu 2 \fBkey\fP \- Your Dimension Data Cloud password .IP \(bu 2 \fBregion\fP \- The region key, one of the possible region keys .UNINDENT .sp Possible regions: .INDENT 0.0 .IP \(bu 2 \fBdd\-na\fP : Dimension Data North America (USA) .IP \(bu 2 \fBdd\-eu\fP : Dimension Data Europe .IP \(bu 2 \fBdd\-af\fP : Dimension Data Africa .IP \(bu 2 \fBdd\-au\fP : Dimension Data Australia .IP \(bu 2 \fBdd\-latam\fP : Dimension Data Latin America .IP \(bu 2 \fBdd\-ap\fP : Dimension Data Asia Pacific .IP \(bu 2 \fBdd\-canada\fP : Dimension Data Canada region .UNINDENT .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\-dimensiondata\-config: user_id: my_username key: myPassword! region: dd\-na driver: dimensiondata .ft P .fi .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 Changed in version 2015.8.0. .sp The \fBprovider\fP parameter in cloud provider definitions was renamed to \fBdriver\fP\&. This change was made to avoid confusion with the \fBprovider\fP parameter that is used in cloud profile definitions. Cloud provider definitions now use \fBdriver\fP to refer to the Salt cloud module that provides the underlying functionality to connect to a cloud host, while cloud profiles continue to use \fBprovider\fP to refer to provider configurations that you define. .UNINDENT .UNINDENT .SS Profiles .SS Cloud Profiles .sp Dimension Data images have an inbuilt size configuration, there is no list of sizes (although, if the command \-\-list\-sizes is run a default will be returned). .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\-dimensiondata\-config my\-dimensiondata\-config: \-\-\-\-\-\-\-\-\-\- dimensiondata: \-\-\-\-\-\-\-\-\-\- CSfM SharePoint 2013 Trial: \-\-\-\-\-\-\-\-\-\- driver: extra: \-\-\-\-\-\-\-\-\-\- OS_displayName: WIN2012R2S/64 OS_type: None cpu: created: 2015\-03\-19T18:36:06.000Z description: Windows 2012 R2 Standard 64\-bit installed with SharePoint 2013 and Visual Studio 2013 Pro (Trial Version) location: memoryGb: 12 osImageKey: T\-WIN\-2012R2\-STD\-SP2013\-VS2013\-64\-4\-12\-100 get_uuid: id: 0df4677e\-d380\-4e9b\-9469\-b529ee0214c5 name: CSfM SharePoint 2013 Trial uuid: 28c077f1be970ee904541407b377e3ff87a9ac69 CentOS 5 32\-bit 2 CPU: \-\-\-\-\-\-\-\-\-\- driver: extra: \-\-\-\-\-\-\-\-\-\- OS_displayName: CENTOS5/32 OS_type: None cpu: created: 2015\-10\-21T14:52:29.000Z description: CentOS Release 5.11 32\-bit location: memoryGb: 4 osImageKey: T\-CENT\-5\-32\-2\-4\-10 get_uuid: id: a8046bd1\-04ea\-4668\-bf32\-bf8d5540faed name: CentOS 5 32\-bit 2 CPU uuid: 4d7dd59929fed6f4228db861b609da64997773a7 \&...SNIP... .ft P .fi .UNINDENT .UNINDENT .sp Locations can be obtained using the \fB\-\-list\-locations\fP option for the \fBsalt\-cloud\fP command: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C my\-dimensiondata\-config: \-\-\-\-\-\-\-\-\-\- dimensiondata: \-\-\-\-\-\-\-\-\-\- Australia \- Melbourne: \-\-\-\-\-\-\-\-\-\- country: Australia driver: id: AU2 name: Australia \- Melbourne Australia \- Melbourne MCP2: \-\-\-\-\-\-\-\-\-\- country: Australia driver: id: AU10 name: Australia \- Melbourne MCP2 Australia \- Sydney: \-\-\-\-\-\-\-\-\-\- country: Australia driver: id: AU1 name: Australia \- Sydney Australia \- Sydney MCP2: \-\-\-\-\-\-\-\-\-\- country: Australia driver: id: AU9 name: Australia \- Sydney MCP2 New Zealand: \-\-\-\-\-\-\-\-\-\- country: New Zealand driver: id: AU8 name: New Zealand New_Zealand: \-\-\-\-\-\-\-\-\-\- country: New Zealand driver: id: AU11 name: New_Zealand .ft P .fi .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 Dimension Data Cloud REST API documentation is available from \fI\%Dimension Data MCP 2\fP\&. .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 driver for AWS EC2 was the \fBaws\fP driver. This has been deprecated in favor of the \fBec2\fP driver. Configuration using the old \fBaws\fP driver will still function, but that driver is no longer in active development. .SS Dependencies .sp This driver requires the Python \fBrequests\fP library to be installed. .SS Configuration .sp The following example illustrates some of the options that can be set. These parameters are discussed in more detail below. .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\-cloud command is run inside the EC2 # public_ips \- The salt\-cloud command is run outside of EC2 # ssh_interface: public_ips # Optionally configure the Windows credential validation number of # retries and delay between retries. This defaults to 10 retries # with a one second delay betwee retries win_deploy_auth_retries: 10 win_deploy_auth_retry_delay: 1 # Set the EC2 access credentials (see below) # id: \(aquse\-instance\-role\-credentials\(aq key: \(aquse\-instance\-role\-credentials\(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 # Use salt\-cloud \-\-list\-locations to obtain valid regions # 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 driver: 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 # Optionally configure the Windows credential validation number of # retries and delay between retries. This defaults to 10 retries # with a one second delay betwee retries win_deploy_auth_retries: 10 win_deploy_auth_retry_delay: 1 # Set the EC2 access credentials (see below) # id: \(aquse\-instance\-role\-credentials\(aq key: \(aquse\-instance\-role\-credentials\(aq # Make sure this key is owned by root with permissions 0400. # private_key: /etc/salt/my_test_key.pem keyname: my_test_key # This one should NOT be specified if VPC was not configured in AWS to be # the default. It might cause an error message which says that network # interfaces and an instance\-level security groups may not be specified # on the same request. # 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 driver: ec2 .ft P .fi .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 Changed in version 2015.8.0. .sp The \fBprovider\fP parameter in cloud provider definitions was renamed to \fBdriver\fP\&. This change was made to avoid confusion with the \fBprovider\fP parameter that is used in cloud profile definitions. Cloud provider definitions now use \fBdriver\fP to refer to the Salt cloud module that provides the underlying functionality to connect to a cloud host, while cloud profiles continue to use \fBprovider\fP to refer to provider configurations that you define. .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. .sp Note: if either \fBid\fP or \fBkey\fP is set to \(aquse\-instance\-role\-credentials\(aq it is assumed that Salt is running on an AWS instance, and the instance role credentials will be retrieved and used. Since both the \fBid\fP and \fBkey\fP are required parameters for the AWS ec2 provider, it is recommended to set both to \(aquse\-instance\-role\-credentials\(aq for this functionality. .sp A "static" and "permanent" Access Key ID and Secret Key can be specified, but this is not recommended. Instance role keys are rotated on a regular basis, and are the recommended method of specifying AWS credentials. .SS Windows Deploy Timeouts .sp For Windows instances, it may take longer than normal for the instance to be ready. In these circumstances, the provider configuration can be configured with a \fBwin_deploy_auth_retries\fP and/or a \fBwin_deploy_auth_retry_delay\fP setting, which default to 10 retries and a one second delay between retries. These retries and timeouts relate to validating the Administrator password once AWS provides the credentials via the AWS API. .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 accessible 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\-step configuration process: .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 .INDENT 0.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: t2.micro ssh_username: ec2\-user base_ec2_public: provider: my\-ec2\-southeast\-public\-ips image: ami\-e565ba8c size: t2.micro 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 } \- { size: 10, device: /dev/sdi, tags: {"Environment": "production"} } # optionally add tags to profile: tag: {\(aqEnvironment\(aq: \(aqproduction\(aq, \(aqRole\(aq: \(aqdatabase\(aq} # force grains to sync after install sync_after_install: grains base_ec2_vpc: provider: my\-ec2\-southeast\-public\-ips image: ami\-a73264ce size: m1.xlarge ssh_username: ec2\-user script: /etc/salt/cloud.deploy.d/user_data.sh network_interfaces: \- DeviceIndex: 0 PrivateIpAddresses: \- Primary: True #auto assign public ip (not EIP) AssociatePublicIpAddress: True SubnetId: subnet\-813d4bbf SecurityGroupId: \- sg\-750af413 del_root_vol_on_destroy: True del_all_vol_on_destroy: True volumes: \- { size: 10, device: /dev/sdf } \- { size: 10, device: /dev/sdg, type: io1, iops: 1000 } \- { size: 10, device: /dev/sdh, type: io1, iops: 1000 } tag: {\(aqEnvironment\(aq: \(aqproduction\(aq, \(aqRole\(aq: \(aqdatabase\(aq} sync_after_install: grains .ft P .fi .UNINDENT .UNINDENT .sp The profile can now be realized 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 driver: ec2 .ft P .fi .UNINDENT .UNINDENT .SS Optional Settings .sp EC2 allows a userdata file to be passed to the instance to be created. This functionality was added to Salt in the 2015.5.0 release. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C my\-ec2\-config: # Pass userdata to the instance to be created userdata_file: /etc/salt/my\-userdata\-file .ft P .fi .UNINDENT .UNINDENT .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 EC2 instances can be added to an \fI\%AWS Placement Group\fP by specifying the \fBplacementgroup\fP option: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C my\-ec2\-config: placementgroup: my\-aws\-placement\-group .ft P .fi .UNINDENT .UNINDENT .sp Your instances may optionally make use of EC2 Spot Instances. The following example will request that spot instances be used and your maximum bid will be $0.10. Keep in mind that different spot prices may be needed based on the current value of the various EC2 instance sizes. You can check current and past spot instance pricing via the EC2 API or AWS Console. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C my\-ec2\-config: spot_config: spot_price: 0.10 .ft P .fi .UNINDENT .UNINDENT .sp By default, the spot instance type is set to \(aqone\-time\(aq, meaning it will be launched and, if it\(aqs ever terminated for whatever reason, it will not be recreated. If you would like your spot instances to be relaunched after a termination (by your or AWS), set the \fBtype\fP to \(aqpersistent\(aq. .sp NOTE: Spot instances are a great way to save a bit of money, but you do run the risk of losing your spot instances if the current price for the instance size goes above your maximum bid. .sp The following parameters may be set in the cloud configuration file to control various aspects of the spot instance launching: .INDENT 0.0 .IP \(bu 2 \fBwait_for_spot_timeout\fP: seconds to wait before giving up on spot instance launch (default=600) .IP \(bu 2 \fBwait_for_spot_interval\fP: seconds to wait in between polling requests to determine if a spot instance is available (default=30) .IP \(bu 2 \fBwait_for_spot_interval_multiplier\fP: a multiplier to add to the interval in between requests, which is useful if AWS is throttling your requests (default=1) .IP \(bu 2 \fBwait_for_spot_max_failures\fP: maximum number of failures before giving up on launching your spot instance (default=10) .UNINDENT .sp If you find that you\(aqre being throttled by AWS while polling for spot instances, you can set the following in your core cloud configuration file that will double the polling interval after each request to AWS. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C wait_for_spot_interval: 1 wait_for_spot_interval_multiplier: 2 .ft P .fi .UNINDENT .UNINDENT .sp See the \fI\%AWS Spot Instances\fP documentation for more information. .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, and device names. .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 provisioning 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 Ebs.VolumeType: gp2 Ebs.SnapshotId: dummy0 \- DeviceName: /dev/sdb # required for devices > 2TB Ebs.VolumeType: gp2 Ebs.VolumeSize: 3001 .ft P .fi .UNINDENT .UNINDENT .sp Existing EBS volumes may also be attached (not created) to your instances or you can create new EBS volumes based on EBS snapshots. To simply attach an existing volume use the \fBvolume_id\fP parameter. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C device: /dev/xvdj volume_id: vol\-12345abcd .ft P .fi .UNINDENT .UNINDENT .sp Or, to create a volume from an EBS snapshot, use the \fBsnapshot\fP parameter. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C device: /dev/xvdj snapshot: snap\-abcd12345 .ft P .fi .UNINDENT .UNINDENT .sp Note that \fBvolume_id\fP will take precedence over the \fBsnapshot\fP parameter. .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 tag1: value .ft P .fi .UNINDENT .UNINDENT .SS Setting up a Master inside EC2 .sp Salt Cloud can configure Salt Masters as well as Minions. Use the \fBmake_master\fP setting to use this functionality. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C my\-ec2\-config: # Optionally install a Salt Master in addition to the Salt Minion make_master: True .ft P .fi .UNINDENT .UNINDENT .sp When creating a Salt Master inside EC2 with \fBmake_master: True\fP, or when the Salt Master is already located and configured inside EC2, by default, minions connect to the master\(aqs public IP address during Salt Cloud\(aqs provisioning process. Depending on how your security groups are defined, the minions may or may not be able to communicate with the master. In order to use the master\(aqs private IP in EC2 instead of the public IP, set the \fBsalt_interface\fP to \fBprivate_ips\fP\&. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C my\-ec2\-config: # Optionally set the IP configuration to private_ips salt_interface: private_ips .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 .sp It is possible to manage tags on any resource in EC2 with a Resource ID, not just instances: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-f get_tags my_ec2 resource_id=af5467ba salt\-cloud \-f set_tags my_ec2 resource_id=af5467ba tag1=somestuff salt\-cloud \-f del_tags my_ec2 resource_id=af5467ba 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 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 retains 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 .UNINDENT .INDENT 0.0 .IP \(bu 2 \fI\%FreeBSD\fP .UNINDENT .INDENT 0.0 .IP \(bu 2 \fI\%Fedora\fP .UNINDENT .INDENT 0.0 .IP \(bu 2 \fI\%CentOS\fP .UNINDENT .INDENT 0.0 .IP \(bu 2 \fI\%Ubuntu\fP .UNINDENT .INDENT 0.0 .IP \(bu 2 \fI\%Debian\fP .UNINDENT .INDENT 0.0 .IP \(bu 2 \fI\%OmniOS\fP .UNINDENT .INDENT 0.0 .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 \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 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. .sp The following parameters may also be set (when providing a snapshot OR size): .INDENT 0.0 .IP \(bu 2 \fBtype\fP: choose between standard (magnetic disk), gp2 (SSD), or io1 (provisioned IOPS). (default=standard) .IP \(bu 2 \fBiops\fP: the number of IOPS (only applicable to io1 volumes) (default varies on volume size) .IP \(bu 2 \fBencrypted\fP: enable encryption on the volume (default=false) .UNINDENT .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=gp2 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, 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 Importing a Key Pair .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-f import_keypair ec2 keyname=mykeypair file=/path/to/id_rsa.pub .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 Launching instances into a VPC .SS Simple launching into a VPC .sp In the amazon web interface, identify the id or the name of the subnet into which your image should be created. Then, edit your cloud.profiles file like so:\- .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C profile\-id: provider: provider\-name subnetid: subnet\-XXXXXXXX image: ami\-XXXXXXXX size: m1.medium ssh_username: ubuntu securitygroupid: \- sg\-XXXXXXXX securitygroupname: \- AnotherSecurityGroup \- AndThirdSecurityGroup .ft P .fi .UNINDENT .UNINDENT .sp Note that \(aqsubnetid\(aq takes precedence over \(aqsubnetname\(aq, but \(aqsecuritygroupid\(aq and \(aqsecuritygroupname\(aq are merged toghether to generate a single list for SecurityGroups of instances. .SS Specifying interface properties .sp New in version 2014.7.0. .sp Launching into a VPC allows you to specify more complex configurations for the network interfaces of your virtual machines, for example:\- .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C profile\-id: provider: provider\-name image: ami\-XXXXXXXX size: m1.medium ssh_username: ubuntu # Do not include either \(aqsubnetid\(aq, \(aqsubnetname\(aq, \(aqsecuritygroupid\(aq or # \(aqsecuritygroupname\(aq here if you are going to manually specify # interface configuration # network_interfaces: \- DeviceIndex: 0 SubnetId: subnet\-XXXXXXXX SecurityGroupId: \- sg\-XXXXXXXX # Uncomment this line if you would like to set an explicit private # IP address for the ec2 instance # # PrivateIpAddress: 192.168.1.66 # Uncomment this to associate an existing Elastic IP Address with # this network interface: # # associate_eip: eipalloc\-XXXXXXXX # You can allocate more than one IP address to an interface. Use the # \(aqip addr list\(aq command to see them. # # SecondaryPrivateIpAddressCount: 2 # Uncomment this to allocate a new Elastic IP Address to this # interface (will be associated with the primary private ip address # of the interface # # allocate_new_eip: True # Uncomment this instead to allocate a new Elastic IP Address to # both the primary private ip address and each of the secondary ones # allocate_new_eips: True # Uncomment this if you\(aqre creating NAT instances. Allows an instance # to accept IP packets with destinations other than itself. # SourceDestCheck: False .ft P .fi .UNINDENT .UNINDENT .sp Note that it is an error to assign a \(aqsubnetid\(aq, \(aqsubnetname\(aq, \(aqsecuritygroupid\(aq or \(aqsecuritygroupname\(aq to a profile where the interfaces are manually configured like this. These are both really properties of each network interface, not of the machine itself. .SS Getting Started With GoGrid .sp GoGrid is a public cloud host that supports Linux and Windows. .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: driver: gogrid apikey: asdff7896asdh789 sharedsecret: saltybacon .ft P .fi .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 A Note about using Map files with GoGrid: .sp Due to limitations in the GoGrid API, instances cannot be provisioned in parallel with the GoGrid driver. Map files will work with GoGrid, but the \fB\-P\fP argument should not be used on maps referencing GoGrid instances. .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 Changed in version 2015.8.0. .sp The \fBprovider\fP parameter in cloud provider definitions was renamed to \fBdriver\fP\&. This change was made to avoid confusion with the \fBprovider\fP parameter that is used in cloud profile definitions. Cloud provider definitions now use \fBdriver\fP to refer to the Salt cloud module that provides the underlying functionality to connect to a cloud host, while cloud profiles continue to use \fBprovider\fP to refer to provider configurations that you define. .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 Assigning IPs .sp New in version 2015.8.0. .sp The GoGrid API allows IP addresses to be manually assigned. Salt Cloud supports this functionality by allowing an IP address to be specified using the \fBassign_public_ip\fP argument. This likely makes the most sense inside a map file, but it may also be used inside a profile. .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 assign_public_ip: 11.38.257.42 .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 LibCloud >= 0.14.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 .sp 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 .sp 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 .sp In your Project, either just click \fICompute Engine\fP to the left, or 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 .sp To set up authorization, navigate to \fIAPIs & auth\fP section and then the \fICredentials\fP link and click the \fICREATE NEW CLIENT ID\fP button. Select \fIService Account\fP and click the \fICreate Client ID\fP button. This will automatically download a \fB\&.json\fP file, which may or may not be used in later steps, depending on your version of \fBlibcloud\fP\&. .sp Look for a new \fIService Account\fP section in the page and record the generated email address for the matching key/fingerprint. The email address will be used in the \fBservice_account_email_address\fP of the \fB/etc/salt/cloud.providers\fP or the \fB/etc/salt/cloud.providers.d/*.conf\fP file. .IP 5. 3 Key Format .sp \fBNOTE:\fP .INDENT 3.0 .INDENT 3.5 If you are using \fBlibcloud >= 0.17.0\fP it is recommended that you use the \fBJSON format\fP file you downloaded above and skip to the \fI\%Provider Configuration\fP section below, using the JSON file \fBin place of \(aqNEW.pem\(aq\fP in the documentation. .sp If you are using an older version of libcloud or are unsure of the version you have, please follow the instructions below to generate and format a new P12 key. .UNINDENT .UNINDENT .sp In the new \fIService Account\fP section, click \fIGenerate new P12 key\fP, which will automatically download a \fB\&.p12\fP private key file. The \fB\&.p12\fP private key needs to be converted to a format compatible with libcloud. This new 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 the \fB/etc/salt/cloud\fP file: .INDENT 3.0 .INDENT 3.5 .sp .nf .ft C openssl pkcs12 \-in ORIG.p12 \-passin pass:notasecret \e \-nodes \-nocerts | openssl rsa \-out NEW.pem .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS Provider Configuration .sp Set up the provider cloud config at \fB/etc/salt/cloud.providers\fP or \fB/etc/salt/cloud.providers.d/*.conf\fP: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C gce\-config: # Set up the Project name and Service Account authorization project: "your\-project\-id" 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 driver: gce .ft P .fi .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 The value provided for \fBproject\fP must not contain underscores or spaces and is labeled as "Project ID" on the Google Developers Console. .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 Changed in version 2015.8.0. .sp The \fBprovider\fP parameter in cloud provider definitions was renamed to \fBdriver\fP\&. This change was made to avoid confusion with the \fBprovider\fP parameter that is used in cloud profile definitions. Cloud provider definitions now use \fBdriver\fP to refer to the Salt cloud module that provides the underlying functionality to connect to a cloud host, while cloud profiles continue to use \fBprovider\fP to refer to provider configurations that you define. .UNINDENT .UNINDENT .SS Profile Configuration .sp Set up an initial profile at \fB/etc/salt/cloud.profiles\fP or \fB/etc/salt/cloud.profiles.d/*.conf\fP: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C my\-gce\-profile: 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 my\-gce\-profile 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 a salt\-minion installed, connectivity to it can be verified with Salt: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt gce\-instance 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. .SS Initial Profile .sp Set up an initial profile at \fB/etc/salt/cloud.profiles\fP or \fB/etc/salt/cloud.profiles.d/gce.conf\fP: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C my\-gce\-profile: 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 ssh_interface: public_ips external_ip: "ephemeral" .ft P .fi .UNINDENT .UNINDENT .SS image .sp Image is used to define what Operating System image should be used to for the instance. Examples are Debian 7 (wheezy) and CentOS 6. Required. .SS size .sp 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. Required. .SS location .sp 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). Required. .SS network .sp 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. .SS tags .sp 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. .SS metadata .sp 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. .SS use_persistent_disk .sp 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. .SS delete_boot_pd .sp 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. .SS ssh_interface .sp New in version 2015.5.0. .sp Specify whether to use public or private IP for deploy script. .sp Valid options are: .INDENT 0.0 .IP \(bu 2 private_ips: The salt\-master is also hosted with GCE .IP \(bu 2 public_ips: The salt\-master is hosted outside of GCE .UNINDENT .SS external_ip .sp Per instance setting: Used a named fixed IP address to this host. .sp Valid options are: .INDENT 0.0 .IP \(bu 2 ephemeral: The host will use a GCE ephemeral IP .IP \(bu 2 None: No external IP will be configured on this host. .UNINDENT .sp Optionally, pass the name of a GCE address to use a fixed IP address. If the address does not already exist, it will be created. .SS ex_disk_type .sp GCE supports two different disk types, \fBpd\-standard\fP and \fBpd\-ssd\fP\&. The default disk type setting is \fBpd\-standard\fP\&. To specify using an SSD disk, set \fBpd\-ssd\fP as the value. .sp New in version 2014.7.0. .SS ip_forwarding .sp GCE instances can be enabled to use IP Forwarding. When set to \fBTrue\fP, this options allows the instance to send/receive non\-matching src/dst packets. Default is \fBFalse\fP\&. .sp New in version 2015.8.1. .SS Profile with scopes .sp Scopes can be specified by setting the optional \fBex_service_accounts\fP key in your cloud profile. The following example enables the bigquery scope. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C my\-gce\-profile: image: centos\-6 ssh_username: salt size: f1\-micro location: us\-central1\-a network: default tags: \(aq["one", "two", "three"]\(aq metadata: \(aq{"one": "1", "2": "two", "sshKeys": ""}\(aq use_persistent_disk: True delete_boot_pd: False deploy: False make_master: False provider: gce\-config ex_service_accounts: \- scopes: \- bigquery .ft P .fi .UNINDENT .UNINDENT .sp Email can also be specified as an (optional) parameter. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C my\-gce\-profile: \&...snip ex_service_accounts: \- scopes: \- bigquery email: default .ft P .fi .UNINDENT .UNINDENT .sp There can be multiple entries for scopes since \fBex\-service_accounts\fP accepts a list of dictionaries. For more information refer to the libcloud documentation on \fI\%specifying service account scopes\fP\&. .SS SSH Remote Access .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. Append something like this to \fB/etc/salt/cloud.profiles\fP or \fB/etc/salt/cloud.profiles.d/*.conf\fP: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C my\-gce\-profile: ... # SSH to GCE instances as gceuser ssh_username: gceuser # Use the local private SSH key file located here ssh_keyfile: /etc/cloud/google_compute_engine .ft P .fi .UNINDENT .UNINDENT .sp If you have not already used this SSH key to login to instances in this GCE project you will also need to add the public key to your projects metadata at \fI\%https://cloud.google.com/console\fP\&. You could also add it via the metadata setting too: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C my\-gce\-profile: ... metadata: \(aq{"one": "1", "2": "two", "sshKeys": "gceuser:ssh\-rsa gceuser@host"}\(aq .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 Persistent Disk .sp The Compute Engine provider provides functions via salt\-cloud to manage your Persistent Disks. You can create and destroy disks as well as attach and detach them from running instances. .SS Create .sp When creating a disk, you can create an empty disk and specify its size (in GB), or specify either an \(aqimage\(aq or \(aqsnapshot\(aq. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-f create_disk gce disk_name=pd location=us\-central1\-b size=200 .ft P .fi .UNINDENT .UNINDENT .SS Delete .sp Deleting a disk only requires the name of the disk to delete .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-f delete_disk gce disk_name=old\-backup .ft P .fi .UNINDENT .UNINDENT .SS Attach .sp Attaching a disk to an existing instance is really an \(aqaction\(aq and requires both an instance name and disk name. It\(aqs possible to use this ation to create bootable persistent disks if necessary. Compute Engine also supports attaching a persistent disk in READ_ONLY mode to multiple instances at the same time (but then cannot be attached in READ_WRITE to any instance). .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-a attach_disk myinstance disk_name=pd mode=READ_WRITE boot=yes .ft P .fi .UNINDENT .UNINDENT .SS Detach .sp Detaching a disk is also an action against an instance and only requires the name of the disk. Note that this does \fInot\fP safely sync and umount the disk from the instance. To ensure no data loss, you must first make sure the disk is unmounted from the instance. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-a detach_disk myinstance disk_name=pd .ft P .fi .UNINDENT .UNINDENT .SS Show disk .sp It\(aqs also possible to look up the details for an existing disk with either a function or an action. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-a show_disk myinstance disk_name=pd salt\-cloud \-f show_disk gce disk_name=pd .ft P .fi .UNINDENT .UNINDENT .SS Create snapshot .sp You can take a snapshot of an existing disk\(aqs content. The snapshot can then in turn be used to create other persistent disks. Note that to prevent data corruption, it is strongly suggested that you unmount the disk prior to taking a snapshot. You must name the snapshot and provide the name of the disk. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-f create_snapshot gce name=backup\-20140226 disk_name=pd .ft P .fi .UNINDENT .UNINDENT .SS Delete snapshot .sp You can delete a snapshot when it\(aqs no longer needed by specifying the name of the snapshot. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-f delete_snapshot gce name=backup\-20140226 .ft P .fi .UNINDENT .UNINDENT .SS Show snapshot .sp Use this function to look up information about the snapshot. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-f show_snapshot gce name=backup\-20140226 .ft P .fi .UNINDENT .UNINDENT .SS Networking .sp Compute Engine supports multiple private networks per project. Instances within a private network can easily communicate with each other by an internal DNS service that resolves instance names. Instances within a private network can also communicate with either directly without needing special routing or firewall rules even if they span different regions/zones. .sp Networks also support custom firewall rules. By default, traffic between instances on the same private network is open to all ports and protocols. Inbound SSH traffic (port 22) is also allowed but all other inbound traffic is blocked. .SS Create network .sp New networks require a name and CIDR range. New instances can be created and added to this network by setting the network name during create. It is not possible to add/remove existing instances to a network. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-f create_network gce name=mynet cidr=10.10.10.0/24 .ft P .fi .UNINDENT .UNINDENT .SS Destroy network .sp Destroy a network by specifying the name. Make sure that there are no instances associated with the network prior to deleting it or you\(aqll have a bad day. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-f delete_network gce name=mynet .ft P .fi .UNINDENT .UNINDENT .SS Show network .sp Specify the network name to view information about the network. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-f show_network gce name=mynet .ft P .fi .UNINDENT .UNINDENT .SS Create address .sp Create a new named static IP address in a region. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-f create_address gce name=my\-fixed\-ip region=us\-central1 .ft P .fi .UNINDENT .UNINDENT .SS Delete address .sp Delete an existing named fixed IP address. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-f delete_address gce name=my\-fixed\-ip region=us\-central1 .ft P .fi .UNINDENT .UNINDENT .SS Show address .sp View details on a named address. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-f show_address gce name=my\-fixed\-ip region=us\-central1 .ft P .fi .UNINDENT .UNINDENT .SS Create firewall .sp You\(aqll need to create custom firewall rules if you want to allow other traffic than what is described above. For instance, if you run a web service on your instances, you\(aqll need to explicitly allow HTTP and/or SSL traffic. The firewall rule must have a name and it will use the \(aqdefault\(aq network unless otherwise specified with a \(aqnetwork\(aq attribute. Firewalls also support instance tags for source/destination .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-f create_fwrule gce name=web allow=tcp:80,tcp:443,icmp .ft P .fi .UNINDENT .UNINDENT .SS Delete firewall .sp Deleting a firewall rule will prevent any previously allowed traffic for the named firewall rule. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-f delete_fwrule gce name=web .ft P .fi .UNINDENT .UNINDENT .SS Show firewall .sp Use this function to review an existing firewall rule\(aqs information. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-f show_fwrule gce name=web .ft P .fi .UNINDENT .UNINDENT .SS Load Balancer .sp Compute Engine possess a load\-balancer feature for splitting traffic across multiple instances. Please reference the \fI\%documentation\fP for a more complete description. .sp The load\-balancer functionality is slightly different than that described in Google\(aqs documentation. The concept of \fITargetPool\fP and \fIForwardingRule\fP are consolidated in salt\-cloud/libcloud. HTTP Health Checks are optional. .SS HTTP Health Check .sp HTTP Health Checks can be used as a means to toggle load\-balancing across instance members, or to detect if an HTTP site is functioning. A common use\-case is to set up a health check URL and if you want to toggle traffic on/off to an instance, you can temporarily have it return a non\-200 response. A non\-200 response to the load\-balancer\(aqs health check will keep the LB from sending any new traffic to the "down" instance. Once the instance\(aqs health check URL beings returning 200\-responses, the LB will again start to send traffic to it. Review Compute Engine\(aqs documentation for allowable parameters. You can use the following salt\-cloud functions to manage your HTTP health checks. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-f create_hc gce name=myhc path=/ port=80 salt\-cloud \-f delete_hc gce name=myhc salt\-cloud \-f show_hc gce name=myhc .ft P .fi .UNINDENT .UNINDENT .SS Load\-balancer .sp When creating a new load\-balancer, it requires a name, region, port range, and list of members. There are other optional parameters for protocol, and list of health checks. Deleting or showing details about the LB only requires the name. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-f create_lb gce name=lb region=... ports=80 members=w1,w2,w3 salt\-cloud \-f delete_lb gce name=lb salt\-cloud \-f show_lb gce name=lb .ft P .fi .UNINDENT .UNINDENT .sp You can also create a load balancer using a named fixed IP addressby specifying the name of the address. If the address does not exist yet it will be created. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-f create_lb gce name=my\-lb region=us\-central1 ports=234 members=s1,s2,s3 address=my\-lb\-ip .ft P .fi .UNINDENT .UNINDENT .SS Attach and Detach LB .sp It is possible to attach or detach an instance from an existing load\-balancer. Both the instance and load\-balancer must exist before using these functions. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-f attach_lb gce name=lb member=w4 salt\-cloud \-f detach_lb gce name=lb member=oops .ft P .fi .UNINDENT .UNINDENT .SS Getting Started With HP Cloud .sp HP Cloud is a major public cloud platform and uses the libcloud \fIopenstack\fP driver. The current version of OpenStack that HP Cloud uses is Havana. When an instance is booted, it must have a floating IP added to it in order to connect to it and further below you will see an example that adds context to this statement. .SS Set up a cloud provider configuration file .sp To use the \fIopenstack\fP driver for HP Cloud, set up the cloud provider configuration file as in the example shown below: .sp \fB/etc/salt/cloud.providers.d/hpcloud.conf\fP: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C hpcloud\-config: # Set the location of the salt\-master # minion: master: saltmaster.example.com # Configure HP Cloud using the OpenStack plugin # identity_url: https://region\-b.geo\-1.identity.hpcloudsvc.com:35357/v2.0/tokens compute_name: Compute protocol: ipv4 # Set the compute region: # compute_region: region\-b.geo\-1 # Configure HP Cloud authentication credentials # user: myname tenant: myname\-project1 password: xxxxxxxxx # keys to allow connection to the instance launched # ssh_key_name: yourkey ssh_key_file: /path/to/key/yourkey.priv driver: openstack .ft P .fi .UNINDENT .UNINDENT .sp The subsequent example that follows is using the openstack driver. .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 Changed in version 2015.8.0. .sp The \fBprovider\fP parameter in cloud provider definitions was renamed to \fBdriver\fP\&. This change was made to avoid confusion with the \fBprovider\fP parameter that is used in cloud profile definitions. Cloud provider definitions now use \fBdriver\fP to refer to the Salt cloud module that provides the underlying functionality to connect to a cloud host, while cloud profiles continue to use \fBprovider\fP to refer to provider configurations that you define. .UNINDENT .UNINDENT .SS Compute Region .sp Originally, HP Cloud, in its OpenStack Essex version (1.0), had 3 availability zones in one region, US West (region\-a.geo\-1), which each behaved each as a region. .sp This has since changed, and the current OpenStack Havana version of HP Cloud (1.1) now has simplified this and now has two regions to choose from: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C region\-a.geo\-1 \-> US West region\-b.geo\-1 \-> US East .ft P .fi .UNINDENT .UNINDENT .SS Authentication .sp The \fBuser\fP is the same user as is used to log into the HP Cloud management UI. The \fBtenant\fP can be found in the upper left under "Project/Region/Scope". It is often named the same as \fBuser\fP albeit with a \fB\-project1\fP appended. The \fBpassword\fP is of course what you created your account with. The management UI also has other information such as being able to select US East or US West. .SS Set up a cloud profile config file .sp The profile shown below is a know working profile for an Ubuntu instance. The profile configuration file is stored in the following location: .sp \fB/etc/salt/cloud.profiles.d/hp_ae1_ubuntu.conf\fP: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C hp_ae1_ubuntu: provider: hp_ae1 image: 9302692b\-b787\-4b52\-a3a6\-daebb79cb498 ignore_cidr: 10.0.0.1/24 networks: \- floating: Ext\-Net size: standard.small ssh_key_file: /root/keys/test.key ssh_key_name: test ssh_username: ubuntu .ft P .fi .UNINDENT .UNINDENT .sp Some important things about the example above: .INDENT 0.0 .IP \(bu 2 The \fBimage\fP parameter can use either the image name or image ID which you can obtain by running in the example below (this case US East): .UNINDENT .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C # salt\-cloud \-\-list\-images hp_ae1 .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .IP \(bu 2 The parameter \fBignore_cidr\fP specifies a range of addresses to ignore when trying to connect to the instance. In this case, it\(aqs the range of IP addresses used for an private IP of the instance. .IP \(bu 2 The parameter \fBnetworks\fP is very important to include. In previous versions of Salt Cloud, this is what made it possible for salt\-cloud to be able to attach a floating IP to the instance in order to connect to the instance and set up the minion. The current version of salt\-cloud doesn\(aqt require it, though having it is of no harm either. Newer versions of salt\-cloud will use this, and without it, will attempt to find a list of floating IP addresses to use regardless. .IP \(bu 2 The \fBssh_key_file\fP and \fBssh_key_name\fP are the keys that will make it possible to connect to the instance to set up the minion .IP \(bu 2 The \fBssh_username\fP parameter, in this case, being that the image used will be ubuntu, will make it possible to not only log in but install the minion .UNINDENT .SS Launch an instance .sp To instantiate a machine based on this profile (example): .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C # salt\-cloud \-p hp_ae1_ubuntu ubuntu_instance_1 .ft P .fi .UNINDENT .UNINDENT .sp After several minutes, this will create an instance named ubuntu_instance_1 running in HP Cloud in the US East region and will set up the minion and then return information about the instance once completed. .SS Manage the instance .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 ubuntu_instance_1 ping .ft P .fi .UNINDENT .UNINDENT .SS SSH to the instance .sp Additionally, the instance can be accessed via SSH using the floating IP assigned to it .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C # ssh ubuntu@ .ft P .fi .UNINDENT .UNINDENT .SS Using a private IP .sp Alternatively, in the cloud profile, using the private IP to log into the instance to set up the minion is another option, particularly if salt\-cloud is running within the cloud on an instance that is on the same network with all the other instances (minions) .sp The example below is a modified version of the previous example. Note the use of \fBssh_interface\fP: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C hp_ae1_ubuntu: provider: hp_ae1 image: 9302692b\-b787\-4b52\-a3a6\-daebb79cb498 size: standard.small ssh_key_file: /root/keys/test.key ssh_key_name: test ssh_username: ubuntu ssh_interface: private_ips .ft P .fi .UNINDENT .UNINDENT .sp With this setup, salt\-cloud will use the private IP address to ssh into the instance and set up the salt\-minion .SS Getting Started With Joyent .sp Joyent is a public cloud host that supports SmartOS, Linux, FreeBSD, and Windows. .SS Dependencies .sp This driver requires the Python \fBrequests\fP library 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: driver: joyent user: fred password: saltybacon private_key: /root/mykey.pem keyname: mykey .ft P .fi .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 Changed in version 2015.8.0. .sp The \fBprovider\fP parameter in cloud provider definitions was renamed to \fBdriver\fP\&. This change was made to avoid confusion with the \fBprovider\fP parameter that is used in cloud profile definitions. Cloud provider definitions now use \fBdriver\fP to refer to the Salt cloud module that provides the underlying functionality to connect to a cloud host, while cloud profiles continue to use \fBprovider\fP to refer to provider configurations that you define. .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: g4\-highcpu\-512M image: ubuntu\-16.04 .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: \-\-\-\-\-\-\-\-\-\- g4\-highcpu\-512M: \-\-\-\-\-\-\-\-\-\- default: False description: Compute Optimized 512M RAM \- 1 vCPU \- 10 GB Disk disk: 10240 group: Compute Optimized id: 14aea8fc\-d0f8\-11e5\-bfe4\-a7458dbc6c99 lwps: 4000 memory: 512 name: g4\-highcpu\-512M swap: 2048 vcpus: 0 version: 1.0.3 \&...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 comfortabl e with setting up their own environment and tools. files: |_ \-\-\-\-\-\-\-\-\-\- compression: gzip sha1: b00a77408ddd9aeac85085b68b1cd22a07353956 size: 106918297 homepage: http://wiki.joyent.com/jpc2/Base+Instance id: 00aec452\-6e81\-11e4\-8474\-ebfec9a1a911 name: base os: smartos owner: 9dce1460\-0c4c\-4417\-ab8b\-25ca478c5a78 public: True published_at: 2014\-11\-17T17:41:46Z requirements: \-\-\-\-\-\-\-\-\-\- state: active type: smartmachine version: 14.3.0 \&...SNIP... .ft P .fi .UNINDENT .UNINDENT .SS SmartDataCenter .sp This driver can also be used with the Joyent SmartDataCenter project. More details can be found at: .sp Using SDC requires that an api_host_suffix is set. The default value for this is \fI\&.api.joyentcloud.com\fP\&. All characters, including the leading \fI\&.\fP, should be included: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C api_host_suffix: .api.myhostname.com .ft P .fi .UNINDENT .UNINDENT .SS Miscellaneous Configuration .sp The following configuration items can be set in either \fBprovider\fP or \fBprofile\fP confuration files. .SS use_ssl .sp When set to \fBTrue\fP (the default), attach \fBhttps://\fP to any URL that does not already have \fBhttp://\fP or \fBhttps://\fP included at the beginning. The best practice is to leave the protocol out of the URL, and use this setting to manage it. .SS verify_ssl .sp When set to \fBTrue\fP (the default), the underlying web library will verify the SSL certificate. This should only be set to \fBFalse\fP for debugging.\(ga .SS Getting Started With Linode .sp Linode is a public cloud host with a focus on Linux instances. .sp Starting with the 2015.8.0 release of Salt, the Linode driver uses Linode\(aqs native REST API. There are no external dependencies required to use the Linode driver, other than a Linode account. .SS Provider Configuration .sp Linode requires a single API key, but the default root password for new instances also needs to be set. The password needs to be eight characters and contain lowercase, uppercase, and numbers. .sp Set up the provider cloud configuration file at \fB/etc/salt/cloud.providers\fP or \fB/etc/salt/cloud.providers.d/*.conf\fP\&. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C my\-linode\-config: apikey: \(aqasldkgfakl;sdfjsjaslfjaklsdjf;askldjfaaklsjdfhasldsadfghdkf\(aq password: \(aqF00barbaz\(aq driver: linode .ft P .fi .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 Changed in version 2015.8.0. .sp The \fBprovider\fP parameter in cloud provider definitions was renamed to \fBdriver\fP\&. This change was made to avoid confusion with the \fBprovider\fP parameter that is used in cloud profile definitions. Cloud provider definitions now use \fBdriver\fP to refer to the Salt cloud module that provides the underlying functionality to connect to a cloud host, while cloud profiles continue to use \fBprovider\fP to refer to provider configurations that you define. .UNINDENT .UNINDENT .SS Profile Configuration .sp Linode profiles require a \fBprovider\fP, \fBsize\fP, \fBimage\fP, and \fBlocation\fP\&. 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 2048 image: CentOS 7 location: London, England, UK .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 linode_1024 linode\-instance .ft P .fi .UNINDENT .UNINDENT .sp This will create an salt minion instance named \fBlinode\-instance\fP in Linode. 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 a salt\-minion installed, connectivity to it can be verified with Salt: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt linode\-instance test.ping .ft P .fi .UNINDENT .UNINDENT .SS Listing Sizes .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: \-\-\-\-\-\-\-\-\-\- AVAIL: \-\-\-\-\-\-\-\-\-\- 10: 500 2: 500 3: 500 4: 500 6: 500 7: 500 8: 500 9: 500 CORES: 1 DISK: 24 HOURLY: 0.015 LABEL: Linode 1024 \&...SNIP... .ft P .fi .UNINDENT .UNINDENT .SS Listing Images .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 2015.02: \-\-\-\-\-\-\-\-\-\- CREATE_DT: 2015\-02\-20 14:17:16.0 DISTRIBUTIONID: 138 IS64BIT: 1 LABEL: Arch Linux 2015.02 MINIMAGESIZE: 800 REQUIRESPVOPSKERNEL: 1 \&...SNIP... .ft P .fi .UNINDENT .UNINDENT .SS Listing Locations .sp Locations can be obtained using the \fB\-\-list\-locations\fP option for the \fBsalt\-cloud\fP command: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C # salt\-cloud \-\-list\-locations my\-linode\-config my\-linode\-config: \-\-\-\-\-\-\-\-\-\- linode: \-\-\-\-\-\-\-\-\-\- Atlanta, GA, USA: \-\-\-\-\-\-\-\-\-\- ABBR: atlanta DATACENTERID: 4 LOCATION: Atlanta, GA, USA \&...SNIP... .ft P .fi .UNINDENT .UNINDENT .SS Linode Specific Settings .sp There are several options outlined below that can be added to either the Linode provider of profile configuration files. Some options are mandatory and are properly labeled below but typically also include a hard\-coded default. .SS image .sp Image is used to define what Operating System image should be used for the instance. Examples are \fBUbuntu 14.04 LTS\fP and \fBCentOS 7\fP\&. This option should be specified in the profile config. Required. .SS location .sp Location is used to define which Linode data center the instance will reside in. Required. .SS size .sp Size is used to define the instance\(aqs "plan type" which includes memory, storage, and price. Required. .SS assign_private_ip .sp New in version 2016.3.0. .sp Assigns a private IP address to a Linode when set to True. Default is False. .SS ssh_interface .sp New in version 2016.3.0. .sp Specify whether to use a public or private IP for the deploy script. Valid options are: .INDENT 0.0 .IP \(bu 2 public_ips: The salt\-master is hosted outside of Linode. Default. .IP \(bu 2 private_ips: The salt\-master is also hosted within Linode. .UNINDENT .sp If specifying \fBprivate_ips\fP, the Linodes must be hosted within the same data center and have the Network Helper enabled on your entire account. The instance that is running the Salt\-Cloud provisioning command must also have a private IP assigned to it. .sp Newer accounts created on Linode have the Network Helper setting enabled by default, account\-wide. Legacy accounts do not have this setting enabled by default. To enable the Network Helper on your Linode account, please see \fI\%Linode\(aqs Network Helper\fP documentation. .sp If you\(aqre running into problems, be sure to restart the instance that is running Salt Cloud after adding its own private IP address or enabling the Network Helper. .SS clonefrom .sp Setting the clonefrom option to a specified instance enables the new instance to be cloned from the named instance instead of being created from scratch. If using the clonefrom option, it is likely a good idea to also specify \fBscript_args: \-C\fP if a minion is already installed on the to\-be\-cloned instance. See the \fI\%Cloning\fP section below for more information. .SS Cloning .sp To clone a Linode, add a profile with a \fBclonefrom\fP key, and a \fBscript_args: \-C\fP\&. \fBclonefrom\fP should be the name of the Linode that is the source for the clone. \fBscript_args: \-C\fP passes a \-C to the salt\-bootstrap script, which only configures the minion and doesn\(aqt try to install a new copy of salt\-minion. This way the minion gets new keys and the keys get pre\-seeded on the master, and the \fB/etc/salt/minion\fP file has the right minion \(aqid:\(aq declaration. .sp Cloning requires a post 2015\-02\-01 salt\-bootstrap. .sp It is safest to clone a stopped machine. To stop a machine run .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-a stop machine_to_clone .ft P .fi .UNINDENT .UNINDENT .sp To create a new machine based on another machine, add an entry to your linode cloud profile that looks like this: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C li\-clone: provider: my\-linode\-config clonefrom: machine_to_clone script_args: \-C \-F .ft P .fi .UNINDENT .UNINDENT .sp Then run salt\-cloud as normal, specifying \fB\-p li\-clone\fP\&. The profile name can be anything; It doesn\(aqt have to be \fBli\-clone\fP\&. .sp \fBclonefrom:\fP is the name of an existing machine in Linode from which to clone. \fBScript_args: \-C \-F\fP is necessary to avoid re\-deploying Salt via salt\-bootstrap. \fB\-C\fP will just re\-deploy keys so the new minion will not have a duplicate key or minion_id on the Master, and \fB\-F\fP will force a rewrite of the Minion config file on the new Minion. If \fB\-F\fP isn\(aqt provided, the new Minion will have the \fBmachine_to_clone\fP\(aqs Minion ID, instead of its own Minion ID, which can cause problems. .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 \fI\%Pull Request #733\fP to the salt\-bootstrap repo makes the \fB\-F\fP argument non\-necessary. Once that change is released into a stable version of the Bootstrap Script, the \fB\-C\fP argument will be sufficient for the \fBscript_args\fP setting. .UNINDENT .UNINDENT .sp If the \fBmachine_to_clone\fP does not have Salt installed on it, refrain from using the \fBscript_args: \-C \-F\fP altogether, because the new machine will need to have Salt installed. .SS Getting Started With LXC .sp The LXC module is designed to install Salt in an LXC container on a controlled and possibly remote minion. .sp In other words, Salt will connect to a minion, then from that minion: .INDENT 0.0 .IP \(bu 2 Provision and configure a container for networking access .IP \(bu 2 Use those modules to deploy salt and re\-attach to master. .INDENT 2.0 .INDENT 3.5 .INDENT 0.0 .IP \(bu 2 \fBlxc runner\fP .IP \(bu 2 \fBlxc module\fP .IP \(bu 2 \fBseed\fP .UNINDENT .UNINDENT .UNINDENT .UNINDENT .SS Limitations .INDENT 0.0 .IP \(bu 2 You can only act on one minion and one provider at a time. .IP \(bu 2 Listing images must be targeted to a particular LXC provider (nothing will be outputted with \fBall\fP) .UNINDENT .SS Operation .sp Salt\(aqs LXC support does use \fBlxc.init\fP via the \fBlxc.cloud_init_interface\fP and seeds the minion via \fBseed.mkconfig\fP\&. .sp You can provide to those lxc VMs a profile and a network profile like if you were directly using the minion module. .sp Order of operation: .INDENT 0.0 .IP \(bu 2 Create the LXC container on the desired minion (clone or template) .IP \(bu 2 Change LXC config options (if any need to be changed) .IP \(bu 2 Start container .IP \(bu 2 Change base passwords if any .IP \(bu 2 Change base DNS configuration if necessary .IP \(bu 2 Wait for LXC container to be up and ready for ssh .IP \(bu 2 Test SSH connection and bailout in error .IP \(bu 2 Upload deploy script and seeds, then re\-attach the minion. .UNINDENT .SS Provider configuration .sp Here is a simple provider configuration: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C # Note: This example goes in /etc/salt/cloud.providers or any file in the # /etc/salt/cloud.providers.d/ directory. devhost10\-lxc: target: devhost10 driver: lxc .ft P .fi .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 Changed in version 2015.8.0. .sp The \fBprovider\fP parameter in cloud provider definitions was renamed to \fBdriver\fP\&. This change was made to avoid confusion with the \fBprovider\fP parameter that is used in cloud profile definitions. Cloud provider definitions now use \fBdriver\fP to refer to the Salt cloud module that provides the underlying functionality to connect to a cloud host, while cloud profiles continue to use \fBprovider\fP to refer to provider configurations that you define. .UNINDENT .UNINDENT .SS Profile configuration .sp Please read tutorial\-lxc before anything else. And specially tutorial\-lxc\-profiles\&. .sp Here are the options to configure your containers: .INDENT 0.0 .INDENT 3.5 .INDENT 0.0 .TP .B target Host minion id to install the lxc Container into .TP .B lxc_profile Name of the profile or inline options for the LXC vm creation/cloning, please see tutorial\-lxc\-profiles\-container\&. .TP .B network_profile Name of the profile or inline options for the LXC vm network settings, please see tutorial\-lxc\-profiles\-network\&. .TP .B nic_opts Totally optional. Per interface new\-style configuration options mappings which will override any profile default option: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C eth0: {\(aqmac\(aq: \(aq00:16:3e:01:29:40\(aq, \(aqgateway\(aq: None, (default) \(aqlink\(aq: \(aqbr0\(aq, (default) \(aqgateway\(aq: None, (default) \(aqnetmask\(aq: \(aq\(aq, (default) \(aqip\(aq: \(aq22.1.4.25\(aq}} .ft P .fi .UNINDENT .UNINDENT .TP .B password password for root and sysadmin users .TP .B dnsservers List of DNS servers to use. This is optional. .TP .B minion minion configuration (see Minion Configuration in Salt Cloud) .TP .B bootstrap_delay specify the time to wait (in seconds) between container creation and salt bootstrap execution. It is useful to ensure that all essential services have started before the bootstrap script is executed. By default there\(aqs no wait time between container creation and bootstrap unless you are on systemd where we wait that the system is no more in starting state. .TP .B bootstrap_shell shell for bootstraping script (default: /bin/sh) .TP .B script defaults to salt\-boostrap .TP .B script_args arguments which are given to the bootstrap script. the {0} placeholder will be replaced by the path which contains the minion config and key files, eg: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C script_args="\-c {0}" .ft P .fi .UNINDENT .UNINDENT .UNINDENT .UNINDENT .UNINDENT .sp Using profiles: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C # Note: This example would go in /etc/salt/cloud.profiles or any file in the # /etc/salt/cloud.profiles.d/ directory. devhost10\-lxc: provider: devhost10\-lxc lxc_profile: foo network_profile: bar minion: master: 10.5.0.1 master_port: 4506 .ft P .fi .UNINDENT .UNINDENT .sp Using inline profiles (eg to override the network bridge): .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C devhost11\-lxc: provider: devhost10\-lxc lxc_profile: clone_from: foo network_profile: etho: link: lxcbr0 minion: master: 10.5.0.1 master_port: 4506 .ft P .fi .UNINDENT .UNINDENT .sp Using a lxc template instead of a clone: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C devhost11\-lxc: provider: devhost10\-lxc lxc_profile: template: ubuntu # options: # release: trusty network_profile: etho: link: lxcbr0 minion: master: 10.5.0.1 master_port: 4506 .ft P .fi .UNINDENT .UNINDENT .sp Static ip: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C # Note: This example would go in /etc/salt/cloud.profiles or any file in the # /etc/salt/cloud.profiles.d/ directory. devhost10\-lxc: provider: devhost10\-lxc nic_opts: eth0: ipv4: 10.0.3.9 minion: master: 10.5.0.1 master_port: 4506 .ft P .fi .UNINDENT .UNINDENT .sp DHCP: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C # Note: This example would go in /etc/salt/cloud.profiles or any file in the # /etc/salt/cloud.profiles.d/ directory. devhost10\-lxc: provider: devhost10\-lxc minion: master: 10.5.0.1 master_port: 4506 .ft P .fi .UNINDENT .UNINDENT .SS Driver Support .INDENT 0.0 .IP \(bu 2 Container creation .IP \(bu 2 Image listing (LXC templates) .IP \(bu 2 Running container information (IP addresses, etc.) .UNINDENT .SS Getting Started with OpenNebula .sp OpenNebula is an open\-source solution for the comprehensive management of virtualized data centers to enable the mixed use of private, public, and hybrid IaaS clouds. .SS Dependencies .sp The driver requires Python\(aqs \fBlxml\fP library to be installed. It also requires an OpenNebula installation running version \fB4.12\fP or greater. .SS Configuration .sp The following example illustrates some of the options that can be set. These parameters are discussed in more detail below. .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\-opennebula\-provider: # Set up the location of the salt master # minion: master: saltmaster.example.com # Define xml_rpc setting which Salt\-Cloud uses to connect to the OpenNebula API. Required. # xml_rpc: http://localhost:2633/RPC2 # Define the OpenNebula access credentials. This can be the main "oneadmin" user that OpenNebula uses as the # OpenNebula main admin, or it can be a user defined in the OpenNebula instance. Required. # user: oneadmin password: JHGhgsayu32jsa # Define the private key location that is used by OpenNebula to access new VMs. This setting is required if # provisioning new VMs or accessing VMs previously created with the associated public key. # private_key: /path/to/private/key driver: opennebula .ft P .fi .UNINDENT .UNINDENT .SS Access Credentials .sp The Salt Cloud driver for OpenNebula was written using OpenNebula\(aqs native XML RPC API. Every interaction with OpenNebula\(aqs API requires a \fBusername\fP and \fBpassword\fP to make the connection from the machine running Salt Cloud to API running on the OpenNebula instance. Based on the access credentials passed in, OpenNebula filters the commands that the user can perform or the information for which the user can query. For example, the images that a user can view with a \fB\-\-list\-images\fP command are the images that the connected user and the connected user\(aqs groups can access. .SS Key Pairs .sp Salt Cloud needs to be able to access a virtual machine in order to install the Salt Minion by using a public/private key pair. The virtual machine will need to be seeded with the public key, which is laid down by the OpenNebula template. Salt Cloud then uses the corresponding private key, provided by the \fBprivate_key\fP setting in the cloud provider file, to SSH into the new virtual machine. .sp To seed the virtual machine with the public key, the public key must be added to the OpenNebula template. If using the OpenNebula web interface, navigate to the template, then click \fBUpdate\fP\&. Click the \fBContext\fP tab. Under the \fBNetwork & SSH\fP section, click \fBAdd SSH Contextualization\fP and paste the public key in the \fBPublic Key\fP box. Don\(aqt forget to save your changes by clicking the green \fBUpdate\fP button. .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 The key pair must not have a pass\-phrase. .UNINDENT .UNINDENT .SS Cloud Profiles .sp Set up an initial profile at either \fB/etc/salt/cloud.profiles\fP or the \fB/etc/salt/cloud.profiles.d/\fP directory. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C my\-opennebula\-profile: provider: my\-opennebula\-provider image: Ubuntu\-14.04 .ft P .fi .UNINDENT .UNINDENT .sp The profile can now be realized with a salt command: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-p my\-opennebula\-profile my\-new\-vm .ft P .fi .UNINDENT .UNINDENT .sp This will create a new instance named \fBmy\-new\-vm\fP in OpenNebula. The minion that is installed on this instance will have a minion id of \fBmy\-new\-vm\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 my\-new\-vm test.ping .ft P .fi .UNINDENT .UNINDENT .sp OpenNebula uses an image \-\-> template \-\-> virtual machine paradigm where the template draws on the image, or disk, and virtual machines are created from templates. Because of this, there is no need to define a \fBsize\fP in the cloud profile. The size of the virtual machine is defined in the template. .SS Required Settings .sp The following settings are always required for OpenNebula: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C my\-opennebula\-config: xml_rpc: http://localhost:26633/RPC2 user: oneadmin password: JHGhgsayu32jsa driver: opennebula .ft P .fi .UNINDENT .UNINDENT .SS Required Settings for VM Deployment .sp The settings defined in the \fI\%Required Settings\fP section are required for all interactions with OpenNebula. However, when deploying a virtual machine via Salt Cloud, an additional setting, \fBprivate_key\fP, is also required: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C my\-opennebula\-config: private_key: /path/to/private/key .ft P .fi .UNINDENT .UNINDENT .SS Listing Images .sp Images can be queried on OpenNebula by passing the \fB\-\-list\-images\fP argument to Salt Cloud: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-\-list\-images opennebula .ft P .fi .UNINDENT .UNINDENT .SS Listing Locations .sp In OpenNebula, locations are defined as \fBhosts\fP\&. Locations, or "hosts", can be querried on OpenNebula by passing the \fB\-\-list\-locations\fP argument to Salt Cloud: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-\-list\-locations opennebula .ft P .fi .UNINDENT .UNINDENT .SS Listing Sizes .sp Sizes are defined by templates in OpenNebula. As such, the \fB\-\-list\-sizes\fP call returns an empty dictionary since there are no sizes to return. .SS Additional OpenNebula API Functionality .sp The Salt Cloud driver for OpenNebula was written using OpenNebula\(aqs native XML RPC API. As such, many \fB\-\-function\fP and \fB\-\-action\fP calls were added to the OpenNebula driver to enhance support for an OpenNebula infrastructure with additional control from Salt Cloud. See the \fBOpenNebula function definitions\fP for more information. .SS Access via DNS entry instead of IP .sp Some OpenNebula installations do not assign IP addresses to new VMs, instead they establish the new VM\(aqs hostname based on OpenNebula\(aqs name of the VM, and then allocate an IP out of DHCP with dynamic DNS attaching the hostname. This driver supports this behavior by adding the entry \fIfqdn_base\fP to the driver configuration or the OpenNebula profile with a value matching the base fully\-qualified domain. For example: .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\-opennebula\-provider: [...] fqdn_base: corp.example.com [...] .ft P .fi .UNINDENT .UNINDENT .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. .SS Dependencies .INDENT 0.0 .IP \(bu 2 Libcloud >= 0.13.2 .UNINDENT .SS Configuration .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/tokens compute_name: nova protocol: ipv4 compute_region: RegionOne # Configure Openstack authentication credentials # user: myname password: 123456 # tenant is the project name tenant: myproject driver: openstack # skip SSL certificate validation (default false) insecure: false .ft P .fi .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 Changed in version 2015.8.0. .sp The \fBprovider\fP parameter in cloud provider definitions was renamed to \fBdriver\fP\&. This change was made to avoid confusion with the \fBprovider\fP parameter that is used in cloud profile definitions. Cloud provider definitions now use \fBdriver\fP to refer to the Salt cloud module that provides the underlying functionality to connect to a cloud host, while cloud profiles continue to use \fBprovider\fP to refer to provider configurations that you define. .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 ssh_key_name: test ssh_interface: private_ips .ft P .fi .UNINDENT .UNINDENT .sp The following list explains some of the important properties. .INDENT 0.0 .TP .B size can be one of the options listed in the output of \fBnova flavor\-list\fP\&. .TP .B image can be one of the options listed in the output of \fBnova image\-list\fP\&. .TP .B ssh_key_file The SSH private key that the salt\-cloud uses to SSH into the VM after its first booted in order to execute a command or script. This private key\(aqs \fIpublic key\fP must be the openstack public key inserted into the authorized_key\(aqs file of the VM\(aqs root user account. .TP .B ssh_key_name The name of the openstack SSH public key that is inserted into the authorized_keys file of the VM\(aqs root user account. Prior to using this public key, you must use openstack commands or the horizon web UI to load that key into the tenant\(aqs account. Note that this openstack tenant must be the one you defined in the cloud provider. .TP .B ssh_interface This option allows you to create a VM without a public IP. If this option is omitted and the VM does not have a public IP, then the salt\-cloud waits for a certain period of time and then destroys the VM. With the nova drive, private cloud networks can be defined here. .UNINDENT .sp For more information concerning cloud profiles, see here\&. .SS change_password .sp If no ssh_key_file is provided, and the server already exists, change_password will use the api to change the root password of the server so that it can be bootstrapped. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C change_password: True .ft P .fi .UNINDENT .UNINDENT .SS userdata_file .sp Use \fIuserdata_file\fP to specify the userdata file to upload for use with cloud\-init if available. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C userdata_file: /etc/salt/cloud\-init/packages.yml .ft P .fi .UNINDENT .UNINDENT .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 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 host # 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/ driver: parallels .ft P .fi .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 Changed in version 2015.8.0. .sp The \fBprovider\fP parameter in cloud provider definitions was renamed to \fBdriver\fP\&. This change was made to avoid confusion with the \fBprovider\fP parameter that is used in cloud profile definitions. Cloud provider definitions now use \fBdriver\fP to refer to the Salt cloud module that provides the underlying functionality to connect to a cloud host, while cloud profiles continue to use \fBprovider\fP to refer to provider configurations that you define. .UNINDENT .UNINDENT .SS Access Credentials .sp The \fBuser\fP, \fBpassword\fP, and \fBurl\fP will be provided to you by your cloud host. 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 .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 host. 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/ driver: 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 hosts. 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 Getting Started With ProfitBricks .sp ProfitBricks provides an enterprise\-grade Infrastructure as a Service (IaaS) solution that can be managed through a browser\-based "Data Center Designer" (DCD) tool or via an easy to use API. A unique feature of the ProfitBricks platform is that it allows you to define your own settings for cores, memory, and disk size without being tied to a particular server size. .SS Dependencies .INDENT 0.0 .IP \(bu 2 profitbricks >= 2.3.4 .UNINDENT .SS Configuration .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/profitbricks.conf\fP: .UNINDENT .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C my\-profitbricks\-config: driver: profitbricks # Set the location of the salt\-master # minion: master: saltmaster.example.com # Configure ProfitBricks authentication credentials # username: user@domain.com password: 123456 # datacenter is the UUID of a pre\-existing virtual data center. datacenter: 9e6709a0\-6bf9\-4bd6\-8692\-60349c70ce0e # Connect to public LAN ID 1. public_lan: 1 ssh_public_key: /path/to/id_rsa.pub ssh_private_key: /path/to/id_rsa .ft P .fi .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 Changed in version 2015.8.0. .sp The \fBprovider\fP parameter in cloud provider definitions was renamed to \fBdriver\fP\&. This change was made to avoid confusion with the \fBprovider\fP parameter that is used in cloud profile definitions. Cloud provider definitions now use \fBdriver\fP to refer to the Salt cloud module that provides the underlying functionality to connect to a cloud host, while cloud profiles continue to use \fBprovider\fP to refer to provider configurations that you define. .UNINDENT .UNINDENT .SS Virtual Data Center .sp ProfitBricks uses the concept of Virtual Data Centers. These are logically separated from one another and allow you to have a self\-contained environment for all servers, volumes, networking, snapshots, and so forth. .sp A list of existing virtual data centers can be retrieved with the following command: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-f list_datacenters my\-profitbricks\-config .ft P .fi .UNINDENT .UNINDENT .SS Authentication .sp The \fBusername\fP and \fBpassword\fP are the same as those used to log into the ProfitBricks "Data Center Designer". .SS Profiles .sp Here is an example of a profile: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C profitbricks_staging provider: my\-profitbricks\-config size: Micro Instance image: 2f98b678\-6e7e\-11e5\-b680\-52540066fee9 cores: 2 ram: 4096 public_lan: 1 private_lan: 2 ssh_public_key: /path/to/id_rsa.pub ssh_private_key: /path/to/id_rsa ssh_interface: private_lan profitbricks_production: provider: my\-profitbricks\-config image: Ubuntu\-15.10\-server\-2016\-05\-01 disk_type: SSD disk_size: 40 cores: 8 cpu_family: INTEL_XEON ram: 32768 public_lan: 1 private_lan: 2 public_firewall_rules: Allow SSH: protocol: TCP source_ip: 1.2.3.4 port_range_start: 22 port_range_end: 22 Allow Ping: protocol: ICMP icmp_type: 8 ssh_public_key: /path/to/id_rsa.pub ssh_private_key: /path/to/id_rsa ssh_interface: private_lan volumes: db_data: disk_size: 500 db_log: disk_size: 50 disk_type: SSD .ft P .fi .UNINDENT .UNINDENT .sp The following list explains some of the important properties. .INDENT 0.0 .TP .B size Can be one of the options listed in the output of the following command: .UNINDENT .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-\-list\-sizes my\-profitbricks .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .TP .B image Can be one of the options listed in the output of the following command: .UNINDENT .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-\-list\-images my\-profitbricks .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .TP .B disk_size This option allows you to override the size of the disk as defined by the size. The disk size is set in gigabytes (GB). .TP .B disk_type This option allow the disk type to be set to HDD or SSD. The default is HDD. .TP .B cores This option allows you to override the number of CPU cores as defined by the size. .TP .B ram This option allows you to override the amount of RAM defined by the size. The value must be a multiple of 256, e.g. 256, 512, 768, 1024, and so forth. .TP .B public_lan This option will connect the server to the specified public LAN. If no LAN exists, then a new public LAN will be created. The value accepts a LAN ID (integer). .TP .B public_firewall_rules This option allows for a list of firewall rules assigned to the public network interface. .INDENT 7.0 .TP .B Firewall Rule Name: protocol: (TCP, UDP, ICMP) source_mac: source_ip: target_ip: port_range_start: port_range_end: icmp_type: icmp_code: .UNINDENT .TP .B private_lan This option will connect the server to the specified private LAN. If no LAN exists, then a new private LAN will be created. The value accepts a LAN ID (integer). .TP .B private_firewall_rules This option allows for a list of firewall rules assigned to the private network interface. .INDENT 7.0 .TP .B Firewall Rule Name: protocol: (TCP, UDP, ICMP) source_mac: source_ip: target_ip: port_range_start: port_range_end: icmp_type: icmp_code: .UNINDENT .TP .B ssh_private_key Full path to the SSH private key file. .TP .B ssh_public_key Full path to the SSH public key file. .TP .B ssh_interface This option will use the private LAN IP for node connections (such as as bootstrapping the node) instead of the public LAN IP. The value accepts \(aqprivate_lan\(aq. .TP .B cpu_family This option allow the CPU family to be set to AMD_OPTERON or INTEL_XEON. The default is AMD_OPTERON. .TP .B volumes: This option allows a list of additional volumes by name that will be created and attached to the server. Each volume requires \(aqdisk_size\(aq and, optionally, \(aqdisk_type\(aq. The default is HDD. .TP .B deploy Set to False if Salt should not be installed on the node. .TP .B wait_for_timeout The timeout to wait in seconds for provisioning resources such as servers. The default wait_for_timeout is 15 minutes. .UNINDENT .sp For more information concerning cloud profiles, see here\&. .SS Getting Started With Proxmox .sp Proxmox Virtual Environment is a complete server virtualization management solution, based on OpenVZ(in Proxmox up to 3.4)/LXC(from Proxmox 4.0 and up) and full virtualization with KVM. Further information can be found at: .sp \fI\%http://www.proxmox.org/\fP .SS Dependencies .INDENT 0.0 .IP \(bu 2 IPy >= 0.81 .IP \(bu 2 requests >= 2.2.1 .UNINDENT .sp Please note: This module allows you to create OpenVZ/LXC containers and KVM VMs, but installing Salt on it will only be done on containers rather than a KVM virtual machine. .INDENT 0.0 .IP \(bu 2 Set up the cloud configuration at \fB/etc/salt/cloud.providers\fP or \fB/etc/salt/cloud.providers.d/proxmox.conf\fP: .UNINDENT .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C my\-proxmox\-config: # Set up the location of the salt master # minion: master: saltmaster.example.com # Set the PROXMOX access credentials (see below) # user: myuser@pve password: badpass # Set the access URL for your PROXMOX host # url: your.proxmox.host driver: proxmox .ft P .fi .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 Changed in version 2015.8.0. .sp The \fBprovider\fP parameter in cloud provider definitions was renamed to \fBdriver\fP\&. This change was made to avoid confusion with the \fBprovider\fP parameter that is used in cloud profile definitions. Cloud provider definitions now use \fBdriver\fP to refer to the Salt cloud module that provides the underlying functionality to connect to a cloud host, while cloud profiles continue to use \fBprovider\fP to refer to provider configurations that you define. .UNINDENT .UNINDENT .SS Access Credentials .sp The \fBuser\fP, \fBpassword\fP, and \fBurl\fP will be provided to you by your cloud host. These are all required in order for the PROXMOX 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/proxmox.conf\fP: .INDENT 0.0 .IP \(bu 2 Configure a profile to be used: .UNINDENT .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C proxmox\-ubuntu: provider: my\-proxmox\-config image: local:vztmpl/ubuntu\-12.04\-standard_12.04\-1_amd64.tar.gz technology: lxc # host needs to be set to the configured name of the proxmox host # and not the ip address or FQDN of the server host: myvmhost ip_address: 192.168.100.155 password: topsecret .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 proxmox\-ubuntu myubuntu .ft P .fi .UNINDENT .UNINDENT .sp This will create an instance named \fBmyubuntu\fP on the cloud host. The minion that is installed on this instance will have a \fBhostname\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 PROXMOX: .INDENT 0.0 .IP \(bu 2 Using the new cloud configuration format: .UNINDENT .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C my\-proxmox\-config: driver: proxmox user: saltcloud@pve password: xyzzy url: your.proxmox.host .ft P .fi .UNINDENT .UNINDENT .SS Optional Settings .sp Unlike other cloud providers in Salt Cloud, Proxmox does not utilize a \fBsize\fP setting. This is because Proxmox 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. desc: # How many CPU cores, and how fast they are (in MHz) cpus: 1 cpuunits: 1000 # How many megabytes of RAM memory: 256 # How much swap space in MB swap: 256 # Whether to auto boot the vm after the host reboots onboot: 1 # Size of the instance disk (in GiB) disk: 10 # Host to create this vm on host: myvmhost # Nameservers. Defaults to host nameserver: 8.8.8.8 8.8.4.4 # Username and password ssh_username: root password: # The name of the image, from \(ga\(gasalt\-cloud \-\-list\-images proxmox\(ga\(ga image: local:vztmpl/ubuntu\-12.04\-standard_12.04\-1_amd64.tar.gz # Whether or not to verify the SSL cert on the Proxmox host verify_ssl: False # Network interfaces, netX net0: name=eth0,bridge=vmbr0,ip=dhcp .ft P .fi .UNINDENT .UNINDENT .SS QEMU .sp Some functionnalities works differently if you use \(aqqemu\(aq as technology. In order to create a new VM with qemu, you need to specificy some more information. You can also clone a qemu template which already is on your Proxmox server. .sp QEMU profile file (for a new VM): .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C proxmox\-win7: # Image of the new VM image: image.iso # You can get all your available images using \(aqsalt\-cloud \-\-list\-images provider_name\(aq (Ex: \(aqsalt\-cloud \-\-list\-images my\-proxmox\-config\(aq) # Technology used to create the VM (\(aqqemu\(aq, \(aqopenvz\(aq(on Proxmox <4.x) or \(aqlxc\(aq(on Proxmox 4.x+)) technology: qemu # Proxmox node name host: node_name # Proxmox password password: your_password # Workaround https://github.com/saltstack/salt/issues/27821 size: \(aq\(aq # RAM size (MB) memory: 2048 # OS Type enum (other / wxp / w2k / w2k3 / w2k8 / wvista / win7 / win8 / l24 / l26 / solaris) ostype: win7 # Hard disk location sata0: :, format=, size=GB #Example: local:120,format=qcow2,size=120GB #CD/DVD Drive ide2: ,media=cdrom #Example: local:iso/name.iso,media=cdrom # Network Device net0:,bridge= #Example: e1000,bridge=vmbr0 # Enable QEMU Guest Agent (0 / 1) agent: 1 # VM name name: Test .ft P .fi .UNINDENT .UNINDENT .sp More information about these parameters can be found on Proxmox API (\fI\%http://pve.proxmox.com/pve2\-api\-doc/\fP) under the \(aqPOST\(aq method of nodes/{node}/qemu .sp QEMU profile file (for a clone): .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C proxmox\-win7: # Enable Clone clone: 1 # New VM description clone_description: \(aqdescription\(aq # New VM name clone_name: \(aqname\(aq # New VM format (qcow2 / raw / vmdk) clone_format: qcow2 # Full clone (1) or Link clone (0) clone_full: 0 # VMID of Template to clone clone_from: ID # Technology used to create the VM (\(aqqemu\(aq or \(aqlxc\(aq) technology: qemu # Proxmox node name host: node_name # Proxmox password password: your_password # Workaround https://github.com/saltstack/salt/issues/27821 size: \(aq\(aq .ft P .fi .UNINDENT .UNINDENT .sp More information can be found on Proxmox API under the \(aqPOST\(aq method of /nodes/{node}/qemu/{vmid}/clone .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 The Proxmox API offers a lot more options and parameters, which are not yet supported by this salt\-cloud \(aqoverlay\(aq. Feel free to add your contribution by forking the github repository and modifying the following file: salt/salt/cloud/clouds/proxmox.py An easy way to support more parameters for VM creation would be to add the names of the optional parameters in the \(aqcreate_nodes( .nf vm_ .fi )\(aq function, under the \(aqqemu\(aq technology. But it requires you to dig into the code ... .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 intended only 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. .SS Dependencies .INDENT 0.0 .IP \(bu 2 Libcloud >= 0.13.2 .UNINDENT .SS Configuration .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 driver: 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: driver: 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. .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 Changed in version 2015.8.0. .sp The \fBprovider\fP parameter in cloud provider definitions was renamed to \fBdriver\fP\&. This change was made to avoid confusion with the \fBprovider\fP parameter that is used in cloud profile definitions. Cloud provider definitions now use \fBdriver\fP to refer to the Salt cloud module that provides the underlying functionality to connect to a cloud host, while cloud profiles continue to use \fBprovider\fP to refer to provider configurations that you define. .UNINDENT .UNINDENT .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 available 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 Private Subnets .sp By default salt\-cloud will not add Rackspace private networks to new servers. To enable a private network to a server instantiated by salt cloud, add the following section to the provider file (typically \fB/etc/salt/cloud.providers.d/rackspace.conf\fP) .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C networks: \- fixed: # This is the private network \- private\-network\-id # This is Rackspace\(aqs "PublicNet" \- 00000000\-0000\-0000\-0000\-000000000000 # This is Rackspace\(aqs "ServiceNet" \- 11111111\-1111\-1111\-1111\-111111111111 .ft P .fi .UNINDENT .UNINDENT .sp To get the Rackspace private network ID, go to Networking, Networks and hover over the private network name. .sp The order of the networks in the above code block does not map to the order of the ethernet devices on newly created servers. Public IP will always be first ( eth0 ) followed by servicenet ( eth1 ) and then private networks. .sp Enabling the private network per above gives the option of using the private subnet for all master\-minion communication, including the bootstrap install of salt\-minion. To enable the minion to use the private subnet, update the master: line in the minion: section of the providers file. To configure the master to only listen on the private subnet IP, update the interface: line in the /etc/salt/master file to be the private subnet IP of the salt master. .SS Getting Started With Scaleway .sp Scaleway is the first IaaS host worldwide to offer an ARM based cloud. It’s the ideal platform for horizontal scaling with BareMetal SSD servers. The solution provides on demand resources: it comes with on\-demand SSD storage, movable IPs , images, security group and an Object Storage solution. \fI\%https://scaleway.com\fP .SS Configuration .sp Using Salt for Scaleway, requires an \fBaccess key\fP and an \fBAPI token\fP\&. \fBAPI tokens\fP are unique identifiers associated with your Scaleway account. To retrieve your \fBaccess key\fP and \fBAPI token\fP, log\-in to the Scaleway control panel, open the pull\-down menu on your account name and click on "My Credentials" link. .sp If you do not have API token you can create one by clicking the "Create New Token" button on the right corner. .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\-scaleway\-config: access_key: 15cf404d\-4560\-41b1\-9a0c\-21c3d5c4ff1f token: a7347ec8\-5de1\-4024\-a5e3\-24b77d1ba91d driver: scaleway .ft P .fi .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 Changed in version 2015.8.0. .sp The \fBprovider\fP parameter in cloud provider definitions was renamed to \fBdriver\fP\&. This change was made to avoid confusion with the \fBprovider\fP parameter that is used in cloud profile definitions. Cloud provider definitions now use \fBdriver\fP to refer to the Salt cloud module that provides the underlying functionality to connect to a cloud host, while cloud profiles continue to use \fBprovider\fP to refer to provider configurations that you define. .UNINDENT .UNINDENT .SS Profiles .SS Cloud Profiles .sp Set up an initial profile at /etc/salt/cloud.profiles or in the /etc/salt/cloud.profiles.d/ directory: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C scalewa\-ubuntu: provider: my\-scaleway\-config image: Ubuntu Trusty (14.04 LTS) .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\-scaleway\-config my\-scaleway\-config: \-\-\-\-\-\-\-\-\-\- scaleway: \-\-\-\-\-\-\-\-\-\- 069fd876\-eb04\-44ab\-a9cd\-47e2fa3e5309: \-\-\-\-\-\-\-\-\-\- arch: arm creation_date: 2015\-03\-12T09:35:45.764477+00:00 default_bootscript: {u\(aqkernel\(aq: {u\(aqdtb\(aq: u\(aq\(aq, u\(aqtitle\(aq: u\(aqPimouss 3.2.34\-30\-std\(aq, u\(aqid\(aq: u\(aqcfda4308\-cd6f\-4e51\-9744\-905fc0da370f\(aq, u\(aqpath\(aq: u\(aqkernel/pimouss\-uImage\-3.2.34\-30\-std\(aq}, u\(aqtitle\(aq: u\(aq3.2.34\-std #30 (stable)\(aq, u\(aqid\(aq: u\(aqc5af0215\-2516\-4316\-befc\-5da1cfad609c\(aq, u\(aqinitrd\(aq: {u\(aqpath\(aq: u\(aqinitrd/c1\-uInitrd\(aq, u\(aqid\(aq: u\(aq1be14b1b\-e24c\-48e5\-b0b6\-7ba452e42b92\(aq, u\(aqtitle\(aq: u\(aqC1 initrd\(aq}, u\(aqbootcmdargs\(aq: {u\(aqid\(aq: u\(aqd22c4dde\-e5a4\-47ad\-abb9\-d23b54d542ff\(aq, u\(aqvalue\(aq: u\(aqip=dhcp boot=local root=/dev/nbd0 USE_XNBD=1 nbd.max_parts=8\(aq}, u\(aqorganization\(aq: u\(aq11111111\-1111\-4111\-8111\-111111111111\(aq, u\(aqpublic\(aq: True} extra_volumes: [] id: 069fd876\-eb04\-44ab\-a9cd\-47e2fa3e5309 modification_date: 2015\-04\-24T12:02:16.820256+00:00 name: Ubuntu Vivid (15.04) organization: a283af0b\-d13e\-42e1\-a43f\-855ffbf281ab public: True root_volume: {u\(aqname\(aq: u\(aqdistrib\-ubuntu\-vivid\-2015\-03\-12_10:32\-snapshot\(aq, u\(aqid\(aq: u\(aqa6d02e63\-8dee\-4bce\-b627\-b21730f35a05\(aq, u\(aqvolume_type\(aq: u\(aql_ssd\(aq, u\(aqsize\(aq: 50000000000L} \&... .ft P .fi .UNINDENT .UNINDENT .sp Execute a query and return all information about the nodes running on configured cloud providers using the \fB\-Q\fP option for the \fBsalt\-cloud\fP command: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C # salt\-cloud \-F [INFO ] salt\-cloud starting [INFO ] Starting new HTTPS connection (1): api.scaleway.com my\-scaleway\-config: \-\-\-\-\-\-\-\-\-\- scaleway: \-\-\-\-\-\-\-\-\-\- salt\-manager: \-\-\-\-\-\-\-\-\-\- creation_date: 2015\-06\-03T08:17:38.818068+00:00 hostname: salt\-manager \&... .ft P .fi .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 Additional documentation about Scaleway can be found at \fI\%https://www.scaleway.com/docs\fP\&. .UNINDENT .UNINDENT .SS Getting Started With Saltify .sp The Saltify driver is a new, experimental driver for installing Salt on existing machines (virtual or bare metal). .SS Dependencies .sp The Saltify driver has no external dependencies. .SS Configuration .sp Because the Saltify driver does not use an actual cloud provider host, it has a simple provider configuration. The only thing that is required to be set is the driver name, and any other potentially useful information, like the location of the salt\-master: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C # Note: This example is for /etc/salt/cloud.providers file or any file in # the /etc/salt/cloud.providers.d/ directory. my\-saltify\-config: minion: master: 111.222.333.444 provider: saltify .ft P .fi .UNINDENT .UNINDENT .SS Profiles .sp Saltify requires a profile to be configured for each machine that needs Salt installed. The initial profile can be set up at \fB/etc/salt/cloud.profiles\fP or in the \fB/etc/salt/cloud.profiles.d/\fP directory. Each profile requires both an \fBssh_host\fP and an \fBssh_username\fP key parameter as well as either an \fBkey_filename\fP or a \fBpassword\fP\&. .sp Profile configuration example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C # /etc/salt/cloud.profiles.d/saltify.conf salt\-this\-machine: ssh_host: 12.34.56.78 ssh_username: root key_filename: \(aq/etc/salt/mysshkey.pem\(aq provider: my\-saltify\-config .ft P .fi .UNINDENT .UNINDENT .sp The machine can now be "Salted" with the following command: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-p salt\-this\-machine my\-machine .ft P .fi .UNINDENT .UNINDENT .sp This will install salt on the machine specified by the cloud profile, \fBsalt\-this\-machine\fP, and will give the machine the minion id of \fBmy\-machine\fP\&. If the command was executed on the salt\-master, its Salt key will automatically be signed on the master. .sp Once a salt\-minion has been successfully installed on the instance, connectivity to it can be verified with Salt: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt my\-machine test.ping .ft P .fi .UNINDENT .UNINDENT .SS Using Map Files .sp The settings explained in the section above may also be set in a map file. An example of how to use the Saltify driver with a map file follows: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C # /etc/salt/saltify\-map make_salty: \- my\-instance\-0: ssh_host: 12.34.56.78 ssh_username: root password: very\-bad\-password \- my\-instance\-1: ssh_host: 44.33.22.11 ssh_username: root password: another\-bad\-pass .ft P .fi .UNINDENT .UNINDENT .sp Note: When using a cloud map with the Saltify driver, the name of the profile to use, in this case \fBmake_salty\fP, must be defined in a profile config. For example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C # /etc/salt/cloud.profiles.d/saltify.conf make_salty: provider: my\-saltify\-config .ft P .fi .UNINDENT .UNINDENT .sp The machines listed in the map file can now be "Salted" by applying the following salt map command: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-m /etc/salt/saltify\-map .ft P .fi .UNINDENT .UNINDENT .sp This command will install salt on the machines specified in the map and will give each machine their minion id of \fBmy\-instance\-0\fP and \fBmy\-instance\-1\fP, respectively. If the command was executed on the salt\-master, its Salt key will automatically be signed on the master. .sp Connectivity to the new "Salted" instances can now be verified with Salt: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt \(aqmy\-instance\-*\(aq test.ping .ft P .fi .UNINDENT .UNINDENT .SS Getting Started With SoftLayer .sp SoftLayer is a public cloud host, and baremetal hardware hosting service. .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 \fBpip\fP or \fBeasy_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 driver: 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 driver: softlayer_hw .ft P .fi .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 Changed in version 2015.8.0. .sp The \fBprovider\fP parameter in cloud provider definitions was renamed to \fBdriver\fP\&. This change was made to avoid confusion with the \fBprovider\fP parameter that is used in cloud profile definitions. Cloud provider definitions now use \fBdriver\fP to refer to the Salt cloud module that provides the underlying functionality to connect to a cloud host, while cloud profiles continue to use \fBprovider\fP to refer to provider configurations that you define. .UNINDENT .UNINDENT .SS Access Credentials .sp The \fBuser\fP setting is the same user as is used to log into the SoftLayer Administration area. The \fBapikey\fP setting is found inside the Admin area after logging in: .INDENT 0.0 .IP \(bu 2 Hover over the \fBAccount\fP menu item. .IP \(bu 2 Click the \fBUsers\fP link. .IP \(bu 2 Find the \fBAPI Key\fP column and click \fBView\fP\&. .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 \fB\-\-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 \fBtemplate\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 gigabytes. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C base_softlayer_ubuntu: disk_size: 100 .ft P .fi .UNINDENT .UNINDENT .SS Using Multiple Disks .sp New in version 2015.8.1. .sp SoftLayer allows up to 5 disks to be specified for a virtual machine upon creation. Multiple disks can be specified either as a list or a comma\-delimited string. The first \fBdisk_size\fP specified in the string or list will be the first disk size assigned to the VM. .sp List Example: .. code\-block:: yaml .INDENT 0.0 .INDENT 3.5 .INDENT 0.0 .TP .B base_softlayer_ubuntu: disk_size: [\(aq100\(aq, \(aq20\(aq, \(aq20\(aq] .UNINDENT .UNINDENT .UNINDENT .sp String Example: .. code\-block:: yaml .INDENT 0.0 .INDENT 3.5 .INDENT 0.0 .TP .B base_softlayer_ubuntu: disk_size: \(aq100, 20, 20\(aq .UNINDENT .UNINDENT .UNINDENT .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 use_fqdn .sp If set to True, the Minion will be identified by the FQDN (Fully Qualified Domain Name) which is a result of combining the \fBdomain\fP configuration value and the Minion name specified either via the CLI or a map file rather than only using the short host name, or Minion ID. Default is False. .sp New in version 2016.3.0. .sp For example, if the value of \fBdomain\fP is \fBexample.com\fP and a new VM was created via the CLI with \fBsalt\-cloud \-p base_softlayer_ubuntu my\-vm\fP, the resulting Minion ID would be \fBmy\-vm.example.com\fP\&. .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 When enabling the \fBuse_fqdn\fP setting, the Minion ID will be the FQDN and will interact with salt commands with the FQDN instead of the short hostname. However, due to the way the SoftLayer API is constructed, some Salt Cloud functions such as listing nodes or destroying VMs will only list the short hostname of the VM instead of the FQDN. .UNINDENT .UNINDENT .sp Example output displaying the SoftLayer hostname quirk mentioned in the note above (note the Minion ID is \fBmy\-vm.example.com\fP, but the VM to be destroyed is listed with its short hostname, \fBmy\-vm\fP): .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C # salt\-key \-L Accepted Keys: my\-vm.example.com Denied Keys: Unaccepted Keys: Rejected Keys: # # # salt my\-vm.example.com test.ping my\-vm.example.com: True # # # salt\-cloud \-d my\-vm.example.com [INFO ] salt\-cloud starting [INFO ] POST https://api.softlayer.com/xmlrpc/v3.1/SoftLayer_Account The following virtual machines are set to be destroyed: softlayer\-config: softlayer: my\-vm Proceed? [N/y] y \&... proceeding [INFO ] Destroying in non\-parallel mode. [INFO ] POST https://api.softlayer.com/xmlrpc/v3.1/SoftLayer_Account [INFO ] POST https://api.softlayer.com/xmlrpc/v3.1/SoftLayer_Virtual_Guest softlayer\-config: \-\-\-\-\-\-\-\-\-\- softlayer: \-\-\-\-\-\-\-\-\-\- my\-vm: True .ft P .fi .UNINDENT .UNINDENT .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 post_uri .sp Specifies the uri location of the script to be downloaded and run after the instance is provisioned. .sp New in version 2015.8.1. .sp Example: .. code\-block:: yaml .INDENT 0.0 .INDENT 3.5 .INDENT 0.0 .TP .B base_softlayer_ubuntu: post_uri: \(aq\fI\%https://SOMESERVERIP:8000/myscript.sh\fP\(aq .UNINDENT .UNINDENT .UNINDENT .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 # 500GB SATA II hdd: 1267 # 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 is currently only one size of hard disk drive (HDD) that is available for hardware instances on SoftLayer: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C 1267: 500GB SATA II .ft P .fi .UNINDENT .UNINDENT .sp The \fIhdd\fP setting in the profile should be 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 driver 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 # 500GB SATA II hdd: 1267 # 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 Getting Started with VEXXHOST .sp \fI\%VEXXHOST\fP is a cloud computing host which provides \fI\%Canadian cloud computing\fP services which are based in Monteral and use the libcloud OpenStack driver. VEXXHOST currently runs the Havana release of OpenStack. When provisioning new instances, they automatically get a public IP and private IP address. Therefore, you do not need to assign a floating IP to access your instance after it\(aqs booted. .SS Cloud Provider Configuration .sp To use the \fIopenstack\fP driver for the VEXXHOST public cloud, you will need to set up the cloud provider configuration file as in the example below: .sp \fB/etc/salt/cloud.providers.d/vexxhost.conf\fP: In order to use the VEXXHOST public cloud, you will need to setup a cloud provider configuration file as in the example below which uses the OpenStack driver. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C my\-vexxhost\-config: # Set the location of the salt\-master # minion: master: saltmaster.example.com # Configure VEXXHOST using the OpenStack plugin # identity_url: http://auth.api.thenebulacloud.com:5000/v2.0/tokens compute_name: nova # Set the compute region: # compute_region: na\-yul\-nhs1 # Configure VEXXHOST authentication credentials # user: your\-tenant\-id password: your\-api\-key tenant: your\-tenant\-name # keys to allow connection to the instance launched # ssh_key_name: yourkey ssh_key_file: /path/to/key/yourkey.priv driver: openstack .ft P .fi .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 Changed in version 2015.8.0. .sp The \fBprovider\fP parameter in cloud provider definitions was renamed to \fBdriver\fP\&. This change was made to avoid confusion with the \fBprovider\fP parameter that is used in cloud profile definitions. Cloud provider definitions now use \fBdriver\fP to refer to the Salt cloud module that provides the underlying functionality to connect to a cloud host, while cloud profiles continue to use \fBprovider\fP to refer to provider configurations that you define. .UNINDENT .UNINDENT .SS Authentication .sp All of the authentication fields that you need can be found by logging into your VEXXHOST customer center. Once you\(aqve logged in, you will need to click on "CloudConsole" and then click on "API Credentials". .SS Cloud Profile Configuration .sp In order to get the correct image UUID and the instance type to use in the cloud profile, you can run the following command respectively: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C # salt\-cloud \-\-list\-images=vexxhost\-config # salt\-cloud \-\-list\-sizes=vexxhost\-config .ft P .fi .UNINDENT .UNINDENT .sp Once you have that, you can go ahead and create a new cloud profile. This profile will build an Ubuntu 12.04 LTS \fInb.2G\fP instance. .sp \fB/etc/salt/cloud.profiles.d/vh_ubuntu1204_2G.conf\fP: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C vh_ubuntu1204_2G: provider: my\-vexxhost\-config image: 4051139f\-750d\-4d72\-8ef0\-074f2ccc7e5a size: nb.2G .ft P .fi .UNINDENT .UNINDENT .SS Provision an instance .sp To create an instance based on the sample profile that we created above, you can run the following \fIsalt\-cloud\fP command. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C # salt\-cloud \-p vh_ubuntu1204_2G vh_instance1 .ft P .fi .UNINDENT .UNINDENT .sp Typically, instances are provisioned in under 30 seconds on the VEXXHOST public cloud. After the instance provisions, it will be set up a minion and then return all the instance information once it\(aqs complete. .sp Once the instance has been setup, you can test connectivity to it by running the following command: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C # salt vh_instance1 test.ping .ft P .fi .UNINDENT .UNINDENT .sp You can now continue to provision new instances and they will all automatically be set up as minions of the master you\(aqve defined in the configuration file. .SS Getting Started With Virtualbox .sp The Virtualbox cloud module allows you to manage a \fBlocal\fP Virtualbox hypervisor. Remote hypervisors may come later on. .SS Dependencies .sp The virtualbox module for Salt Cloud requires the \fI\%Virtualbox SDK\fP which is contained in a virtualbox installation from .sp \fI\%https://www.virtualbox.org/wiki/Downloads\fP .SS Configuration .sp The Virtualbox cloud module just needs to use the virtualbox driver for now. Virtualbox will be run as the running user. .sp \fB/etc/salt/cloud.providers\fP or \fB/etc/salt/cloud.providers.d/virtualbox.conf\fP: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C virtualbox\-config: driver: virtualbox .ft P .fi .UNINDENT .UNINDENT .SS Profiles .sp Set up an initial profile at \fB/etc/salt/cloud.profiles\fP or \fB/etc/salt/cloud.profiles.d/virtualbox.conf\fP: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C virtualbox\-test: provider: virtualbox\-config clonefrom: VM_to_clone_from # Optional power_on: True deploy: True ssh_username: a_username password: a_password sudo: a_username sudo_password: a_password # Example minion config minion: master: localhost make_master: True .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .TP \fBclonefrom\fP \fBMandatory\fP Enter the name of the VM/template to clone from. .UNINDENT .sp So far only machines can only be cloned and automatically provisioned by Salt Cloud. .SS Provisioning .sp In order to provision when creating a new machine \fBpower_on\fP and \fBdeploy\fP have to be \fBTrue\fP\&. .sp Furthermore to connect to the VM \fBssh_username\fP and \fBpassword\fP will have to be set. .sp \fBsudo\fP and \fBsudo_password\fP are the credentials for getting root access in order to deploy salt .SS Actions .INDENT 0.0 .TP .B \fBstart\fP Attempt to boot a VM by name. VMs should have unique names in order to boot the correct one. .TP .B \fBstop\fP Attempt to stop a VM. This is akin to a force shutdown or 5 second press. .UNINDENT .SS Functions .INDENT 0.0 .TP .B \fBshow_image\fP Show all available information about a VM given by the \fIimage\fP parameter .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C $ salt\-cloud \-f show_image virtualbox image=my_vm_name .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS Getting Started With VMware .sp New in version 2015.5.4. .sp \fBAuthor\fP: Nitin Madhok <\fI\%nmadhok@clemson.edu\fP> .sp The VMware cloud module allows you to manage VMware ESX, ESXi, and vCenter. .SS Dependencies .sp The vmware module for Salt Cloud requires the \fBpyVmomi\fP package, which is available at PyPI: .sp \fI\%https://pypi.python.org/pypi/pyvmomi\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 pyvmomi easy_install pyvmomi .ft P .fi .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 Version 6.0 of pyVmomi has some problems with SSL error handling on certain versions of Python. If using version 6.0 of pyVmomi, the machine that you are running the proxy minion process from must have either Python 2.7.9 or newer This is due to an upstream dependency in pyVmomi 6.0 that is not supported in Python version 2.6 to 2.7.8. If the version of Python running the salt\-cloud command is not in the supported range, you will need to install an earlier version of pyVmomi. See \fI\%Issue #29537\fP for more information. .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 pyVmomi doesn\(aqt expose the ability to specify the locale when connecting to VMware. This causes parsing issues when connecting to an instance of VMware running under a non\-English locale. Until this feature is added upstream \fI\%Issue #38402\fP contains a workaround. .UNINDENT .UNINDENT .SS Configuration .sp The VMware cloud module needs the vCenter or ESX/ESXi URL, username and password to be set up in the cloud configuration at \fB/etc/salt/cloud.providers\fP or \fB/etc/salt/cloud.providers.d/vmware.conf\fP: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C my\-vmware\-config: driver: vmware user: \(aqDOMAIN\euser\(aq password: \(aqverybadpass\(aq url: \(aq10.20.30.40\(aq vcenter01: driver: vmware user: \(aqDOMAIN\euser\(aq password: \(aqverybadpass\(aq url: \(aqvcenter01.domain.com\(aq protocol: \(aqhttps\(aq port: 443 vcenter02: driver: vmware user: \(aqDOMAIN\euser\(aq password: \(aqverybadpass\(aq url: \(aqvcenter02.domain.com\(aq protocol: \(aqhttp\(aq port: 80 esx01: driver: vmware user: \(aqadmin\(aq password: \(aqverybadpass\(aq url: \(aqesx01.domain.com\(aq .ft P .fi .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 Optionally, \fBprotocol\fP and \fBport\fP can be specified if the vCenter server is not using the defaults. Default is \fBprotocol: https\fP and \fBport: 443\fP\&. .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 Changed in version 2015.8.0. .sp The \fBprovider\fP parameter in cloud provider configuration was renamed to \fBdriver\fP\&. This change was made to avoid confusion with the \fBprovider\fP parameter that is used in cloud profile configuration. Cloud provider configuration now uses \fBdriver\fP to refer to the salt\-cloud driver that provides the underlying functionality to connect to a cloud provider, while cloud profile configuration continues to use \fBprovider\fP to refer to the cloud provider configuration that you define. .UNINDENT .UNINDENT .SS Profiles .sp Set up an initial profile at \fB/etc/salt/cloud.profiles\fP or \fB/etc/salt/cloud.profiles.d/vmware.conf\fP: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C vmware\-centos6.5: provider: vcenter01 clonefrom: test\-vm ## Optional arguments num_cpus: 4 memory: 8GB devices: cd: CD/DVD drive 1: device_type: datastore_iso_file iso_path: "[nap004\-1] vmimages/tools\-isoimages/linux.iso" CD/DVD drive 2: device_type: client_device mode: atapi controller: IDE 2 CD/DVD drive 3: device_type: client_device mode: passthrough controller: IDE 3 disk: Hard disk 1: size: 30 Hard disk 2: size: 20 controller: SCSI controller 2 Hard disk 3: size: 5 controller: SCSI controller 3 network: Network adapter 1: name: 10.20.30\-400\-Test switch_type: standard ip: 10.20.30.123 gateway: [10.20.30.110] subnet_mask: 255.255.255.128 domain: example.com Network adapter 2: name: 10.30.40\-500\-Dev\-DHCP adapter_type: e1000 switch_type: distributed Network adapter 3: name: 10.40.50\-600\-Prod adapter_type: vmxnet3 switch_type: distributed ip: 10.40.50.123 gateway: [10.40.50.110] subnet_mask: 255.255.255.128 domain: example.com scsi: SCSI controller 1: type: lsilogic SCSI controller 2: type: lsilogic_sas bus_sharing: virtual SCSI controller 3: type: paravirtual bus_sharing: physical ide: IDE 2 IDE 3 domain: example.com dns_servers: \- 123.127.255.240 \- 123.127.255.241 \- 123.127.255.242 resourcepool: Resources cluster: Prod datastore: HUGE\-DATASTORE\-Cluster folder: Development datacenter: DC1 host: c4212n\-002.domain.com template: False power_on: True extra_config: mem.hotadd: \(aqyes\(aq guestinfo.foo: bar guestinfo.domain: foobar.com guestinfo.customVariable: customValue deploy: True customization: True private_key: /root/.ssh/mykey.pem ssh_username: cloud\-user password: veryVeryBadPassword minion: master: 123.127.193.105 file_map: /path/to/local/custom/script: /path/to/remote/script /path/to/local/file: /path/to/remote/file /srv/salt/yum/epel.repo: /etc/yum.repos.d/epel.repo hardware_version: 10 image: centos64Guest #For Windows VM win_username: Administrator win_password: administrator win_organization_name: ABC\-Corp plain_text: True win_installer: /root/Salt\-Minion\-2015.8.4\-AMD64\-Setup.exe win_user_fullname: Windows User .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .TP .B \fBprovider\fP Enter the name that was specified when the cloud provider config was created. .TP .B \fBclonefrom\fP Enter the name of the VM/template to clone from. If not specified, the VM will be created without cloning. .TP .B \fBnum_cpus\fP Enter the number of vCPUS that you want the VM/template to have. If not specified, the current VM/template\(aqs vCPU count is used. .TP .B \fBcores_per_socket\fP New in version 2016.11.0. .sp Enter the number of cores per vCPU that you want the VM/template to have. If not specified, this will default to 1. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 Cores per socket should be less than or equal to the total number of vCPUs assigned to the VM/template. .UNINDENT .UNINDENT .TP .B \fBmemory\fP Enter the memory size (in MB or GB) that you want the VM/template to have. If not specified, the current VM/template\(aqs memory size is used. Example \fBmemory: 8GB\fP or \fBmemory: 8192MB\fP\&. .TP .B \fBdevices\fP Enter the device specifications here. Currently, the following devices can be created or reconfigured: .INDENT 7.0 .TP .B cd Enter the CD/DVD drive specification here. If the CD/DVD drive doesn\(aqt exist, it will be created with the specified configuration. If the CD/DVD drive already exists, it will be reconfigured with the specifications. The following options can be specified per CD/DVD drive: .INDENT 7.0 .TP .B device_type Specify how the CD/DVD drive should be used. Currently supported types are \fBclient_device\fP and \fBdatastore_iso_file\fP\&. Default is \fBdevice_type: client_device\fP .TP .B iso_path Enter the path to the iso file present on the datastore only if \fBdevice_type: datastore_iso_file\fP\&. The syntax to specify this is \fBiso_path: "[datastoreName] vmimages/tools\-isoimages/linux.iso"\fP\&. This field is ignored if \fBdevice_type: client_device\fP .TP .B mode Enter the mode of connection only if \fBdevice_type: client_device\fP\&. Currently supported modes are \fBpassthrough\fP and \fBatapi\fP\&. This field is ignored if \fBdevice_type: datastore_iso_file\fP\&. Default is \fBmode: passthrough\fP .TP .B controller Specify the IDE controller label to which this drive should be attached. This should be specified only when creating both the specified IDE controller as well as the CD/DVD drive at the same time. .UNINDENT .TP .B disk Enter the disk specification here. If the hard disk doesn\(aqt exist, it will be created with the provided size. If the hard disk already exists, it will be expanded if the provided size is greater than the current size of the disk. .INDENT 7.0 .TP .B size Enter the size of disk in GB .TP .B thin_provision Specifies whether the disk should be thin provisioned or not. Default is \fBthin_provision: False\fP\&. .. versionadded:: 2016.3.0 .TP .B controller Specify the SCSI controller label to which this disk should be attached. This should be specified only when creating both the specified SCSI controller as well as the hard disk at the same time. .UNINDENT .TP .B network Enter the network adapter specification here. If the network adapter doesn\(aqt exist, a new network adapter will be created with the specified network name, type and other configuration. If the network adapter already exists, it will be reconfigured with the specifications. The following additional options can be specified per network adapter (See example above): .INDENT 7.0 .TP .B name Enter the network name you want the network adapter to be mapped to. .TP .B adapter_type Enter the network adapter type you want to create. Currently supported types are \fBvmxnet\fP, \fBvmxnet2\fP, \fBvmxnet3\fP, \fBe1000\fP and \fBe1000e\fP\&. If no type is specified, by default \fBvmxnet3\fP will be used. .TP .B switch_type Enter the type of switch to use. This decides whether to use a standard switch network or a distributed virtual portgroup. Currently supported types are \fBstandard\fP for standard portgroups and \fBdistributed\fP for distributed virtual portgroups. .TP .B ip Enter the static IP you want the network adapter to be mapped to. If the network specified is DHCP enabled, you do not have to specify this. .TP .B gateway Enter the gateway for the network as a list. If the network specified is DHCP enabled, you do not have to specify this. .TP .B subnet_mask Enter the subnet mask for the network. If the network specified is DHCP enabled, you do not have to specify this. .TP .B domain Enter the domain to be used with the network adapter. If the network specified is DHCP enabled, you do not have to specify this. .UNINDENT .TP .B scsi Enter the SCSI controller specification here. If the SCSI controller doesn\(aqt exist, a new SCSI controller will be created of the specified type. If the SCSI controller already exists, it will be reconfigured with the specifications. The following additional options can be specified per SCSI controller: .INDENT 7.0 .TP .B type Enter the SCSI controller type you want to create. Currently supported types are \fBlsilogic\fP, \fBlsilogic_sas\fP and \fBparavirtual\fP\&. Type must be specified when creating a new SCSI controller. .TP .B bus_sharing Specify this if sharing of virtual disks between virtual machines is desired. The following can be specified: .INDENT 7.0 .TP .B virtual Virtual disks can be shared between virtual machines on the same server. .TP .B physical Virtual disks can be shared between virtual machines on any server. .TP .B no Virtual disks cannot be shared between virtual machines. .UNINDENT .UNINDENT .TP .B ide Enter the IDE controller specification here. If the IDE controller doesn\(aqt exist, a new IDE controller will be created. If the IDE controller already exists, no further changes to it will me made. .UNINDENT .TP .B \fBdomain\fP Enter the global domain name to be used for DNS. If not specified and if the VM name is a FQDN, \fBdomain\fP is set to the domain from the VM name. Default is \fBlocal\fP\&. .TP .B \fBdns_servers\fP Enter the list of DNS servers to use in order of priority. .TP .B \fBresourcepool\fP Enter the name of the resourcepool to which the new virtual machine should be attached. This determines what compute resources will be available to the clone. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 .INDENT 0.0 .IP \(bu 2 For a clone operation from a virtual machine, it will use the same resourcepool as the original virtual machine unless specified. .IP \(bu 2 For a clone operation from a template to a virtual machine, specifying either this or cluster is required. If both are specified, the resourcepool value will be used. .IP \(bu 2 For a clone operation to a template, this argument is ignored. .UNINDENT .UNINDENT .UNINDENT .TP .B \fBcluster\fP Enter the name of the cluster whose resource pool the new virtual machine should be attached to. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 .INDENT 0.0 .IP \(bu 2 For a clone operation from a virtual machine, it will use the same cluster\(aqs resourcepool as the original virtual machine unless specified. .IP \(bu 2 For a clone operation from a template to a virtual machine, specifying either this or resourcepool is required. If both are specified, the resourcepool value will be used. .IP \(bu 2 For a clone operation to a template, this argument is ignored. .UNINDENT .UNINDENT .UNINDENT .TP .B \fBdatastore\fP Enter the name of the datastore or the datastore cluster where the virtual machine should be located on physical storage. If not specified, the current datastore is used. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 .INDENT 0.0 .IP \(bu 2 If you specify a datastore cluster name, DRS Storage recommendation is automatically applied. .IP \(bu 2 If you specify a datastore name, DRS Storage recommendation is disabled. .UNINDENT .UNINDENT .UNINDENT .TP .B \fBfolder\fP Enter the name of the folder that will contain the new virtual machine. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 .INDENT 0.0 .IP \(bu 2 For a clone operation from a VM/template, the new VM/template will be added to the same folder that the original VM/template belongs to unless specified. .IP \(bu 2 If both folder and datacenter are specified, the folder value will be used. .UNINDENT .UNINDENT .UNINDENT .TP .B \fBdatacenter\fP Enter the name of the datacenter that will contain the new virtual machine. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 .INDENT 0.0 .IP \(bu 2 For a clone operation from a VM/template, the new VM/template will be added to the same folder that the original VM/template belongs to unless specified. .IP \(bu 2 If both folder and datacenter are specified, the folder value will be used. .UNINDENT .UNINDENT .UNINDENT .TP .B \fBhost\fP Enter the name of the target host where the virtual machine should be registered. .sp If not specified: .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 .INDENT 0.0 .IP \(bu 2 If resource pool is not specified, current host is used. .IP \(bu 2 If resource pool is specified, and the target pool represents a stand\-alone host, the host is used. .IP \(bu 2 If resource pool is specified, and the target pool represents a DRS\-enabled cluster, a host selected by DRS is used. .IP \(bu 2 If resource pool is specified and the target pool represents a cluster without DRS enabled, an InvalidArgument exception be thrown. .UNINDENT .UNINDENT .UNINDENT .TP .B \fBtemplate\fP Specifies whether the new virtual machine should be marked as a template or not. Default is \fBtemplate: False\fP\&. .TP .B \fBpower_on\fP Specifies whether the new virtual machine should be powered on or not. If \fBtemplate: True\fP is set, this field is ignored. Default is \fBpower_on: True\fP\&. .TP .B \fBextra_config\fP Specifies the additional configuration information for the virtual machine. This describes a set of modifications to the additional options. If the key is already present, it will be reset with the new value provided. Otherwise, a new option is added. Keys with empty values will be removed. .TP .B \fBdeploy\fP Specifies if salt should be installed on the newly created VM. Default is \fBTrue\fP so salt will be installed using the bootstrap script. If \fBtemplate: True\fP or \fBpower_on: False\fP is set, this field is ignored and salt will not be installed. .TP .B \fBcustomization\fP Specify whether the new virtual machine should be customized or not. If \fBcustomization: False\fP is set, the new virtual machine will not be customized. Default is \fBcustomization: True\fP\&. .TP .B \fBprivate_key\fP Specify the path to the private key to use to be able to ssh to the VM. .TP .B \fBssh_username\fP Specify the username to use in order to ssh to the VM. Default is \fBroot\fP .TP .B \fBpassword\fP Specify a password to use in order to ssh to the VM. If \fBprivate_key\fP is specified, you do not need to specify this. .TP .B \fBminion\fP Specify custom minion configuration you want the salt minion to have. A good example would be to specify the \fBmaster\fP as the IP/DNS name of the master. .TP .B \fBfile_map\fP Specify file/files you want to copy to the VM before the bootstrap script is run and salt is installed. A good example of using this would be if you need to put custom repo files on the server in case your server will be in a private network and cannot reach external networks. .TP .B \fBhardware_version\fP Specify the virtual hardware version for the vm/template that is supported by the host. .TP .B \fBimage\fP Specify the guest id of the VM. For a full list of supported values see the VMware vSphere documentation: .sp \fI\%http://pubs.vmware.com/vsphere\-60/topic/com.vmware.wssdk.apiref.doc/vim.vm.GuestOsDescriptor.GuestOsIdentifier.html\fP .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 For a clone operation, this argument is ignored. .UNINDENT .UNINDENT .TP .B \fBwin_username\fP Specify windows vm administrator account. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 Windows template should have "administrator" account. .UNINDENT .UNINDENT .TP .B \fBwin_password\fP Specify windows vm administrator account password. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 During network configuration (if network specified), it is used to specify new administrator password for the machine. .UNINDENT .UNINDENT .TP .B \fBwin_organization_name\fP .INDENT 7.0 .TP .B Specify windows vm user\(aqs organization. Default organization name is Organization VMware vSphere documentation: .UNINDENT .sp \fI\%https://www.vmware.com/support/developer/vc\-sdk/visdk25pubs/ReferenceGuide/vim.vm.customization.UserData.html\fP .TP .B \fBwin_user_fullname\fP .INDENT 7.0 .TP .B Specify windows vm user\(aqs fullname. Default fullname is "Windows User" VMware vSphere documentation: .UNINDENT .sp \fI\%https://www.vmware.com/support/developer/vc\-sdk/visdk25pubs/ReferenceGuide/vim.vm.customization.UserData.html\fP .TP .B \fBplain_text\fP Flag to specify whether or not the password is in plain text, rather than encrypted. VMware vSphere documentation: .sp \fI\%https://www.vmware.com/support/developer/vc\-sdk/visdk25pubs/ReferenceGuide/vim.vm.customization.Password.html\fP .TP .B \fBwin_installer\fP Specify windows minion client installer path .UNINDENT .SS Cloning a VM .sp Cloning VMs/templates is the easiest and the preferred way to work with VMs using the VMware driver. .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 Cloning operations are unsupported on standalone ESXi hosts, a vCenter server will be required. .UNINDENT .UNINDENT .sp Example of a minimal profile: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C my\-minimal\-clone: provider: vcenter01 clonefrom: \(aqtest\-vm\(aq .ft P .fi .UNINDENT .UNINDENT .sp When cloning a VM, all the profile configuration parameters are optional and the configuration gets inherited from the clone. .sp Example to add/resize a disk: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C my\-disk\-example: provider: vcenter01 clonefrom: \(aqtest\-vm\(aq devices: disk: Hard disk 1: size: 30 .ft P .fi .UNINDENT .UNINDENT .sp Depending on the configuration of the VM that is getting cloned, the disk in the resulting clone will differ. .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 .INDENT 0.0 .IP \(bu 2 If the VM has no disk named \(aqHard disk 1\(aq an empty disk with the specified size will be added to the clone. .IP \(bu 2 If the VM has a disk named \(aqHard disk 1\(aq and the size specified is larger than the original disk, an empty disk with the specified size will be added to the clone. .IP \(bu 2 If the VM has a disk named \(aqHard disk 1\(aq and the size specified is smaller than the original disk, an empty disk with the original size will be added to the clone. .UNINDENT .UNINDENT .UNINDENT .sp Example to reconfigure the memory and number of vCPUs: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C my\-disk\-example: provider: vcenter01 clonefrom: \(aqtest\-vm\(aq memory: 16GB num_cpus: 8 .ft P .fi .UNINDENT .UNINDENT .SS Cloning a Template .sp Cloning a template works similar to cloning a VM except for the fact that a resource pool or cluster must be specified additionally in the profile. .sp Example of a minimal profile: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C my\-template\-clone: provider: vcenter01 clonefrom: \(aqtest\-template\(aq cluster: \(aqProd\(aq .ft P .fi .UNINDENT .UNINDENT .SS Cloning from a Snapshot .sp New in version 2016.3.5. .sp Cloning from a snapshot requires that one of the supported options be set in the cloud profile. .sp Supported options are \fBcreateNewChildDiskBacking\fP, \fBmoveChildMostDiskBacking\fP, \fBmoveAllDiskBackingsAndAllowSharing\fP and \fBmoveAllDiskBackingsAndDisallowSharing\fP\&. .sp Example of a minimal profile: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C my\-template\-clone: provider: vcenter01 clonefrom: \(aqsalt_vm\(aq snapshot: disk_move_type: createNewChildDiskBacking # these types are also supported # disk_move_type: moveChildMostDiskBacking # disk_move_type: moveAllDiskBackingsAndAllowSharing # disk_move_type: moveAllDiskBackingsAndDisallowSharing .ft P .fi .UNINDENT .UNINDENT .SS Creating a VM .sp New in version 2016.3.0. .sp Creating a VM from scratch means that more configuration has to be specified in the profile because there is no place to inherit configuration from. .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 Unlike most cloud drivers that use prepared images, creating VMs using VMware cloud driver needs an installation method that requires no human interaction. For Example: preseeded ISO, kickstart URL or network PXE boot. .UNINDENT .UNINDENT .sp Example of a minimal profile: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C my\-minimal\-profile: provider: esx01 datastore: esx01\-datastore resourcepool: Resources folder: vm .ft P .fi .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 The example above contains the minimum required configuration needed to create a VM from scratch. The resulting VM will only have 1 VCPU, 32MB of RAM and will not have any storage or networking. .UNINDENT .UNINDENT .sp Example of a complete profile: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C my\-complete\-example: provider: esx01 datastore: esx01\-datastore resourcepool: Resources folder: vm num_cpus: 2 memory: 8GB image: debian7_64Guest devices: scsi: SCSI controller 0: type: lsilogic_sas ide: IDE 0 IDE 1 disk: Hard disk 0: controller: \(aqSCSI controller 0\(aq size: 20 mode: \(aqindependent_nonpersistent\(aq cd: CD/DVD drive 0: controller: \(aqIDE 0\(aq device_type: datastore_iso_file iso_path: \(aq[esx01\-datastore] debian\-8\-with\-preseed.iso\(aq network: Network adapter 0: name: \(aqVM Network\(aq swith_type: standard .ft P .fi .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 Depending on VMware ESX/ESXi version, an exact match for \fBimage\fP might not be available. In such cases, the closest match to another \fBimage\fP should be used. In the example above, a Debian 8 VM is created using the image \fBdebian7_64Guest\fP which is for a Debian 7 guest. .UNINDENT .UNINDENT .SS Specifying disk backing mode .sp New in version 2016.3.5. .sp Disk backing mode can now be specified when cloning a VM. This option can be set in the cloud profile as shown in example below: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C my\-vm: provider: esx01 datastore: esx01\-datastore resourcepool: Resources folder: vm devices: disk: Hard disk 1: mode: \(aqindependent_nonpersistent\(aq size: 42 Hard disk 2: mode: \(aqindependent_nonpersistent\(aq .ft P .fi .UNINDENT .UNINDENT .SS Miscellaneous Options .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: my\-ec2\-config image: ami\-1624987f size: t1.micro 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 Selecting the File Transport .sp By default, Salt Cloud uses SFTP to transfer files to Linux hosts. However, if SFTP is not available, or specific SCP functionality is needed, Salt Cloud can be configured to use SCP instead. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C file_transport: sftp file_transport: scp .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 Setting Up a Salt Syndic with Salt Cloud .sp In addition to \fI\%setting up new Salt Masters\fP, syndic\(gas can also be provisioned using Salt Cloud. In order to set up a Salt Syndic via Salt Cloud, a Salt Master needs to be installed on the new machine and a master configuration file needs to be set up using the \(ga\(gamake_master\(ga setting. This setting can be defined either in a profile config file or in a map file: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C make_master: True .ft P .fi .UNINDENT .UNINDENT .sp To install the Salt Syndic, the only other specification that needs to be configured is the \fBsyndic_master\fP key to specify the location of the master that the syndic will be reporting to. This modification needs to be placed in the \fBmaster\fP setting, which can be configured either in the profile, provider, or \fB/etc/salt/cloud\fP config file: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C master: syndic_master: 123.456.789 # may be either an IP address or a hostname .ft P .fi .UNINDENT .UNINDENT .sp Many other Salt Syndic configuration settings and specifications can be passed through to the new syndic machine via the \fBmaster\fP configuration setting. See the syndic documentation for more information. .SS SSH Port .sp By default ssh port is set to port 22. If you want to use a custom port in provider, profile, or map blocks use ssh_port option. .sp New in version 2015.5.0. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C ssh_port: 2222 .ft P .fi .UNINDENT .UNINDENT .SS SSH Port .sp By default ssh port is set to port 22. If you want to use a custom port in provider, profile, or map blocks use ssh_port option. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C ssh_port: 2222 .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 host 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 settings should be provided in lowercase 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 host. Default: varies by cloud provider ( between 5 and 25 minutes) .SS wait_for_ip_interval .sp The amount of time Salt Cloud should sleep while querying for the VM\(aqs IP. Default: varies by cloud provider ( between .5 and 10 seconds) .SS ssh_connect_timeout .sp The amount of time Salt Cloud should wait for a successful SSH connection to the VM. Default: varies by cloud provider (between 5 and 15 minutes) .SS wait_for_passwd_timeout .sp The amount of time until an ssh connection can be established via password or ssh key. Default: varies by cloud provider (mostly 15 seconds) .SS wait_for_passwd_maxtries .sp The number of attempts to connect to the VM until we abandon. Default: 15 attempts .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: 15 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. Default: 10 minutes .SS Salt Cloud Cache .sp Salt Cloud can maintain a cache of node data, for supported providers. The following options manage this functionality. .SS update_cachedir .sp On supported cloud providers, whether or not to maintain a cache of nodes returned from a \-\-full\-query. The data will be stored in \fBmsgpack\fP format under \fB/cloud/active///.p\fP\&. This setting can be True or False. .SS diff_cache_events .sp When the cloud cachedir is being managed, if differences are encountered between the data that is returned live from the cloud host and the data in the cache, fire events which describe the changes. This setting can be True or False. .sp Some of these events will contain data which describe a node. Because some of the fields returned may contain sensitive data, the \fBcache_event_strip_fields\fP configuration option exists to strip those fields from the event return. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C cache_event_strip_fields: \- password \- priv_key .ft P .fi .UNINDENT .UNINDENT .sp The following are events that can be fired based on this data. .SS salt/cloud/minionid/cache_node_new .sp A new node was found on the cloud host which was not listed in the cloud cachedir. A dict describing the new node will be contained in the event. .SS salt/cloud/minionid/cache_node_missing .sp A node that was previously listed in the cloud cachedir is no longer available on the cloud host. .SS salt/cloud/minionid/cache_node_diff .sp One or more pieces of data in the cloud cachedir has changed on the cloud host. A dict containing both the old and the new data will be contained in the event. .SS SSH Known Hosts .sp Normally when bootstrapping a VM, salt\-cloud will ignore the SSH host key. This is because it does not know what the host key is before starting (because it doesn\(aqt exist yet). If strict host key checking is turned on without the key in the \fBknown_hosts\fP file, then the host will never be available, and cannot be bootstrapped. .sp If a provider is able to determine the host key before trying to bootstrap it, that provider\(aqs driver can add it to the \fBknown_hosts\fP file, and then turn on strict host key checking. This can be set up in the main cloud configuration file (normally \fB/etc/salt/cloud\fP) or in the provider\-specific configuration file: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C known_hosts_file: /path/to/.ssh/known_hosts .ft P .fi .UNINDENT .UNINDENT .sp If this is not set, it will default to \fB/dev/null\fP, and strict host key checking will be turned off. .sp It is highly recommended that this option is \fInot\fP set, unless the user has verified that the provider supports this functionality, and that the image being used is capable of providing the necessary information. At this time, only the EC2 driver supports this functionality. .SS SSH Agent .sp New in version 2015.5.0. .sp If the ssh key is not stored on the server salt\-cloud is being run on, set ssh_agent, and salt\-cloud will use the forwarded ssh\-agent to authenticate. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C ssh_agent: True .ft P .fi .UNINDENT .UNINDENT .SS File Map Upload .sp New in version 2014.7.0. .sp The \fBfile_map\fP option allows an arbitrary group of files to be uploaded to the target system before running the deploy script. This functionality requires a provider uses salt.utils.cloud.bootstrap(), which is currently limited to the ec2, gce, openstack and nova drivers. .sp The \fBfile_map\fP can be configured globally in \fB/etc/salt/cloud\fP, or in any cloud provider or profile file. For example, to upload an extra package or a custom deploy script, a cloud profile using \fBfile_map\fP might look like: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C ubuntu14: provider: ec2\-config image: ami\-98aa1cf0 size: t1.micro ssh_username: root securitygroup: default file_map: /local/path/to/custom/script: /remote/path/to/use/custom/script /local/path/to/package: /remote/path/to/store/package .ft P .fi .UNINDENT .UNINDENT .SS Troubleshooting Steps .SS Troubleshooting Salt Cloud .sp This page describes various steps for troubleshooting problems that may arise while using Salt Cloud. .SS Virtual Machines Are Created, But Do Not Respond .sp Are TCP ports 4505 and 4506 open on the master? This is easy to overlook on new masters. Information on how to open firewall ports on various platforms can be found here\&. .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 hosts 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 cloud hosts, 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 cloud hosts, 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 hosts 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 hosts, 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 Extending Salt Cloud .SS Writing Cloud Driver 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 host 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 host is supported by libcloud. Additionally, not every feature in a supported cloud host is necessarily supported by libcloud. In either of these cases, a module can be created which does not rely on libcloud. .SS All Driver Modules .sp The following functions are required by all driver 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/tree/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 host, 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 driver module based on libcloud is the module provided for Linode: .sp \fI\%https://github.com/saltstack/salt/tree/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 host 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 host 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 host. 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 host does not currently support Windows. This will save time in the future if the host 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 (\fBbootstrap\-salt.sh\fP, 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 The \fBsalt.utils.cloud.validate_windows_cred()\fP function has been extended to take the number of retries and retry_delay parameters in case a specific cloud host has a delay between providing the Windows credentials and the credentials being available for use. In their \fBcreate()\fP function, or as a a sub\-function called during the creation process, developers should use the \fBwin_deploy_auth_retries\fP and \fBwin_deploy_auth_retry_delay\fP parameters from the provider configuration to allow the end\-user the ability to customize the number of tries and delay between tries for their particular host. .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 host. 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 host). .SS The libcloudfuncs Functions .sp A number of other functions are required for all cloud hosts. 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 driver is the DigitalOcean driver: .sp \fI\%https://github.com/saltstack/salt/tree/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 host uses multiple data centers. It is not necessary if the cloud host uses only 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 irreversibly 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 Cloud deployment scripts .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 Note that, somewhat counter\-intuitively, this script is referenced as \fBbootstrap\-salt\fP in the configuration. .sp You can specify a deploy script in the cloud configuration file (\fB/etc/salt/cloud\fP by default): .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C script: bootstrap\-salt .ft P .fi .UNINDENT .UNINDENT .sp Or in a provider: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C my\-provider: # snip... script: bootstrap\-salt .ft P .fi .UNINDENT .UNINDENT .sp Or in a profile: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C my\-profile: provider: my\-provider # snip... script: bootstrap\-salt .ft P .fi .UNINDENT .UNINDENT .sp If you do not specify a script argument in your cloud configuration file, provider configuration or profile configuration, the "bootstrap\-salt" script will be used by default. .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 Custom Deploy Scripts .sp If the Salt Bootstrap script does not meet your needs, you may write your own. The script should be written in shell 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. .sp Custom deploy scripts are picked up from \fB/etc/salt/cloud.deploy.d\fP by default, but you can change the location of deploy scripts with the cloud configuration \fBdeploy_scripts_search_path\fP\&. Additionally, if your deploy script has the extension \fB\&.sh\fP, you can leave out the extension in your configuration. .sp For example, if your custom deploy script is located in \fB/etc/salt/cloud.deploy.d/my_deploy.sh\fP, you could specify it in a cloud profile like this: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C my\-profile: provider: my\-provider # snip... script: my_deploy .ft P .fi .UNINDENT .UNINDENT .sp You\(aqre also free to use the full path to the script if you like. Using full paths, your script doesn\(aqt have to live inside \fB/etc/salt/cloud.deploy.d\fP or whatever you\(aqve configured with \fBdeploy_scripts_search_path\fP\&. .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 \fBstate.apply\fP, which would finish provisioning the VM. Another common option (for testing) is to use \fBtest.ping\fP\&. This is configured in the main cloud config file: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C start_action: state.apply .ft P .fi .UNINDENT .UNINDENT .sp This is currently considered to be experimental functionality, and may not work well with all cloud hosts. If you experience problems with Salt Cloud hanging after Salt is deployed, consider using Startup States instead: .sp \fI\%http://docs.saltstack.com/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: my\-ec2\-config image: ami\-7e2da54e size: t1.micro 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 \fBsalt\-cloud\fP: .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 \fBstable\fP version from: .sp \fI\%https://bootstrap.saltstack.com/stable/bootstrap\-salt.sh\fP .sp To update Salt Bootstrap script to the \fBdevelop\fP version, run the following command on the Salt minion host with \fBsalt\-cloud\fP installed: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt\-call config.gather_bootstrap_script \(aqhttps://bootstrap.saltstack.com/develop/bootstrap\-salt.sh\(aq .ft P .fi .UNINDENT .UNINDENT .sp Or just download the file manually: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C curl \-L \(aqhttps://bootstrap.saltstack.com/develop\(aq > /etc/salt/cloud.deploy.d/bootstrap\-salt.sh .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 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: my\-ec2\-config image: ami\-1624987f size: t1.micro 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 Using Salt Cloud from Salt .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=\(aqt1.micro\(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 dependent 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 instance 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: \(aqt1.micro\(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.profile: \- 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 Reactor .sp Examples of using the reactor with Salt Cloud are available in the \fI\%ec2\-autoscale\-reactor\fP and \fI\%salt\-cloud\-reactor\fP formulas. .SS Feature Comparison .SS Feature Matrix .sp A number of features are available in most cloud hosts, but not all are available everywhere. This may be because the feature isn\(aqt supported by the cloud host 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 hosts, as far as Salt Cloud is concerned. This is not a comprehensive list of all features available in all cloud hosts, and should not be used to make business decisions concerning choosing a cloud host. 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 preferred method for working with those hosts. .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 host, 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 cloud host. .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{ 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{ Aliyun 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{ T} T{ Yes 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{ T} T{ Yes 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{ T} T{ Yes 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{ T} T{ Yes 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{ T} T{ Yes 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{ T} T{ Yes 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{ T} T{ Yes 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{ 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{ Aliyun 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{ Yes T} T{ T} T{ Yes T} T{ T} T{ T} T{ Yes 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{ Yes T} T{ Yes T} T{ T} T{ Yes T} T{ T} T{ T} T{ T} T{ T} T{ Yes T} _ T{ stop T} T{ Yes T} T{ T} T{ T} T{ Yes T} T{ T} T{ Yes T} T{ Yes T} T{ T} T{ Yes T} T{ T} T{ T} T{ T} T{ T} T{ Yes T} _ T{ take_action 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{ 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{ 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{ Aliyun 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{ Yes T} T{ 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{ Yes T} T{ T} T{ T} T{ Yes T} T{ T} T{ T} T{ T} T{ T} T{ Yes 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{ Yes T} T{ 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{ Yes T} T{ T} T{ T} T{ T} T{ T} T{ T} T{ T} T{ T} T{ Yes 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{ Yes T} _ T{ import_key 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{ T} _ T{ key_list 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{ 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{ Yes 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{ Yes T} T{ T} T{ T} _ T{ list_keys 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{ T} _ T{ list_nodes 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{ list_nodes_full 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{ list_nodes_select 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{ 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{ Yes T} T{ Yes T} T{ T} _ T{ rackconnect 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{ T} _ T{ reboot T} T{ T} T{ T} T{ T} T{ Yes T} T{ T} T{ Yes T} T{ T} T{ T} T{ T} T{ T} T{ T} T{ T} T{ T} T{ Yes T} _ T{ reformat_node 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{ 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{ Yes T} _ T{ show_image T} T{ T} T{ T} T{ T} T{ Yes T} T{ T} T{ T} T{ T} T{ T} T{ Yes T} T{ T} T{ T} T{ T} T{ T} T{ Yes T} _ T{ show_key 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{ 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{ Yes T} _ .TE .SS Tutorials .SS Salt Cloud Quickstart .sp Salt Cloud is built\-in to Salt, and the easiest way to run Salt Cloud is directly from your Salt Master. .sp Note that if you installed Salt via \fI\%Salt Bootstrap\fP, it may not have automatically installed salt\-cloud for you. Use your distribution\(aqs package manager to install the \fBsalt\-cloud\fP package from the same repo that you used to install Salt. These repos will automatically be setup by Salt Bootstrap. .sp If there is no salt\-cloud package, install with \fBpip install salt\-cloud\fP\&. .sp This quickstart walks you through the basic steps of setting up a cloud host and defining some virtual machines to create. .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 Salt Cloud has its own process and does not rely on the Salt Master, so it can be installed on a standalone minion instead of your Salt Master. .UNINDENT .UNINDENT .SS Define a Provider .sp The first step is to add the credentials for your cloud host. Credentials and other settings provided by the cloud host are stored in provider configuration files. Provider configurations contain the details needed to connect to a cloud host such as EC2, GCE, Rackspace, etc., and any global options that you want set on your cloud minions (such as the location of your Salt Master). .sp On your Salt Master, browse to \fB/etc/salt/cloud.providers.d/\fP and create a file called \fB.conf\fP, replacing \fB\fP with \fBec2\fP, \fBsoftlayer\fP, and so on. The name helps you identify the contents, and is not important as long as the file ends in \fB\&.conf\fP\&. .sp Next, browse to the Provider specifics and add any required settings for your cloud host to this file. Here is an example for Amazon EC2: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C my\-ec2: driver: ec2 # Set the EC2 access credentials (see below) # id: \(aqHJGRYCILJLKJYG\(aq 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 # Optional: Set up the location of the Salt Master # minion: master: saltmaster.example.com .ft P .fi .UNINDENT .UNINDENT .sp The required configuration varies between cloud hosts so make sure you read the provider specifics. .SS List Cloud Provider Options .sp You can now query the cloud provider you configured for available locations, images, and sizes. This information is used when you set up VM profiles. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-\-list\-locations # my\-ec2 in the previous example salt\-cloud \-\-list\-images salt\-cloud \-\-list\-sizes .ft P .fi .UNINDENT .UNINDENT .sp Replace \fB\fP with the name of the provider configuration you defined. .SS Create VM Profiles .sp On your Salt Master, browse to \fB/etc/salt/cloud.profiles.d/\fP and create a file called \fB.conf\fP, replacing \fB\fP with \fBec2\fP, \fBsoftlayer\fP, and so on. The file must end in \fB\&.conf\fP\&. .sp You can now add any custom profiles you\(aqd like to define to this file. Here are a few examples: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C micro_ec2: provider: my\-ec2 image: ami\-d514f291 size: t1.micro medium_ec2: provider: my\-ec2 image: ami\-d514f291 size: m3.medium large_ec2: provider: my\-ec2 image: ami\-d514f291 size: m3.large .ft P .fi .UNINDENT .UNINDENT .sp Notice that the \fBprovider\fP in our profile matches the provider name that we defined? That is how Salt Cloud knows how to connect to to a cloud host to create a VM with these attributes. .SS Create VMs .sp VMs are created by calling \fBsalt\-cloud\fP with the following options: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-p ... .ft P .fi .UNINDENT .UNINDENT .sp For example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-p micro_ec2 minion1 minion2 .ft P .fi .UNINDENT .UNINDENT .SS Destroy VMs .sp Add a \fB\-d\fP and the minion name you provided to destroy: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-d minion1 minion2 .ft P .fi .UNINDENT .UNINDENT .SS Query VMs .sp You can view details about the VMs you\(aqve created using \fB\-\-query\fP: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-\-query .ft P .fi .UNINDENT .UNINDENT .SS Cloud Map .sp Now that you know how to create and destoy individual VMs, next you should learn how to use a cloud map to create a number of VMs at once. .sp Cloud maps let you define a map of your infrastructure and quickly provision any number of VMs. On subsequent runs, any VMs that do not exist are created, and VMs that are already configured are left unmodified. .sp See Cloud Map File\&. .SS Using Salt Cloud with the Event Reactor .sp One of the most powerful features of the Salt framework is the Event Reactor. As the Reactor was in development, Salt Cloud was regularly updated to take advantage of the Reactor upon completion. As such, various aspects of both the creation and destruction of instances with Salt Cloud fire events to the Salt Master, which can be used by the Event Reactor. .SS Event Structure .sp As of this writing, all events in Salt Cloud have a tag, which includes the ID of the instance being managed, and a payload which describes the task that is currently being handled. A Salt Cloud tag looks like: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt/cloud// .ft P .fi .UNINDENT .UNINDENT .sp For instance, the first event fired when creating an instance named \fBweb1\fP would look like: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt/cloud/web1/creating .ft P .fi .UNINDENT .UNINDENT .sp Assuming this instance is using the \fBec2\-centos\fP profile, which is in turn using the \fBec2\-config\fP provider, the payload for this tag would look like: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C {\(aqname\(aq: \(aqweb1\(aq, \(aqprofile\(aq: \(aqec2\-centos\(aq, \(aqprovider\(aq: \(aqec2\-config:ec2\(aq} .ft P .fi .UNINDENT .UNINDENT .SS Available Events .sp When an instance is created in Salt Cloud, whether by map, profile, or directly through an API, a minimum of five events are normally fired. More may be available, depending upon the cloud provider being used. Some of the common events are described below. .SS salt/cloud//creating .sp This event states simply that the process to create an instance has begun. At this point in time, no actual work has begun. The payload for this event includes: .sp name profile provider .SS salt/cloud//requesting .sp Salt Cloud is about to make a request to the cloud provider to create an instance. At this point, all of the variables required to make the request have been gathered, and the payload of the event will reflect those variables which do not normally pose a security risk. What is returned here is dependent upon the cloud provider. Some common variables are: .sp name image size location .SS salt/cloud//querying .sp The instance has been successfully requested, but the necessary information to log into the instance (such as IP address) is not yet available. This event marks the beginning of the process to wait for this information. .sp The payload for this event normally only includes the \fBinstance_id\fP\&. .SS salt/cloud//waiting_for_ssh .sp The information required to log into the instance has been retrieved, but the instance is not necessarily ready to be accessed. Following this event, Salt Cloud will wait for the IP address to respond to a ping, then wait for the specified port (usually 22) to respond to a connection, and on Linux systems, for SSH to become available. Salt Cloud will attempt to issue the \fBdate\fP command on the remote system, as a means to check for availability. If no \fBssh_username\fP has been specified, a list of usernames (starting with \fBroot\fP) will be attempted. If one or more usernames was configured for \fBssh_username\fP, they will be added to the beginning of the list, in order. .sp The payload for this event normally only includes the \fBip_address\fP\&. .SS salt/cloud//deploying .sp The necessary port has been detected as available, and now Salt Cloud can log into the instance, upload any files used for deployment, and run the deploy script. Once the script has completed, Salt Cloud will log back into the instance and remove any remaining files. .sp A number of variables are used to deploy instances, and the majority of these will be available in the payload. Any keys, passwords or other sensitive data will be scraped from the payload. Most of the variables returned will be related to the profile or provider config, and any default values that could have been changed in the profile or provider, but weren\(aqt. .SS salt/cloud//created .sp The deploy sequence has completed, and the instance is now available, Salted, and ready for use. This event is the final task for Salt Cloud, before returning instance information to the user and exiting. .sp The payload for this event contains little more than the initial \fBcreating\fP event. This event is required in all cloud providers. .SS Configuring the Event Reactor .sp The Event Reactor is built into the Salt Master process, and as such is configured via the master configuration file. Normally this will be a YAML file located at \fB/etc/salt/master\fP\&. Additionally, master configuration items can be stored, in YAML format, inside the \fB/etc/salt/master.d/\fP directory. .sp These configuration items may be stored in either location; however, they may only be stored in one location. For organizational and security purposes, it may be best to create a single configuration file, which contains only Event Reactor configuration, at \fB/etc/salt/master.d/reactor\fP\&. .sp The Event Reactor uses a top\-level configuration item called \fBreactor\fP\&. This block contains a list of tags to be watched for, each of which also includes a list of \fBsls\fP files. For instance: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C reactor: \- \(aqsalt/minion/*/start\(aq: \- \(aq/srv/reactor/custom\-reactor.sls\(aq \- \(aqsalt/cloud/*/created\(aq: \- \(aq/srv/reactor/cloud\-alert.sls\(aq \- \(aqsalt/cloud/*/destroyed\(aq: \- \(aq/srv/reactor/cloud\-destroy\-alert.sls\(aq .ft P .fi .UNINDENT .UNINDENT .sp The above configuration configures reactors for three different tags: one which is fired when a minion process has started and is available to receive commands, one which is fired when a cloud instance has been created, and one which is fired when a cloud instance is destroyed. .sp Note that each tag contains a wildcard (\fB*\fP) in it. For each of these tags, this will normally refer to a \fBminion_id\fP\&. This is not required of event tags, but is very common. .SS Reactor SLS Files .sp Reactor \fBsls\fP files should be placed in the \fB/srv/reactor/\fP directory for consistency between environments, but this is not currently enforced by Salt. .sp Reactor \fBsls\fP files follow a similar format to other \fBsls\fP files in Salt. By default they are written in YAML and can be templated using Jinja, but since they are processed through Salt\(aqs rendering system, any available renderer (JSON, Mako, Cheetah, etc.) can be used. .sp As with other \fBsls\fP files, each stanza will start with a declaration ID, followed by the function to run, and then any arguments for that function. For example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C # /srv/reactor/cloud\-alert.sls new_instance_alert: cmd.pagerduty.create_event: \- tgt: alertserver \- kwarg: description: "New instance: {{ data[\(aqname\(aq] }}" details: "New cloud instance created on {{ data[\(aqprovider\(aq] }}" service_key: 1626dead5ecafe46231e968eb1be29c4 profile: my\-pagerduty\-account .ft P .fi .UNINDENT .UNINDENT .sp When the Event Reactor receives an event notifying it that a new instance has been created, this \fBsls\fP will create a new incident in PagerDuty, using the configured PagerDuty account. .sp The declaration ID in this example is \fBnew_instance_alert\fP\&. The function called is \fBcmd.pagerduty.create_event\fP\&. The \fBcmd\fP portion of this function specifies that an execution module and function will be called, in this case, the \fBpagerduty.create_event\fP function. .sp Because an execution module is specified, a target (\fBtgt\fP) must be specified on which to call the function. In this case, a minion called \fBalertserver\fP has been used. Any arguments passed through to the function are declared in the \fBkwarg\fP block. .SS Example: Reactor\-Based Highstate .sp When Salt Cloud creates an instance, by default it will install the Salt Minion onto the instance, along with any specified minion configuration, and automatically accept that minion\(aqs keys on the master. One of the configuration options that can be specified is \fBstartup_states\fP, which is commonly set to \fBhighstate\fP\&. This will tell the minion to immediately apply a highstate, as soon as it is able to do so. .sp This can present a problem with some system images on some cloud hosts. For instance, Salt Cloud can be configured to log in as either the \fBroot\fP user, or a user with \fBsudo\fP access. While some hosts commonly use images that lock out remote \fBroot\fP access and require a user with \fBsudo\fP privileges to log in (notably EC2, with their \fBec2\-user\fP login), most cloud hosts fall back to \fBroot\fP as the default login on all images, including for operating systems (such as Ubuntu) which normally disallow remote \fBroot\fP login. .sp For users of these operating systems, it is understandable that a highstate would include configuration to block remote \fBroot\fP logins again. However, Salt Cloud may not have finished cleaning up its deployment files by the time the minion process has started, and kicked off a highstate run. Users have reported errors from Salt Cloud getting locked out while trying to clean up after itself. .sp The goal of a startup state may be achieved using the Event Reactor. Because a minion fires an event when it is able to receive commands, this event can effectively be used inside the reactor system instead. The following will point the reactor system to the right \fBsls\fP file: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C reactor: \- \(aqsalt/cloud/*/created\(aq: \- \(aq/srv/reactor/startup_highstate.sls\(aq .ft P .fi .UNINDENT .UNINDENT .sp And the following \fBsls\fP file will start a highstate run on the target minion: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C # /srv/reactor/startup_highstate.sls reactor_highstate: cmd.state.apply: \- tgt: {{ data[\(aqname\(aq] }} .ft P .fi .UNINDENT .UNINDENT .sp Because this event will not be fired until Salt Cloud has cleaned up after itself, the highstate run will not step on salt\-cloud\(aqs toes. And because every file on the minion is configurable, including \fB/etc/salt/minion\fP, the \fBstartup_states\fP can still be configured for future minion restarts, if desired. .SH SALT PROXY MINION .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. .sp See the Proxy Minion Walkthrough for an end\-to\-end demonstration of a working REST\-based proxy minion. .sp See the Proxy Minion SSH Walkthrough for an end\-to\-end demonstration of a working SSH proxy minion. .sp See Proxyminion States to configure and run \fBsalt\-proxy\fP on a remote minion. Specify all your master side proxy (pillar) configuration and use this state to remotely configure proxies on one or more minions. .sp See Proxyminion Beacon to help with easy configuration and management of \fBsalt\-proxy\fP processes. .SS New in 2016.11.0 .sp Proxy minions now support configuration files with names ending in \(aq .nf * .fi \&.conf\(aq and placed in /etc/salt/proxy.d. .sp Proxy minions can now be configured in /etc/salt/proxy or /etc/salt/proxy.d instead of just pillar. Configuration format is the same as it would be in pillar. .SS New in 2016.3 .sp The deprecated config option \fBenumerate_proxy_minions\fP has been removed. .sp As mentioned in earlier documentation, the \fBadd_proxymodule_to_opts\fP configuration variable defaults to \fBFalse\fP in this release. This means if you have proxymodules or other code looking in \fB__opts__[\(aqproxymodule\(aq]\fP you will need to set this variable in your \fB/etc/salt/proxy\fP file, or modify your code to use the \fI__proxy__\fP injected variable. .sp The \fB__proxyenabled__\fP directive now only applies to grains and proxy modules themselves. Standard execution modules and state modules are not prevented from loading for proxy minions. .sp Enhancements in grains processing have made the \fB__proxyenabled__\fP directive somewhat redundant in dynamic grains code. It is still required, but best practices for the \fB__virtual__\fP function in grains files have changed. It is now recommended that the \fB__virtual__\fP functions check to make sure they are being loaded for the correct proxytype, example below: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C def __virtual__(): \(aq\(aq\(aq Only work on proxy \(aq\(aq\(aq try: if salt.utils.is_proxy() and \e __opts__[\(aqproxy\(aq][\(aqproxytype\(aq] == \(aqssh_sample\(aq: return __virtualname__ except KeyError: pass return False .ft P .fi .UNINDENT .UNINDENT .sp The try/except block above exists because grains are processed very early in the proxy minion startup process, sometimes earlier than the proxy key in the \fB__opts__\fP dictionary is populated. .sp Grains are loaded so early in startup that no dunder dictionaries are present, so \fB__proxy__\fP, \fB__salt__\fP, etc. are not available. Custom grains located in \fB/srv/salt/_grains\fP and in the salt install grains directory can now take a single argument, \fBproxy\fP, that is identical to \fB__proxy__\fP\&. This enables patterns like .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C def get_ip(proxy): \(aq\(aq\(aq Ask the remote device what IP it has \(aq\(aq\(aq return {\(aqip\(aq:proxy[\(aqproxymodulename.get_ip\(aq]()} .ft P .fi .UNINDENT .UNINDENT .sp Then the grain \fBip\fP will contain the result of calling the \fBget_ip()\fP function in the proxymodule called \fBproxymodulename\fP\&. .sp Proxy modules now benefit from including a function called \fBinitialized()\fP\&. This function should return \fBTrue\fP if the proxy\(aqs \fBinit()\fP function has been successfully called. This is needed to make grains processing easier. .sp Finally, if there is a function called \fBgrains\fP in the proxymodule, it will be executed on proxy\-minion startup and its contents will be merged with the rest of the proxy\(aqs grains. Since older proxy\-minions might have used other methods to call such a function and add its results to grains, this is config\-gated by a new proxy configuration option called \fBproxy_merge_grains_in_module\fP\&. This defaults to \fBFalse\fP in this release. It will default to True in the release after next. The next release is 2016.11.0, the following is \fBNitrogen\fP\&. .SS New in 2015.8.2 .sp \fIBREAKING CHANGE\fP: Adding the \fIproxymodule\fP variable to __opts__ is deprecated. The \fIproxymodule\fP variable has been moved a new globally\-injected variable called \fI__proxy__\fP\&. A related configuration option called \fIadd_proxymodule_to_opts\fP has been added and defaults to \fITrue\fP\&. In the next major release, 2016.3.0, this variable will default to False. .sp In the meantime, proxies that functioned under 2015.8.0 and .1 should continue to work under 2015.8.2. You should rework your proxy code to use \fI__proxy__\fP as soon as possible. .sp The \fIrest_sample\fP example proxy minion has been updated to use \fI__proxy__\fP\&. .sp This change was made because proxymodules are a LazyLoader object, but LazyLoaders cannot be serialized. \fI__opts__\fP gets serialized, and so things like \fIsaltutil.sync_all\fP and \fIstate.highstate\fP would throw exceptions. .sp Support has been added to Salt\(aqs loader allowing custom proxymodules to be placed in \fBsalt://_proxy\fP\&. Proxy minions that need these modules will need to be restarted to pick up any changes. A corresponding utility function, \fBsaltutil.sync_proxymodules\fP, has been added to sync these modules to minions. .sp In addition, a salt.utils helper function called \fIis_proxy()\fP was added to make it easier to tell when the running minion is a proxy minion. .SS New in 2015.8 .sp Starting with the 2015.8 release of Salt, proxy processes are no longer forked off from a controlling minion. Instead, they have their own script \fBsalt\-proxy\fP which takes mostly the same arguments that the standard Salt minion does with the addition of \fB\-\-proxyid\fP\&. This is the id that the salt\-proxy will use to identify itself to the master. Proxy configurations are still best kept in Pillar and their format has not changed. .sp This change allows for better process control and logging. Proxy processes can now be listed with standard process management utilities (\fBps\fP from the command line). Also, a full Salt minion is no longer required (though it is still strongly recommended) on machines hosting proxies. .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. .sp After the proxy minion is started and initiates its connection to the \(aqdumb\(aq device, it connects back to the salt\-master and for all intents and purposes looks like just another minion to the Salt master. .sp To create support for a proxied device one needs to create four things: .INDENT 0.0 .IP 1. 3 The \fI\%proxy_connection_module\fP (located in salt/proxy). .IP 2. 3 The \fI\%grains support code\fP (located in salt/grains). .IP 3. 3 Salt modules specific to the controlled device. .IP 4. 3 Salt states specific to the controlled device. .UNINDENT .SS Configuration parameters .sp Proxy minions require no configuration parameters in /etc/salt/master. .sp Salt\(aqs Pillar system is ideally suited for configuring proxy\-minions (though they can be configured in /etc/salt/proxy as well). 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/pillar/top.sls\fP .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C base: dumbdevice1: \- dumbdevice1 dumbdevice2: \- dumbdevice2 dumbdevice3: \- dumbdevice3 dumbdevice4: \- dumbdevice4 dumbdevice5: \- dumbdevice5 dumbdevice6: \- dumbdevice6 dumbdevice7: \- dumbdevice7 .ft P .fi .UNINDENT .UNINDENT .sp \fB/srv/pillar/dumbdevice1.sls\fP .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C proxy: proxytype: networkswitch host: 172.23.23.5 username: root passwd: letmein .ft P .fi .UNINDENT .UNINDENT .sp \fB/srv/pillar/dumbdevice2.sls\fP .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C proxy: proxytype: networkswitch host: 172.23.23.6 username: root passwd: letmein .ft P .fi .UNINDENT .UNINDENT .sp \fB/srv/pillar/dumbdevice3.sls\fP .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C proxy: proxytype: networkswitch host: 172.23.23.7 username: root passwd: letmein .ft P .fi .UNINDENT .UNINDENT .sp \fB/srv/pillar/dumbdevice4.sls\fP .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C proxy: proxytype: i2c_lightshow i2c_address: 1 .ft P .fi .UNINDENT .UNINDENT .sp \fB/srv/pillar/dumbdevice5.sls\fP .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C proxy: proxytype: i2c_lightshow i2c_address: 2 .ft P .fi .UNINDENT .UNINDENT .sp \fB/srv/pillar/dumbdevice6.sls\fP .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C proxy: proxytype: 433mhz_wireless .ft P .fi .UNINDENT .UNINDENT .sp \fB/srv/pillar/dumbdevice7.sls\fP .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C proxy: 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\-proxy processes that fork off the proxy minions will only see the keys specific to the proxies it will be handling. .sp Proxies can be configured in /etc/salt/proxy or with files in /etc/salt/proxy.d as of Salt\(aqs 2016.11.0 release. .sp Also, in general, proxy\-minions are lightweight, so the machines that run them could conceivably control a large number of devices. To run more than one proxy from a single machine, simply start an additional proxy process with \fB\-\-proxyid\fP set to the id to which you want the proxy to bind. 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. .SS Proxymodules .sp A proxy module encapsulates all the code necessary to interface with a device. Proxymodules are located inside the salt.proxy module, or can be placed in the \fB_proxy\fP directory in your file_roots (default is \fB/srv/salt/_proxy\fP\&. At a minimum a proxymodule object must implement the following functions: .sp \fB__virtual__()\fP: This function performs the same duty that it does for other types of Salt modules. Logic goes here to determine if the module can be loaded, checking for the presence of Python modules on which the proxy depends. Returning \fBFalse\fP will prevent the module from loading. .sp \fBinit(opts)\fP: Perform any initialization that the device needs. This is a good place to bring up a persistent connection to a device, or authenticate to create a persistent authorization token. .sp \fBinitialized()\fP: Returns True if \fBinit()\fP was successfully called. .sp \fBshutdown()\fP: Code to cleanly shut down or close a connection to a controlled device goes here. This function must exist, but can contain only the keyword \fBpass\fP if there is no shutdown logic required. .sp \fBping()\fP: While not required, it is highly recommended that this function also be defined in the proxymodule. The code for \fBping\fP should contact the controlled device and make sure it is really available. .sp \fBgrains()\fP: Rather than including grains in /srv/salt/_grains or in the standard install directories for grains, grains can be computed and returned by this function. This function will be called automatically if \fBproxy_merge_grains_in_module\fP is set to \fBTrue\fP in /etc/salt/proxy. This variable defaults to \fBFalse\fP in 2016.3 but will default to \fBTrue\fP in the release code\-named \fINitrogen\fP\&. .sp Pre 2015.8 the proxymodule also must have an \fBid()\fP function. 2015.8 and following don\(aqt use this function because the proxy\(aqs id is required on the command line. .sp Here is an example proxymodule used to interface to a \fIvery\fP simple REST server. Code for the server is in the \fI\%salt\-contrib GitHub repository\fP .sp This proxymodule enables "service" enumeration, starting, stopping, restarting, and status; "package" installation, and a ping. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C # \-*\- coding: utf\-8 \-*\- \(aq\(aq\(aq This is a simple proxy\-minion designed to connect to and communicate with the bottle\-based web service contained in https://github.com/saltstack/salt\-contrib/tree/master/proxyminion_rest_example \(aq\(aq\(aq from __future__ import absolute_import # Import python libs import logging import salt.utils.http HAS_REST_EXAMPLE = True # This must be present or the Salt loader won\(aqt load this module __proxyenabled__ = [\(aqrest_sample\(aq] # Variables are scoped to this module so we can have persistent data # across calls to fns in here. GRAINS_CACHE = {} DETAILS = {} # Want logging! log = logging.getLogger(__file__) # This does nothing, it\(aqs here just as an example and to provide a log # entry when the module is loaded. def __virtual__(): \(aq\(aq\(aq Only return if all the modules are available \(aq\(aq\(aq log.debug(\(aqrest_sample proxy __virtual__() called...\(aq) return True # Every proxy module needs an \(aqinit\(aq, though you can # just put DETAILS[\(aqinitialized\(aq] = True here if nothing # else needs to be done. def init(opts): log.debug(\(aqrest_sample proxy init() called...\(aq) DETAILS[\(aqinitialized\(aq] = True # Save the REST URL DETAILS[\(aqurl\(aq] = opts[\(aqproxy\(aq][\(aqurl\(aq] # Make sure the REST URL ends with a \(aq/\(aq if not DETAILS[\(aqurl\(aq].endswith(\(aq/\(aq): DETAILS[\(aqurl\(aq] += \(aq/\(aq def initialized(): \(aq\(aq\(aq Since grains are loaded in many different places and some of those places occur before the proxy can be initialized, return whether our init() function has been called \(aq\(aq\(aq return DETAILS.get(\(aqinitialized\(aq, False) def grains(): \(aq\(aq\(aq Get the grains from the proxied device \(aq\(aq\(aq if not DETAILS.get(\(aqgrains_cache\(aq, {}): r = salt.utils.http.query(DETAILS[\(aqurl\(aq]+\(aqinfo\(aq, decode_type=\(aqjson\(aq, decode=True) DETAILS[\(aqgrains_cache\(aq] = r[\(aqdict\(aq] return DETAILS[\(aqgrains_cache\(aq] def grains_refresh(): \(aq\(aq\(aq Refresh the grains from the proxied device \(aq\(aq\(aq DETAILS[\(aqgrains_cache\(aq] = None return grains() def fns(): return {\(aqdetails\(aq: \(aqThis key is here because a function in \(aq \(aqgrains/rest_sample.py called fns() here in the proxymodule.\(aq} def service_start(name): \(aq\(aq\(aq Start a "service" on the REST server \(aq\(aq\(aq r = salt.utils.http.query(DETAILS[\(aqurl\(aq]+\(aqservice/start/\(aq+name, decode_type=\(aqjson\(aq, decode=True) return r[\(aqdict\(aq] def service_stop(name): \(aq\(aq\(aq Stop a "service" on the REST server \(aq\(aq\(aq r = salt.utils.http.query(DETAILS[\(aqurl\(aq]+\(aqservice/stop/\(aq+name, decode_type=\(aqjson\(aq, decode=True) return r[\(aqdict\(aq] def service_restart(name): \(aq\(aq\(aq Restart a "service" on the REST server \(aq\(aq\(aq r = salt.utils.http.query(DETAILS[\(aqurl\(aq]+\(aqservice/restart/\(aq+name, decode_type=\(aqjson\(aq, decode=True) return r[\(aqdict\(aq] def service_list(): \(aq\(aq\(aq List "services" on the REST server \(aq\(aq\(aq r = salt.utils.http.query(DETAILS[\(aqurl\(aq]+\(aqservice/list\(aq, decode_type=\(aqjson\(aq, decode=True) return r[\(aqdict\(aq] def service_status(name): \(aq\(aq\(aq Check if a service is running on the REST server \(aq\(aq\(aq r = salt.utils.http.query(DETAILS[\(aqurl\(aq]+\(aqservice/status/\(aq+name, decode_type=\(aqjson\(aq, decode=True) return r[\(aqdict\(aq] def package_list(): \(aq\(aq\(aq List "packages" installed on the REST server \(aq\(aq\(aq r = salt.utils.http.query(DETAILS[\(aqurl\(aq]+\(aqpackage/list\(aq, decode_type=\(aqjson\(aq, decode=True) return r[\(aqdict\(aq] def package_install(name, **kwargs): \(aq\(aq\(aq Install a "package" on the REST server \(aq\(aq\(aq cmd = DETAILS[\(aqurl\(aq]+\(aqpackage/install/\(aq+name if kwargs.get(\(aqversion\(aq, False): cmd += \(aq/\(aq+kwargs[\(aqversion\(aq] else: cmd += \(aq/1.0\(aq r = salt.utils.http.query(cmd, decode_type=\(aqjson\(aq, decode=True) return r[\(aqdict\(aq] def fix_outage(): r = salt.utils.http.query(DETAILS[\(aqurl\(aq]+\(aqfix_outage\(aq) return r def uptodate(name): \(aq\(aq\(aq Call the REST endpoint to see if the packages on the "server" are up to date. \(aq\(aq\(aq r = salt.utils.http.query(DETAILS[\(aqurl\(aq]+\(aqpackage/remove/\(aq+name, decode_type=\(aqjson\(aq, decode=True) return r[\(aqdict\(aq] def package_remove(name): \(aq\(aq\(aq Remove a "package" on the REST server \(aq\(aq\(aq r = salt.utils.http.query(DETAILS[\(aqurl\(aq]+\(aqpackage/remove/\(aq+name, decode_type=\(aqjson\(aq, decode=True) return r[\(aqdict\(aq] def package_status(name): \(aq\(aq\(aq Check the installation status of a package on the REST server \(aq\(aq\(aq r = salt.utils.http.query(DETAILS[\(aqurl\(aq]+\(aqpackage/status/\(aq+name, decode_type=\(aqjson\(aq, decode=True) return r[\(aqdict\(aq] def ping(): \(aq\(aq\(aq Is the REST server up? \(aq\(aq\(aq r = salt.utils.http.query(DETAILS[\(aqurl\(aq]+\(aqping\(aq, decode_type=\(aqjson\(aq, decode=True) try: return r[\(aqdict\(aq].get(\(aqret\(aq, False) except Exception: return False def shutdown(opts): \(aq\(aq\(aq For this proxy shutdown is a no\-op \(aq\(aq\(aq log.debug(\(aqrest_sample proxy shutdown() called...\(aq) .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. By default, a proxy minion will have several grains taken from the host. Salt core code requires values for \fBkernel\fP, \fBos\fP, and \fBos_family\fP\-\-all of these are forced to be \fBproxy\fP for proxy\-minions. .sp To add others 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. Note the function below called \fBproxy_functions\fP\&. It demonstrates how a grains function can take a single argument, which will be set to the value of \fB__proxy__\fP\&. Dunder variables are not yet injected into Salt processes at the time grains are loaded, so this enables us to get a handle to the proxymodule so we can cross\-call the functions therein used to commmunicate with the controlled device. .sp Note that as of 2016.3, grains values can also be calculated in a function called \fBgrains()\fP in the proxymodule itself. This might be useful if a proxymodule author wants to keep all the code for the proxy interface in the same place instead of splitting it between the proxy and grains directories. .sp This function will only be called automatically if the configuration variable \fBproxy_merge_grains_in_module\fP is set to True in the proxy configuration file (default \fB/etc/salt/proxy\fP). This variable will default to True in the release code\-named \fINitrogen\fP\&. .SS The __proxyenabled__ directive .sp In previous versions of Salt the \fB__proxyenabled__\fP directive controlled loading of all Salt modules for proxies (e.g. grains, execution modules, state modules). From 2016.3 on, the only modules that respect \fB__proxyenabled__\fP are grains and proxy modules. These modules need to be told which proxy they work with. .sp \fB__proxyenabled__\fP is a list, and can contain a single \(aq*\(aq to indicate a grains module works with all proxies. .sp Example from \fBsalt/grains/rest_sample.py\fP: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C # \-*\- coding: utf\-8 \-*\- \(aq\(aq\(aq Generate baseline proxy minion grains \(aq\(aq\(aq from __future__ import absolute_import import salt.utils __proxyenabled__ = [\(aqrest_sample\(aq] __virtualname__ = \(aqrest_sample\(aq def __virtual__(): try: if salt.utils.is_proxy() and __opts__[\(aqproxy\(aq][\(aqproxytype\(aq] == \(aqrest_sample\(aq: return __virtualname__ except KeyError: pass return False .ft P .fi .UNINDENT .UNINDENT .SS Salt Proxy Minion End\-to\-End Example .sp The following is walkthrough that documents how to run a sample REST service and configure one or more proxy minions to talk to and control it. .INDENT 0.0 .IP 1. 3 Ideally, create a Python virtualenv in which to run the REST service. This is not strictly required, but without a virtualenv you will need to install \fBbottle\fP via pip globally on your system .IP 2. 3 Clone \fI\%https://github.com/saltstack/salt\-contrib\fP and copy the contents of the directory \fBproxyminion_rest_example\fP somewhere on a machine that is reachable from the machine on which you want to run the salt\-proxy. This machine needs Python 2.7 or later. .IP 3. 3 Install bottle version 0.12.8 via pip or easy_install .UNINDENT .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C pip install bottle==0.12.8 .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .IP 4. 3 Run \fBpython rest.py \-\-help\fP for usage .IP 5. 3 Start the REST API on an appropriate port and IP. .IP 6. 3 Load the REST service\(aqs status page in your browser by going to the IP/port combination (e.g. \fI\%http://127.0.0.1:8000\fP) .IP 7. 3 You should see a page entitled "Salt Proxy Minion" with two sections, one for "services" and one for "packages" and you should see a log entry in the terminal where you started the REST process indicating that the index page was retrieved. .UNINDENT [image] .sp Now, configure your salt\-proxy. .INDENT 0.0 .IP 1. 3 Edit \fB/etc/salt/proxy\fP and add an entry for your master\(aqs location .UNINDENT .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C master: localhost .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .IP 2. 3 On your salt\-master, ensure that pillar is configured properly. Select an ID for your proxy (in this example we will name the proxy with the letter \(aqp\(aq followed by the port the proxy is answering on). In your pillar topfile, place an entry for your proxy: .UNINDENT .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C base: \(aqp8000\(aq: \- p8000 .ft P .fi .UNINDENT .UNINDENT .sp This says that Salt\(aqs pillar should load some values for the proxy \fBp8000\fP from the file /srv/pillar/p8000.sls (if you have not changed your default pillar_roots) .INDENT 0.0 .IP 3. 3 In the pillar root for your base environment, create this file: .UNINDENT .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C p8000.sls \-\-\-\-\-\-\-\-\- proxy: proxytype: rest_sample url: http://:port .ft P .fi .UNINDENT .UNINDENT .sp In other words, if your REST service is listening on port 8000 on 127.0.0.1 the \(aqurl\(aq key above should say \fBurl: http://127.0.0.1:8000\fP .INDENT 0.0 .IP 4. 3 Make sure your salt\-master is running. .IP 5. 3 Start the salt\-proxy in debug mode .UNINDENT .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt\-proxy \-\-proxyid=p8000 \-l debug .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .IP 6. 3 Accept your proxy\(aqs key on your salt\-master .UNINDENT .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt\-key \-y \-a p8000 The following keys are going to be accepted: Unaccepted Keys: p8000 Key for minion p8000 accepted. .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .IP 7. 3 Now you should be able to ping your proxy. When you ping, you should see a log entry in the terminal where the REST service is running. .UNINDENT .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt p8000 test.ping .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .IP 8. 3 The REST service implements a degenerately simple pkg and service provider as well as a small set of grains. To "install" a package, use a standard \fBpkg.install\fP\&. If you pass \(aq==\(aq and a verrsion number after the package name then the service will parse that and accept that as the package\(aqs version. .IP 9. 3 Try running \fBsalt p8000 grains.items\fP to see what grains are available. You can target proxies via grains if you like. .IP 10. 3 You can also start and stop the available services (apache, redbull, and postgresql with \fBservice.start\fP, etc. .IP 11. 3 States can be written to target the proxy. Feel free to experiment with them. .UNINDENT .SS SSH Proxymodules .sp See above for a general introduction to writing proxy modules. All of the guidelines that apply to REST are the same for SSH. This sections specifically talks about the SSH proxy module and explains the working of the example proxy module \fBssh_sample\fP\&. .sp Here is a simple example proxymodule used to interface to a device over SSH. Code for the SSH shell is in the \fI\%salt\-contrib GitHub repository\fP .sp This proxymodule enables "package" installation. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C # \-*\- coding: utf\-8 \-*\- \(aq\(aq\(aq This is a simple proxy\-minion designed to connect to and communicate with a server that exposes functionality via SSH. This can be used as an option when the device does not provide an api over HTTP and doesn\(aqt have the python stack to run a minion. \(aq\(aq\(aq from __future__ import absolute_import # Import python libs import json import logging # Import Salt\(aqs libs from salt.utils.vt_helper import SSHConnection from salt.utils.vt import TerminalException # This must be present or the Salt loader won\(aqt load this module __proxyenabled__ = [\(aqssh_sample\(aq] DETAILS = {} # Want logging! log = logging.getLogger(__file__) # This does nothing, it\(aqs here just as an example and to provide a log # entry when the module is loaded. def __virtual__(): \(aq\(aq\(aq Only return if all the modules are available \(aq\(aq\(aq log.info(\(aqssh_sample proxy __virtual__() called...\(aq) return True def init(opts): \(aq\(aq\(aq Required. Can be used to initialize the server connection. \(aq\(aq\(aq try: DETAILS[\(aqserver\(aq] = SSHConnection(host=__opts__[\(aqproxy\(aq][\(aqhost\(aq], username=__opts__[\(aqproxy\(aq][\(aqusername\(aq], password=__opts__[\(aqproxy\(aq][\(aqpassword\(aq]) # connected to the SSH server out, err = DETAILS[\(aqserver\(aq].sendline(\(aqhelp\(aq) except TerminalException as e: log.error(e) return False def shutdown(opts): \(aq\(aq\(aq Disconnect \(aq\(aq\(aq DETAILS[\(aqserver\(aq].close_connection() def parse(out): \(aq\(aq\(aq Extract json from out. Parameter out: Type string. The data returned by the ssh command. \(aq\(aq\(aq jsonret = [] in_json = False for ln_ in out.split(\(aq\en\(aq): if \(aq{\(aq in ln_: in_json = True if in_json: jsonret.append(ln_) if \(aq}\(aq in ln_: in_json = False return json.loads(\(aq\en\(aq.join(jsonret)) def package_list(): \(aq\(aq\(aq List "packages" by executing a command via ssh This function is called in response to the salt command ..code\-block::bash salt target_minion pkg.list_pkgs \(aq\(aq\(aq # Send the command to execute out, err = DETAILS[\(aqserver\(aq].sendline(\(aqpkg_list\(aq) # "scrape" the output and return the right fields as a dict return parse(out) def package_install(name, **kwargs): \(aq\(aq\(aq Install a "package" on the REST server \(aq\(aq\(aq cmd = \(aqpkg_install \(aq + name if \(aqversion\(aq in kwargs: cmd += \(aq/\(aq+kwargs[\(aqversion\(aq] else: cmd += \(aq/1.0\(aq # Send the command to execute out, err = DETAILS[\(aqserver\(aq].sendline(cmd) # "scrape" the output and return the right fields as a dict return parse(out) def package_remove(name): \(aq\(aq\(aq Remove a "package" on the REST server \(aq\(aq\(aq cmd = \(aqpkg_remove \(aq + name # Send the command to execute out, err = DETAILS[\(aqserver\(aq].sendline(cmd) # "scrape" the output and return the right fields as a dict return parse(out) .ft P .fi .UNINDENT .UNINDENT .SS Connection Setup .sp The \fBinit()\fP method is responsible for connection setup. It uses the \fBhost\fP, \fBusername\fP and \fBpassword\fP config variables defined in the pillar data. The \fBprompt\fP kwarg can be passed to \fBSSHConnection\fP if your SSH server\(aqs prompt differs from the example\(aqs prompt \fB(Cmd)\fP\&. Instantiating the \fBSSHConnection\fP class establishes an SSH connection to the ssh server (using Salt VT). .SS Command execution .sp The \fBpackage_*\fP methods use the SSH connection (established in \fBinit()\fP) to send commands out to the SSH server. The \fBsendline()\fP method of \fBSSHConnection\fP class can be used to send commands out to the server. In the above example we send commands like \fBpkg_list\fP or \fBpkg_install\fP\&. You can send any SSH command via this utility. .SS Output parsing .sp Output returned by \fBsendline()\fP is a tuple of strings representing the stdout and the stderr respectively. In the toy example shown we simply scrape the output and convert it to a python dictionary, as shown in the \fBparse\fP method. You can tailor this method to match your parsing logic. .SS Connection teardown .sp The \fBshutdown\fP method is responsible for calling the \fBclose_connection()\fP method of \fBSSHConnection\fP class. This ends the SSH connection to the server. .sp For more information please refer to class \fI\%SSHConnection\fP\&. .SS Salt Proxy Minion SSH End\-to\-End Example .sp The following is walkthrough that documents how to run a sample SSH service and configure one or more proxy minions to talk to and control it. .INDENT 0.0 .IP 1. 3 This walkthrough uses a custom SSH shell to provide an end to end example. Any other shells can be used too. .IP 2. 3 Setup the proxy command shell as shown \fI\%https://github.com/saltstack/salt\-contrib/tree/master/proxyminion_ssh_example\fP .UNINDENT .sp Now, configure your salt\-proxy. .INDENT 0.0 .IP 1. 3 Edit \fB/etc/salt/proxy\fP and add an entry for your master\(aqs location .UNINDENT .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C master: localhost multiprocessing: False .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .IP 2. 3 On your salt\-master, ensure that pillar is configured properly. Select an ID for your proxy (in this example we will name the proxy with the letter \(aqp\(aq followed by the port the proxy is answering on). In your pillar topfile, place an entry for your proxy: .UNINDENT .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C base: \(aqp8000\(aq: \- p8000 .ft P .fi .UNINDENT .UNINDENT .sp This says that Salt\(aqs pillar should load some values for the proxy \fBp8000\fP from the file /srv/pillar/p8000.sls (if you have not changed your default pillar_roots) .INDENT 0.0 .IP 3. 3 In the pillar root for your base environment, create this file: .UNINDENT .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C p8000.sls \-\-\-\-\-\-\-\-\- proxy: proxytype: ssh_sample host: saltyVM username: salt password: badpass .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .IP 4. 3 Make sure your salt\-master is running. .IP 5. 3 Start the salt\-proxy in debug mode .UNINDENT .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt\-proxy \-\-proxyid=p8000 \-l debug .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .IP 6. 3 Accept your proxy\(aqs key on your salt\-master .UNINDENT .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt\-key \-y \-a p8000 The following keys are going to be accepted: Unaccepted Keys: p8000 Key for minion p8000 accepted. .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .IP 7. 3 Now you should be able to run commands on your proxy. .UNINDENT .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt p8000 pkg.list_pkgs .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .IP 8. 3 The SSH shell implements a degenerately simple pkg. To "install" a package, use a standard \fBpkg.install\fP\&. If you pass \(aq==\(aq and a verrsion number after the package name then the service will parse that and accept that as the package\(aqs version. .UNINDENT New in version 2015.8.3. .SS Proxy Minion Beacon .sp The salt proxy beacon is meant to facilitate configuring multiple proxies on one or many minions. This should simplify configuring and managing multiple \fBsalt\-proxy\fP processes. .INDENT 0.0 .IP 1. 3 On your salt\-master, ensure that pillar is configured properly. Select an ID for your proxy (in this example we will name the proxy \(aqp8000\(aq). In your pillar topfile, place an entry for your proxy: .UNINDENT .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C base: \(aqp8000\(aq: \- p8000 .ft P .fi .UNINDENT .UNINDENT .sp This says that Salt\(aqs pillar should load some values for the proxy \fBp8000\fP from the file /srv/pillar/p8000.sls (if you have not changed your default pillar_roots) .INDENT 0.0 .IP 2. 3 In the pillar root for your base environment, create this file: .UNINDENT .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C p8000.sls \-\-\-\-\-\-\-\-\- proxy: # set proxytype for your proxymodule proxytype: ssh_sample host: saltyVM username: salt password: badpass .ft P .fi .UNINDENT .UNINDENT .sp This should complete the proxy setup for \fBp8000\fP .INDENT 0.0 .IP 3. 3 \fI\%Configure\fP the \fBsalt_proxy\fP beacon .UNINDENT .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C beacons: salt_proxy: \- p8000: {} .ft P .fi .UNINDENT .UNINDENT .sp Once this beacon is configured it will automatically start the \fBsalt\-proxy\fP process. If the \fBsalt\-proxy\fP process is terminated the beacon will re\-start it. .INDENT 0.0 .IP 4. 3 Accept your proxy\(aqs key on your salt\-master .UNINDENT .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt\-key \-y \-a p8000 The following keys are going to be accepted: Unaccepted Keys: p8000 Key for minion p8000 accepted. .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .IP 5. 3 Now you should be able to run commands on your proxy. .UNINDENT .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt p8000 pkg.list_pkgs .ft P .fi .UNINDENT .UNINDENT New in version 2015.8.2. .SS Proxy Minion States .sp Salt proxy state can be used to deploy, configure and run a \fBsalt\-proxy\fP instance on your minion. Configure proxy settings on the master side and the state configures and runs \fBsalt\-proxy\fP on the remote end. .INDENT 0.0 .IP 1. 3 On your salt\-master, ensure that pillar is configured properly. Select an ID for your proxy (in this example we will name the proxy \(aqp8000\(aq). In your pillar topfile, place an entry for your proxy: .UNINDENT .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C base: \(aqp8000\(aq: \- p8000 .ft P .fi .UNINDENT .UNINDENT .sp This says that Salt\(aqs pillar should load some values for the proxy \fBp8000\fP from the file /srv/pillar/p8000.sls (if you have not changed your default pillar_roots) .INDENT 0.0 .IP 2. 3 In the pillar root for your base environment, create this file: .UNINDENT .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C p8000.sls \-\-\-\-\-\-\-\-\- proxy: # set proxytype for your proxymodule proxytype: ssh_sample host: saltyVM username: salt password: badpass .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .IP 3. 3 Create the following state in your state tree (let\(aqs name it salt_proxy.sls) .UNINDENT .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt\-proxy\-configure: salt_proxy.configure_proxy: \- proxyname: p8000 \- start: True # start the process if it isn\(aqt running .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .IP 4. 3 Make sure your salt\-master and salt\-minion are running. .IP 5. 3 Run the state salt_proxy on the minion where you want to run \fBsalt\-proxy\fP .UNINDENT .sp Example using \fBstate.sls\fP to configure and run \fBsalt\-proxy\fP .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C # salt device_minion state.sls salt_proxy .ft P .fi .UNINDENT .UNINDENT .sp This starts salt\-proxy on \fBdevice_minion\fP .INDENT 0.0 .IP 6. 3 Accept your proxy\(aqs key on your salt\-master .UNINDENT .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt\-key \-y \-a p8000 The following keys are going to be accepted: Unaccepted Keys: p8000 Key for minion p8000 accepted. .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .IP 7. 3 Now you should be able to run commands on your proxy. .UNINDENT .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt p8000 pkg.list_pkgs .ft P .fi .UNINDENT .UNINDENT .SS ESXi Proxy Minion .sp New in version 2015.8.4. .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 This tutorial assumes basic knowledge of Salt. To get up to speed, check out the Salt Walkthrough\&. .sp This tutorial also assumes a basic understanding of Salt Proxy Minions. If you\(aqre unfamiliar with Salt\(aqs Proxy Minion system, please read the Salt Proxy Minion documentation and the Salt Proxy Minion End\-to\-End Example tutorial. .sp The third assumption that this tutorial makes is that you also have a basic understanding of ESXi hosts. You can learn more about ESXi hosts on \fI\%VMware\(aqs various resources\fP\&. .UNINDENT .UNINDENT .sp Salt\(aqs ESXi Proxy Minion allows a VMware ESXi host to be treated as an individual Salt Minion, without installing a Salt Minion on the ESXi host. .sp Since an ESXi host may not necessarily run on an OS capable of hosting a Python stack, the ESXi host can\(aqt run a regular Salt Minion directly. Therefore, Salt\(aqs Proxy Minion functionality enables you to designate another machine to host a proxy process that "proxies" communication from the Salt Master to the ESXi host. The master does not know or care that the ESXi target is not a "real" Salt Minion. .sp More in\-depth conceptual reading on Proxy Minions can be found in the Proxy Minion section of Salt\(aqs documentation. .sp Salt\(aqs ESXi Proxy Minion was added in the 2015.8.4 release of Salt. .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 Be aware that some functionality for the ESXi Proxy Minion may depend on the type of license attached the ESXi host(s). .sp For example, certain services are only available to manipulate service state or policies with a VMware vSphere Enterprise or Enterprise Plus license, while others are available with a Standard license. The \fBntpd\fP service is restricted to an Enterprise Plus license, while \fBssh\fP is available via the Standard license. .sp Please see the \fI\%vSphere Comparison\fP page for more information. .UNINDENT .UNINDENT .SS Dependencies .sp Manipulation of the ESXi host via a Proxy Minion requires the machine running the Proxy Minion process to have the ESXCLI package (and all of it\(aqs dependencies) and the pyVmomi Python Library to be installed. .SS ESXi Password .sp The ESXi Proxy Minion uses VMware\(aqs API to perform tasks on the host as if it was a regular Salt Minion. In order to access the API that is already running on the ESXi host, the ESXi host must have a username and password that is used to log into the host. The username is usually \fBroot\fP\&. Before Salt can access the ESXi host via VMware\(aqs API, a default password \fImust\fP be set on the host. .SS pyVmomi .sp The pyVmomi Python library must be installed on the machine that is running the proxy process. pyVmomi can be installed via pip: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C pip install pyVmomi .ft P .fi .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 Version 6.0 of pyVmomi has some problems with SSL error handling on certain versions of Python. If using version 6.0 of pyVmomi, the machine that you are running the proxy minion process from must have either Python 2.6, Python 2.7.9, or newer. This is due to an upstream dependency in pyVmomi 6.0 that is not supported in Python version 2.7 to 2.7.8. If the version of Python running the proxy process is not in the supported range, you will need to install an earlier version of pyVmomi. See \fI\%Issue #29537\fP for more information. .UNINDENT .UNINDENT .sp Based on the note above, to install an earlier version of pyVmomi than the version currently listed in PyPi, run the following: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C pip install pyVmomi==5.5.0.2014.1.1 .ft P .fi .UNINDENT .UNINDENT .sp The 5.5.0.2014.1.1 is a known stable version that the original ESXi Proxy Minion was developed against. .SS ESXCLI .sp Currently, about a third of the functions used for the ESXi Proxy Minion require the ESXCLI package be installed on the machine running the Proxy Minion process. .sp The ESXCLI package is also referred to as the VMware vSphere CLI, or vCLI. VMware provides vCLI package installation instructions for \fI\%vSphere 5.5\fP and \fI\%vSphere 6.0\fP\&. .sp Once all of the required dependencies are in place and the vCLI package is installed, you can check to see if you can connect to your ESXi host by running the following command: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C esxcli \-s \-u \-p system syslog config get .ft P .fi .UNINDENT .UNINDENT .sp If the connection was successful, ESXCLI was successfully installed on your system. You should see output related to the ESXi host\(aqs syslog configuration. .SS Configuration .sp There are several places where various configuration values need to be set in order for the ESXi Proxy Minion to run and connect properly. .SS Proxy Config File .sp On the machine that will be running the Proxy Minon process(es), a proxy config file must be in place. This file should be located in the \fB/etc/salt/\fP directory and should be named \fBproxy\fP\&. If the file is not there by default, create it. .sp This file should contain the location of your Salt Master that the Salt Proxy will connect to. .sp Example Proxy Config File: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C # /etc/salt/proxy master: .ft P .fi .UNINDENT .UNINDENT .SS Pillar Profiles .sp Proxy minions get their configuration from Salt\(aqs Pillar. Every proxy must have a stanza in Pillar and a reference in the Pillar top\-file that matches the Proxy ID. At a minimum for communication with the ESXi host, the pillar should look like this: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C proxy: proxytype: esxi host: username: passwords: \- first_password \- second_password \- third_password .ft P .fi .UNINDENT .UNINDENT .sp Some other optional settings are \fBprotocol\fP and \fBport\fP\&. These can be added to the pillar configuration. .SS proxytype .sp The \fBproxytype\fP key and value pair is critical, as it tells Salt which interface to load from the \fBproxy\fP directory in Salt\(aqs install hierarchy, or from \fB/srv/salt/_proxy\fP on the Salt Master (if you have created your own proxy module, for example). To use this ESXi Proxy Module, set this to \fBesxi\fP\&. .SS host .sp The location, or ip/dns, of the ESXi host. Required. .SS username .sp The username used to login to the ESXi host, such as \fBroot\fP\&. Required. .SS passwords .sp A list of passwords to be used to try and login to the ESXi host. At least one password in this list is required. .sp The proxy integration will try the passwords listed in order. It is configured this way so you can have a regular password and the password you may be updating for an ESXi host either via the \fBvsphere.update_host_password\fP execution module function or via the \fBesxi.password_present\fP state function. This way, after the password is changed, you should not need to restart the proxy minion\-\-it should just pick up the the new password provided in the list. You can then change pillar at will to move that password to the front and retire the unused ones. .sp Use\-case/reasoning for using a list of passwords: You are setting up an ESXi host for the first time, and the host comes with a default password. You know that you\(aqll be changing this password during your initial setup from the default to a new password. If you only have one password option, and if you have a state changing the password, any remote execution commands or states that run after the password change will not be able to run on the host until the password is updated in Pillar and the Proxy Minion process is restarted. .sp This allows you to use any number of potential fallback passwords. .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 When a password is changed on the host to one in the list of possible passwords, the further down on the list the password is, the longer individual commands will take to return. This is due to the nature of pyVmomi\(aqs login system. We have to wait for the first attempt to fail before trying the next password on the list. .sp This scenario is especially true, and even slower, when the proxy minion first starts. If the correct password is not the first password on the list, it may take up to a minute for \fBtest.ping\fP to respond with a \fBTrue\fP result. Once the initial authorization is complete, the responses for commands will be a little faster. .sp To avoid these longer waiting periods, SaltStack recommends moving the correct password to the top of the list and restarting the proxy minion at your earliest convenience. .UNINDENT .UNINDENT .SS protocol .sp If the ESXi host is not using the default protocol, set this value to an alternate protocol. Default is \fBhttps\fP\&. For example: .SS port .sp If the ESXi host is not using the default port, set this value to an alternate port. Default is \fB443\fP\&. .SS Example Configuration Files .sp An example of all of the basic configurations that need to be in place before starting the Proxy Minion processes includes the Proxy Config File, Pillar Top File, and any individual Proxy Minion Pillar files. .sp In this example, we\(aqll assuming there are two ESXi hosts to connect to. Therefore, we\(aqll be creating two Proxy Minion config files, one config for each ESXi host. .sp Proxy Config File: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C # /etc/salt/proxy master: .ft P .fi .UNINDENT .UNINDENT .sp Pillar Top File: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C # /srv/pillar/top.sls base: \(aqesxi\-1\(aq: \- esxi\-1 \(aqesxi\-2\(aq: \- esxi\-2 .ft P .fi .UNINDENT .UNINDENT .sp Pillar Config File for the first ESXi host, esxi\-1: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C # /srv/pillar/esxi\-1.sls proxy: proxytype: esxi host: esxi\-1.example.com username: \(aqroot\(aq passwords: \- bad\-password\-1 \- backup\-bad\-password\-1 .ft P .fi .UNINDENT .UNINDENT .sp Pillar Config File for the second ESXi host, esxi\-2: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C # /srv/pillar/esxi\-2.sls proxy: proxytype: esxi host: esxi\-2.example.com username: \(aqroot\(aq passwords: \- bad\-password\-2 \- backup\-bad\-password\-2 .ft P .fi .UNINDENT .UNINDENT .SS Starting the Proxy Minion .sp Once all of the correct configuration files are in place, it is time to start the proxy processes! .INDENT 0.0 .IP 1. 3 First, make sure your Salt Master is running. .IP 2. 3 Start the first Salt Proxy, in debug mode, by giving the Proxy Minion process and ID that matches the config file name created in the \fI\%Configuration\fP section. .UNINDENT .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt\-proxy \-\-proxyid=\(aqesxi\-1\(aq \-l debug .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .IP 1. 3 Accept the \fBesxi\-1\fP Proxy Minion\(aqs key on the Salt Master: .UNINDENT .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C # salt\-key \-L Accepted Keys: Denied Keys: Unaccepted Keys: esxi\-1 Rejected Keys: # # salt\-key \-a esxi\-1 The following keys are going to be accepted: Unaccepted Keys: esxi\-1 Proceed? [n/Y] y Key for minion esxi\-1 accepted. .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .IP 1. 3 Repeat for the second Salt Proxy, this time we\(aqll run the proxy process as a daemon, as an example. .UNINDENT .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt\-proxy \-\-proxyid=\(aqesxi\-2\(aq \-d .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .IP 1. 3 Accept the \fBesxi\-2\fP Proxy Minion\(aqs key on the Salt Master: .UNINDENT .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C # salt\-key \-L Accepted Keys: esxi\-1 Denied Keys: Unaccepted Keys: esxi\-2 Rejected Keys: # # salt\-key \-a esxi\-1 The following keys are going to be accepted: Unaccepted Keys: esxi\-2 Proceed? [n/Y] y Key for minion esxi\-1 accepted. .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .IP 1. 3 Check and see if your Proxy Minions are responding: .UNINDENT .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C # salt \(aqesxi\-*\(aq test.ping esxi\-1: True esxi\-3: True .ft P .fi .UNINDENT .UNINDENT .SS Executing Commands .sp Now that you\(aqve configured your Proxy Minions and have them responding successfully to a \fBtest.ping\fP, we can start executing commands against the ESXi hosts via Salt. .sp It\(aqs important to understand how this particular proxy works, and there are a couple of important pieces to be aware of in order to start running remote execution and state commands against the ESXi host via a Proxy Minion: the \fI\%vSphere Execution Module\fP, the \fI\%ESXi Execution Module\fP, and the \fI\%ESXi State Module\fP\&. .SS vSphere Execution Module .sp The \fBSalt.modules.vsphere\fP is a standard Salt execution module that does the bulk of the work for the ESXi Proxy Minion. If you pull up the docs for it you\(aqll see that almost every function in the module takes credentials (\fBusername\fP and \fBpassword\fP) and a target \fBhost\fP argument. When credentials and a host aren\(aqt passed, Salt runs commands through \fBpyVmomi\fP or \fBESXCLI\fP against the local machine. If you wanted, you could run functions from this module on any machine where an appropriate version of \fBpyVmomi\fP and \fBESXCLI\fP are installed, and that machine would reach out over the network and communicate with the ESXi host. .sp You\(aqll notice that most of the functions in the vSphere module require a \fBhost\fP, \fBusername\fP, and \fBpassword\fP\&. These parameters are contained in the Pillar files and passed through to the function via the proxy process that is already running. You don\(aqt need to provide these parameters when you execute the commands. See the \fI\%Running Remote Execution Commands\fP section below for an example. .SS ESXi Execution Module .sp In order for the Pillar information set up in the \fI\%Configuration\fP section above to be passed to the function call in the vSphere Execution Module, the \fBsalt.modules.esxi\fP execution module acts as a "shim" between the vSphere execution module functions and the proxy process. .sp The "shim" takes the authentication credentials specified in the Pillar files and passes them through to the \fBhost\fP, \fBusername\fP, \fBpassword\fP, and optional \fBprotocol\fP and \fBport\fP options required by the vSphere Execution Module functions. .sp If the function takes more positional, or keyword, arguments you can append them to the call. It\(aqs this shim that speaks to the ESXi host through the proxy, arranging for the credentials and hostname to be pulled from the Pillar section for the ESXi Proxy Minion. .sp Because of the presence of the shim, to lookup documentation for what functions you can use to interface with the ESXi host, you\(aqll want to look in \fBsalt.modules.vsphere\fP instead of \fBsalt.modules.esxi\fP\&. .SS Running Remote Execution Commands .sp To run commands from the Salt Master to execute, via the ESXi Proxy Minion, against the ESXi host, you use the \fBesxi.cmd \fP syntax to call functions located in the vSphere Execution Module. Both args and kwargs needed for various vsphere execution module functions must be passed through in a kwarg\- type manor. For example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt \(aqesxi\-*\(aq esxi.cmd system_info salt \(aqexsi\-*\(aq esxi.cmd get_service_running service_name=\(aqssh\(aq .ft P .fi .UNINDENT .UNINDENT .SS ESXi State Module .sp The ESXi State Module functions similarly to other state modules. The "shim" provided by the \fI\%ESXi Execution Module\fP passes the necessary \fBhost\fP, \fBusername\fP, and \fBpassword\fP credentials through, so those options don\(aqt need to be provided in the state. Other than that, state files are written and executed just like any other Salt state. See the \fBsalt.modules.esxi\fP state for ESXi state functions. .sp The follow state file is an example of how to configure various pieces of an ESXi host including enabling SSH, uploading and SSH key, configuring a coredump network config, syslog, ntp, enabling VMotion, resetting a host password, and more. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C # /srv/salt/configure\-esxi.sls configure\-host\-ssh: esxi.ssh_configured: \- service_running: True \- ssh_key_file: /etc/salt/ssh_keys/my_key.pub \- service_policy: \(aqautomatic\(aq \- service_restart: True \- certificate_verify: True configure\-host\-coredump: esxi.coredump_configured: \- enabled: True \- dump_ip: \(aqmy\-coredump\-ip.example.com\(aq configure\-host\-syslog: esxi.syslog_configured: \- syslog_configs: loghost: ssl://localhost:5432,tcp://10.1.0.1:1514 default\-timeout: 120 \- firewall: True \- reset_service: True \- reset_syslog_config: True \- reset_configs: loghost,default\-timeout configure\-host\-ntp: esxi.ntp_configured: \- service_running: True \- ntp_servers: \- 192.174.1.100 \- 192.174.1.200 \- service_policy: \(aqautomatic\(aq \- service_restart: True configure\-vmotion: esxi.vmotion_configured: \- enabled: True configure\-host\-vsan: esxi.vsan_configured: \- enabled: True \- add_disks_to_vsan: True configure\-host\-password: esxi.password_present: \- password: \(aqnew\-bad\-password\(aq .ft P .fi .UNINDENT .UNINDENT .sp States are called via the ESXi Proxy Minion just as they would on a regular minion. For example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt \(aqesxi\-*\(aq state.sls configure\-esxi test=true salt \(aqesxi\-*\(aq state.sls configure\-esxi .ft P .fi .UNINDENT .UNINDENT .SS Relevant Salt Files and Resources .INDENT 0.0 .IP \(bu 2 \fBESXi Proxy Minion\fP .IP \(bu 2 \fBESXi Execution Module\fP .IP \(bu 2 \fBESXi State Module\fP .IP \(bu 2 Salt Proxy Minion Docs .IP \(bu 2 Salt Proxy Minion End\-to\-End Example .IP \(bu 2 \fBvSphere Execution Module\fP .UNINDENT .SH SALT VIRT .sp The Salt Virt cloud controller capability was initially 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 .sp \fBWARNING:\fP .INDENT 0.0 .INDENT 3.5 Salt Virt does not work with KVM that is running in a VM. KVM must be running on the base hardware. .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 Cloud Controller Tutorial .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. .SS Deploy from Network or Disk .SS 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. .SS 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. .SS Salt as a Cloud Controller .sp In Salt 0.14.0, an advanced cloud control system were introduced, allow 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 besides setting up Salt, no additional salt code needs to be deployed. .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 The \fBlibvirt\fP python module and the \fBcerttool\fP binary are required. .UNINDENT .UNINDENT .sp The main goal of Salt Virt is to facilitate a very fast and simple cloud. The cloud that can scale and is fully featured. 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 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 virt.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 Salt Virt Networking .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: virt.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 kiwi: (openSUSE, SLES, RHEL, CentOS) \fI\%https://suse.github.io/kiwi/\fP .TP .B vm\-builder: \fI\%https://wiki.debian.org/VMBuilder\fP .sp \fBSEE ALSO:\fP .INDENT 7.0 .INDENT 3.5 \fI\%vmbuilder\-formula\fP .UNINDENT .UNINDENT .UNINDENT .sp Once virtual machine 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://fedoraproject.org/en/get\-fedora#clouds\fP .SS openSUSE .sp \fI\%http://download.opensuse.org/repositories/openSUSE:/Leap:/42.1:/Images/images\fP .sp (look for JeOS\-for\-kvm\-and\-xen variant) .SS SUSE .sp \fI\%https://www.suse.com/products/server/jeos\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 Opening the Firewall up for Salt .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. .SH COMMAND LINE REFERENCE .SS salt\-call .SS \fBsalt\-call\fP .SS Synopsis .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt\-call [options] .ft P .fi .UNINDENT .UNINDENT .SS Description .sp The salt\-call command is used to run module functions locally on a minion instead of executing them from the master. Salt\-call is used to run a Standalone Minion, and was originally created for troubleshooting\&. .sp The Salt Master is contacted to retrieve state files and other resources during execution unless the \fB\-\-local\fP option is specified. .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 \fBsalt\-call\fP commands execute from the current user\(aqs shell context, while \fBsalt\fP commands execute from the system\(aqs default context. .UNINDENT .UNINDENT .SS Options .INDENT 0.0 .TP .B \-\-version Print the version of Salt that is running. .UNINDENT .INDENT 0.0 .TP .B \-\-versions\-report Show program\(aqs dependencies and version number, and then exit .UNINDENT .INDENT 0.0 .TP .B \-h, \-\-help Show the help message and exit .UNINDENT .INDENT 0.0 .TP .B \-c CONFIG_DIR, \-\-config\-dir=CONFIG_dir The location of the Salt configuration directory. This directory contains the configuration files for Salt master and minions. The default location on most systems is \fB/etc/salt\fP\&. .UNINDENT .INDENT 0.0 .TP .B \-\-hard\-crash Raise any original exception rather than exiting gracefully Default: False .UNINDENT .INDENT 0.0 .TP .B \-g, \-\-grains Return the information generated by the Salt grains .UNINDENT .INDENT 0.0 .TP .B \-m MODULE_DIRS, \-\-module\-dirs=MODULE_DIRS Specify an additional directory to pull modules from. Multiple directories can be provided by passing \-m /\-\-module\-dirs multiple times. .UNINDENT .INDENT 0.0 .TP .B \-d, \-\-doc, \-\-documentation Return the documentation for the specified module or for all modules if none are specified .UNINDENT .INDENT 0.0 .TP .B \-\-master=MASTER Specify the master to use. The minion must be authenticated with the master. If this option is omitted, the master options from the minion config will be used. If multi masters are set up the first listed master that responds will be used. .UNINDENT .INDENT 0.0 .TP .B \-\-return RETURNER Set salt\-call to pass the return data to one or many returner interfaces. To use many returner interfaces specify a comma delimited list of returners. .UNINDENT .INDENT 0.0 .TP .B \-\-local Run salt\-call locally, as if there was no master running. .UNINDENT .INDENT 0.0 .TP .B \-\-file\-root=FILE_ROOT Set this directory as the base file root. .UNINDENT .INDENT 0.0 .TP .B \-\-pillar\-root=PILLAR_ROOT Set this directory as the base pillar root. .UNINDENT .INDENT 0.0 .TP .B \-\-retcode\-passthrough Exit with the salt call retcode and not the salt binary retcode .UNINDENT .INDENT 0.0 .TP .B \-\-metadata Print out the execution metadata as well as the return. This will print out the outputter data, the return code, etc. .UNINDENT .INDENT 0.0 .TP .B \-\-id=ID Specify the minion id to use. If this option is omitted, the id option from the minion config will be used. .UNINDENT .INDENT 0.0 .TP .B \-\-skip\-grains Do not load grains. .UNINDENT .INDENT 0.0 .TP .B \-\-refresh\-grains\-cache Force a refresh of the grains cache .UNINDENT .SS Logging Options .sp Logging options which override any settings defined on the configuration files. .INDENT 0.0 .TP .B \-l LOG_LEVEL, \-\-log\-level=LOG_LEVEL Console logging log level. One of \fBall\fP, \fBgarbage\fP, \fBtrace\fP, \fBdebug\fP, \fBinfo\fP, \fBwarning\fP, \fBerror\fP, \fBquiet\fP\&. Default: \fBwarning\fP\&. .UNINDENT .INDENT 0.0 .TP .B \-\-log\-file=LOG_FILE Log file path. Default: /var/log/salt/minion\&. .UNINDENT .INDENT 0.0 .TP .B \-\-log\-file\-level=LOG_LEVEL_LOGFILE Logfile logging log level. One of \fBall\fP, \fBgarbage\fP, \fBtrace\fP, \fBdebug\fP, \fBinfo\fP, \fBwarning\fP, \fBerror\fP, \fBquiet\fP\&. Default: \fBwarning\fP\&. .UNINDENT .SS Output Options .INDENT 0.0 .TP .B \-\-out Pass in an alternative outputter to display the return of data. This outputter can be any of the available outputters: .INDENT 7.0 .INDENT 3.5 \fBgrains\fP, \fBhighstate\fP, \fBjson\fP, \fBkey\fP, \fBoverstatestage\fP, \fBpprint\fP, \fBraw\fP, \fBtxt\fP, \fByaml\fP .UNINDENT .UNINDENT .sp Some outputters are formatted only for data returned from specific functions; for instance, the \fBgrains\fP outputter will not work for non\-grains data. .sp If an outputter is used that does not support the data passed into it, then Salt will fall back on the \fBpprint\fP outputter and display the return data using the Python \fBpprint\fP standard library module. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 If using \fB\-\-out=json\fP, you will probably want \fB\-\-static\fP as well. Without the static option, you will get a separate JSON string per minion which makes JSON output invalid as a whole. This is due to using an iterative outputter. So if you want to feed it to a JSON parser, use \fB\-\-static\fP as well. .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B \-\-out\-indent OUTPUT_INDENT, \-\-output\-indent OUTPUT_INDENT Print the output indented by the provided value in spaces. Negative values disable indentation. Only applicable in outputters that support indentation. .UNINDENT .INDENT 0.0 .TP .B \-\-out\-file=OUTPUT_FILE, \-\-output\-file=OUTPUT_FILE Write the output to the specified file. .UNINDENT .INDENT 0.0 .TP .B \-\-no\-color Disable all colored output .UNINDENT .INDENT 0.0 .TP .B \-\-force\-color Force colored output .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 When using colored output the color codes are as follows: .sp \fBgreen\fP denotes success, \fBred\fP denotes failure, \fBblue\fP denotes changes and success and \fByellow\fP denotes a expected future change in configuration. .UNINDENT .UNINDENT .UNINDENT .SS See also .sp \fBsalt(1)\fP \fBsalt\-master(1)\fP \fBsalt\-minion(1)\fP .SS salt .SS \fBsalt\fP .SS Synopsis .INDENT 0.0 .INDENT 3.5 salt \(aq*\(aq [ options ] sys.doc .sp salt \-E \(aq.*\(aq [ options ] sys.doc cmd .sp salt \-G \(aqos:Arch.*\(aq [ options ] test.ping .sp salt \-C \fI\%\(aqG@os\fP:Arch.* and webserv* or \fI\%G@kernel\fP:FreeBSD\(aq [ options ] test.ping .UNINDENT .UNINDENT .SS Description .sp Salt allows for commands to be executed across a swath of remote systems in parallel. This means that remote systems can be both controlled and queried with ease. .SS Options .INDENT 0.0 .TP .B \-\-version Print the version of Salt that is running. .UNINDENT .INDENT 0.0 .TP .B \-\-versions\-report Show program\(aqs dependencies and version number, and then exit .UNINDENT .INDENT 0.0 .TP .B \-h, \-\-help Show the help message and exit .UNINDENT .INDENT 0.0 .TP .B \-c CONFIG_DIR, \-\-config\-dir=CONFIG_dir The location of the Salt configuration directory. This directory contains the configuration files for Salt master and minions. The default location on most systems is \fB/etc/salt\fP\&. .UNINDENT .INDENT 0.0 .TP .B \-t TIMEOUT, \-\-timeout=TIMEOUT The timeout in seconds to wait for replies from the Salt minions. The timeout number specifies how long the command line client will wait to query the minions and check on running jobs. Default: 5 .UNINDENT .INDENT 0.0 .TP .B \-s, \-\-static By default as of version 0.9.8 the salt command returns data to the console as it is received from minions, but previous releases would return data only after all data was received. Use the static option to only return the data with a hard timeout and after all minions have returned. Without the static option, you will get a separate JSON string per minion which makes JSON output invalid as a whole. .UNINDENT .INDENT 0.0 .TP .B \-\-async Instead of waiting for the job to run on minions only print the job id of the started execution and complete. .UNINDENT .INDENT 0.0 .TP .B \-\-state\-output=STATE_OUTPUT New in version 0.17. .sp Override the configured \fBstate_output\fP value for minion output. One of \fBfull\fP, \fBterse\fP, \fBmixed\fP, \fBchanges\fP or \fBfilter\fP\&. Default: \fBfull\fP\&. .UNINDENT .INDENT 0.0 .TP .B \-\-subset=SUBSET Execute the routine on a random subset of the targeted minions. The minions will be verified that they have the named function before executing. The SUBSET argument is the count of the minions to target. .UNINDENT .INDENT 0.0 .TP .B \-v VERBOSE, \-\-verbose Turn on verbosity for the salt call, this will cause the salt command to print out extra data like the job id. .UNINDENT .INDENT 0.0 .TP .B \-\-hide\-timeout Instead of showing the return data for all minions. This option prints only the online minions which could be reached. .UNINDENT .INDENT 0.0 .TP .B \-b BATCH, \-\-batch\-size=BATCH Instead of executing on all targeted minions at once, execute on a progressive set of minions. This option takes an argument in the form of an explicit number of minions to execute at once, or a percentage of minions to execute on. .UNINDENT .INDENT 0.0 .TP .B \-a EAUTH, \-\-auth=EAUTH Pass in an external authentication medium to validate against. The credentials will be prompted for. The options are \fIauto\fP, \fIkeystone\fP, \fIldap\fP, \fIpam\fP, and \fIstormpath\fP\&. Can be used with the \-T option. .UNINDENT .INDENT 0.0 .TP .B \-T, \-\-make\-token Used in conjunction with the \-a option. This creates a token that allows for the authenticated user to send commands without needing to re\-authenticate. .UNINDENT .INDENT 0.0 .TP .B \-\-return=RETURNER Choose an alternative returner to call on the minion, if an alternative returner is used then the return will not come back to the command line but will be sent to the specified return system. The options are \fIcarbon\fP, \fIcassandra\fP, \fIcouchbase\fP, \fIcouchdb\fP, \fIelasticsearch\fP, \fIetcd\fP, \fIhipchat\fP, \fIlocal\fP, \fIlocal_cache\fP, \fImemcache\fP, \fImongo\fP, \fImysql\fP, \fIodbc\fP, \fIpostgres\fP, \fIredis\fP, \fIsentry\fP, \fIslack\fP, \fIsms\fP, \fIsmtp\fP, \fIsqlite3\fP, \fIsyslog\fP, and \fIxmpp\fP\&. .UNINDENT .INDENT 0.0 .TP .B \-d, \-\-doc, \-\-documentation Return the documentation for the module functions available on the minions .UNINDENT .INDENT 0.0 .TP .B \-\-args\-separator=ARGS_SEPARATOR Set the special argument used as a delimiter between command arguments of compound commands. This is useful when one wants to pass commas as arguments to some of the commands in a compound command. .UNINDENT .SS Logging Options .sp Logging options which override any settings defined on the configuration files. .INDENT 0.0 .TP .B \-l LOG_LEVEL, \-\-log\-level=LOG_LEVEL Console logging log level. One of \fBall\fP, \fBgarbage\fP, \fBtrace\fP, \fBdebug\fP, \fBinfo\fP, \fBwarning\fP, \fBerror\fP, \fBquiet\fP\&. Default: \fBwarning\fP\&. .UNINDENT .INDENT 0.0 .TP .B \-\-log\-file=LOG_FILE Log file path. Default: /var/log/salt/master\&. .UNINDENT .INDENT 0.0 .TP .B \-\-log\-file\-level=LOG_LEVEL_LOGFILE Logfile logging log level. One of \fBall\fP, \fBgarbage\fP, \fBtrace\fP, \fBdebug\fP, \fBinfo\fP, \fBwarning\fP, \fBerror\fP, \fBquiet\fP\&. Default: \fBwarning\fP\&. .UNINDENT .SS Target Selection .sp The default matching that Salt utilizes is shell\-style globbing around the minion id. See \fI\%https://docs.python.org/2/library/fnmatch.html#module\-fnmatch\fP\&. .INDENT 0.0 .TP .B \-E, \-\-pcre The target expression will be interpreted as a PCRE regular expression rather than a shell glob. .UNINDENT .INDENT 0.0 .TP .B \-L, \-\-list The target expression will be interpreted as a comma\-delimited list; example: server1.foo.bar,server2.foo.bar,example7.quo.qux .UNINDENT .INDENT 0.0 .TP .B \-G, \-\-grain The target expression matches values returned by the Salt grains system on the minions. The target expression is in the format of \(aq:\(aq; example: \(aqos:Arch*\(aq .sp This was changed in version 0.9.8 to accept glob expressions instead of regular expression. To use regular expression matching with grains, use the \-\-grain\-pcre option. .UNINDENT .INDENT 0.0 .TP .B \-\-grain\-pcre The target expression matches values returned by the Salt grains system on the minions. The target expression is in the format of \(aq:< regular expression>\(aq; example: \(aqos:Arch.*\(aq .UNINDENT .INDENT 0.0 .TP .B \-N, \-\-nodegroup Use a predefined compound target defined in the Salt master configuration file. .UNINDENT .INDENT 0.0 .TP .B \-R, \-\-range Instead of using shell globs to evaluate the target, use a range expression to identify targets. Range expressions look like %cluster. .sp Using the Range option requires that a range server is set up and the location of the range server is referenced in the master configuration file. .UNINDENT .INDENT 0.0 .TP .B \-C, \-\-compound Utilize many target definitions to make the call very granular. This option takes a group of targets separated by \fBand\fP or \fBor\fP\&. The default matcher is a glob as usual. If something other than a glob is used, preface it with the letter denoting the type; example: \(aqwebserv* and \fI\%G@os\fP:Debian or \fI\%E@db*\fP\(aq Make sure that the compound target is encapsulated in quotes. .UNINDENT .INDENT 0.0 .TP .B \-I, \-\-pillar Instead of using shell globs to evaluate the target, use a pillar value to identify targets. The syntax for the target is the pillar key followed by a glob expression: "role:production*" .UNINDENT .INDENT 0.0 .TP .B \-S, \-\-ipcidr Match based on Subnet (CIDR notation) or IPv4 address. .UNINDENT .SS Output Options .INDENT 0.0 .TP .B \-\-out Pass in an alternative outputter to display the return of data. This outputter can be any of the available outputters: .INDENT 7.0 .INDENT 3.5 \fBgrains\fP, \fBhighstate\fP, \fBjson\fP, \fBkey\fP, \fBoverstatestage\fP, \fBpprint\fP, \fBraw\fP, \fBtxt\fP, \fByaml\fP .UNINDENT .UNINDENT .sp Some outputters are formatted only for data returned from specific functions; for instance, the \fBgrains\fP outputter will not work for non\-grains data. .sp If an outputter is used that does not support the data passed into it, then Salt will fall back on the \fBpprint\fP outputter and display the return data using the Python \fBpprint\fP standard library module. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 If using \fB\-\-out=json\fP, you will probably want \fB\-\-static\fP as well. Without the static option, you will get a separate JSON string per minion which makes JSON output invalid as a whole. This is due to using an iterative outputter. So if you want to feed it to a JSON parser, use \fB\-\-static\fP as well. .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B \-\-out\-indent OUTPUT_INDENT, \-\-output\-indent OUTPUT_INDENT Print the output indented by the provided value in spaces. Negative values disable indentation. Only applicable in outputters that support indentation. .UNINDENT .INDENT 0.0 .TP .B \-\-out\-file=OUTPUT_FILE, \-\-output\-file=OUTPUT_FILE Write the output to the specified file. .UNINDENT .INDENT 0.0 .TP .B \-\-no\-color Disable all colored output .UNINDENT .INDENT 0.0 .TP .B \-\-force\-color Force colored output .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 When using colored output the color codes are as follows: .sp \fBgreen\fP denotes success, \fBred\fP denotes failure, \fBblue\fP denotes changes and success and \fByellow\fP denotes a expected future change in configuration. .UNINDENT .UNINDENT .UNINDENT .SS See also .sp \fBsalt(7)\fP \fBsalt\-master(1)\fP \fBsalt\-minion(1)\fP .SS salt\-cloud .SS salt\-cp .SS \fBsalt\-cp\fP .sp Copy a file to a set of systems .SS Synopsis .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt\-cp \(aq*\(aq [ options ] SOURCE DEST salt\-cp \-E \(aq.*\(aq [ options ] SOURCE DEST salt\-cp \-G \(aqos:Arch.*\(aq [ options ] SOURCE DEST .ft P .fi .UNINDENT .UNINDENT .SS Description .sp Salt copy copies a local file out to all of the Salt minions matched by the given target. .sp Salt copy is only intended for use with small files (< 100KB). If you need to copy large files out to minions please use the cp.get_file function. .sp Note: salt\-cp uses salt\(aqs publishing mechanism. This means the privacy of the contents of the file on the wire is completely dependent upon the transport in use. In addition, if the salt\-master is running with debug logging it is possible that the contents of the file will be logged to disk. .SS Options .INDENT 0.0 .TP .B \-\-version Print the version of Salt that is running. .UNINDENT .INDENT 0.0 .TP .B \-\-versions\-report Show program\(aqs dependencies and version number, and then exit .UNINDENT .INDENT 0.0 .TP .B \-h, \-\-help Show the help message and exit .UNINDENT .INDENT 0.0 .TP .B \-c CONFIG_DIR, \-\-config\-dir=CONFIG_dir The location of the Salt configuration directory. This directory contains the configuration files for Salt master and minions. The default location on most systems is \fB/etc/salt\fP\&. .UNINDENT .INDENT 0.0 .TP .B \-t TIMEOUT, \-\-timeout=TIMEOUT The timeout in seconds to wait for replies from the Salt minions. The timeout number specifies how long the command line client will wait to query the minions and check on running jobs. Default: 5 .UNINDENT .SS Logging Options .sp Logging options which override any settings defined on the configuration files. .INDENT 0.0 .TP .B \-l LOG_LEVEL, \-\-log\-level=LOG_LEVEL Console logging log level. One of \fBall\fP, \fBgarbage\fP, \fBtrace\fP, \fBdebug\fP, \fBinfo\fP, \fBwarning\fP, \fBerror\fP, \fBquiet\fP\&. Default: \fBwarning\fP\&. .UNINDENT .INDENT 0.0 .TP .B \-\-log\-file=LOG_FILE Log file path. Default: /var/log/salt/master\&. .UNINDENT .INDENT 0.0 .TP .B \-\-log\-file\-level=LOG_LEVEL_LOGFILE Logfile logging log level. One of \fBall\fP, \fBgarbage\fP, \fBtrace\fP, \fBdebug\fP, \fBinfo\fP, \fBwarning\fP, \fBerror\fP, \fBquiet\fP\&. Default: \fBwarning\fP\&. .UNINDENT .SS Target Selection .sp The default matching that Salt utilizes is shell\-style globbing around the minion id. See \fI\%https://docs.python.org/2/library/fnmatch.html#module\-fnmatch\fP\&. .INDENT 0.0 .TP .B \-E, \-\-pcre The target expression will be interpreted as a PCRE regular expression rather than a shell glob. .UNINDENT .INDENT 0.0 .TP .B \-L, \-\-list The target expression will be interpreted as a comma\-delimited list; example: server1.foo.bar,server2.foo.bar,example7.quo.qux .UNINDENT .INDENT 0.0 .TP .B \-G, \-\-grain The target expression matches values returned by the Salt grains system on the minions. The target expression is in the format of \(aq:\(aq; example: \(aqos:Arch*\(aq .sp This was changed in version 0.9.8 to accept glob expressions instead of regular expression. To use regular expression matching with grains, use the \-\-grain\-pcre option. .UNINDENT .INDENT 0.0 .TP .B \-\-grain\-pcre The target expression matches values returned by the Salt grains system on the minions. The target expression is in the format of \(aq:< regular expression>\(aq; example: \(aqos:Arch.*\(aq .UNINDENT .INDENT 0.0 .TP .B \-N, \-\-nodegroup Use a predefined compound target defined in the Salt master configuration file. .UNINDENT .INDENT 0.0 .TP .B \-R, \-\-range Instead of using shell globs to evaluate the target, use a range expression to identify targets. Range expressions look like %cluster. .sp Using the Range option requires that a range server is set up and the location of the range server is referenced in the master configuration file. .UNINDENT .SS See also .sp \fBsalt(1)\fP \fBsalt\-master(1)\fP \fBsalt\-minion(1)\fP .SS salt\-extend .SS \fBsalt\-extend\fP .sp A utilty to generate extensions to the Salt source\-code. This is used for : .INDENT 0.0 .IP \(bu 2 Adding new execution modules, state modules .IP \(bu 2 Adding unit tests to existing modules .IP \(bu 2 Adding integration tests to existing modules .UNINDENT .SS Synopsis .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt\-extend \-\-help .ft P .fi .UNINDENT .UNINDENT .SS Description .sp \fBsalt\-extend\fP is a templating tool for extending SaltStack. If you\(aqre looking to add a module to SaltStack, then the \fBsalt\-extend\fP utility can guide you through the process. .sp You can use Salt Extend to quickly create templated modules for adding new behaviours to some of the module subsystems within Salt. .sp Salt Extend takes a template directory and merges it into a SaltStack source code directory. .sp \fISee also\fP: Salt Extend\&. .SS Options .INDENT 0.0 .TP .B \-\-extension, \-e The extension type you want to develop, e.g. module, module_unit, state .UNINDENT .INDENT 0.0 .TP .B \-\-salt\-directory, \-o The path to the salt installation, defaults to . .UNINDENT .INDENT 0.0 .TP .B \-\-name, \-n The module name for the new module .UNINDENT .INDENT 0.0 .TP .B \-\-description, \-d A description of the new extension .UNINDENT .INDENT 0.0 .TP .B \-\-no\-merge Don\(aqt merge the new module into the Salt source directory specified by \fI\-\-salt\-directory\fP, save to a temporary directory and print the directory path .UNINDENT .INDENT 0.0 .TP .B \-\-debug Print debug messages to stdout .UNINDENT .SS See also .sp \fBsalt\-api(1)\fP \fBsalt\-call(1)\fP \fBsalt\-cloud(1)\fP \fBsalt\-cp(1)\fP \fBsalt\-key(1)\fP \fBsalt\-main(1)\fP \fBsalt\-master(1)\fP \fBsalt\-minion(1)\fP \fBsalt\-run(1)\fP \fBsalt\-ssh(1)\fP \fBsalt\-syndic(1)\fP .SS salt\-key .SS \fBsalt\-key\fP .SS Synopsis .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt\-key [ options ] .ft P .fi .UNINDENT .UNINDENT .SS Description .sp Salt\-key executes simple management of Salt server public keys used for authentication. .sp On initial connection, a Salt minion sends its public key to the Salt master. This key must be accepted using the \fBsalt\-key\fP command on the Salt master. .sp Salt minion keys can be in one of the following states: .INDENT 0.0 .IP \(bu 2 \fBunaccepted\fP: key is waiting to be accepted. .IP \(bu 2 \fBaccepted\fP: key was accepted and the minion can communicate with the Salt master. .IP \(bu 2 \fBrejected\fP: key was rejected using the \fBsalt\-key\fP command. In this state the minion does not receive any communication from the Salt master. .IP \(bu 2 \fBdenied\fP: key was rejected automatically by the Salt master. This occurs when a minion has a duplicate ID, or when a minion was rebuilt or had new keys generated and the previous key was not deleted from the Salt master. In this state the minion does not receive any communication from the Salt master. .UNINDENT .sp To change the state of a minion key, use \fB\-d\fP to delete the key and then accept or reject the key. .SS Options .INDENT 0.0 .TP .B \-\-version Print the version of Salt that is running. .UNINDENT .INDENT 0.0 .TP .B \-\-versions\-report Show program\(aqs dependencies and version number, and then exit .UNINDENT .INDENT 0.0 .TP .B \-h, \-\-help Show the help message and exit .UNINDENT .INDENT 0.0 .TP .B \-c CONFIG_DIR, \-\-config\-dir=CONFIG_dir The location of the Salt configuration directory. This directory contains the configuration files for Salt master and minions. The default location on most systems is \fB/etc/salt\fP\&. .UNINDENT .INDENT 0.0 .TP .B \-u USER, \-\-user=USER Specify user to run salt\-key .UNINDENT .INDENT 0.0 .TP .B \-\-hard\-crash Raise any original exception rather than exiting gracefully. Default is False. .UNINDENT .INDENT 0.0 .TP .B \-q, \-\-quiet Suppress output .UNINDENT .INDENT 0.0 .TP .B \-y, \-\-yes Answer \(aqYes\(aq to all questions presented, defaults to False .UNINDENT .INDENT 0.0 .TP .B \-\-rotate\-aes\-key=ROTATE_AES_KEY Setting this to False prevents the master from refreshing the key session when keys are deleted or rejected, this lowers the security of the key deletion/rejection operation. Default is True. .UNINDENT .SS Logging Options .sp Logging options which override any settings defined on the configuration files. .INDENT 0.0 .TP .B \-\-log\-file=LOG_FILE Log file path. Default: /var/log/salt/minion\&. .UNINDENT .INDENT 0.0 .TP .B \-\-log\-file\-level=LOG_LEVEL_LOGFILE Logfile logging log level. One of \fBall\fP, \fBgarbage\fP, \fBtrace\fP, \fBdebug\fP, \fBinfo\fP, \fBwarning\fP, \fBerror\fP, \fBquiet\fP\&. Default: \fBwarning\fP\&. .UNINDENT .SS Output Options .INDENT 0.0 .TP .B \-\-out Pass in an alternative outputter to display the return of data. This outputter can be any of the available outputters: .INDENT 7.0 .INDENT 3.5 \fBgrains\fP, \fBhighstate\fP, \fBjson\fP, \fBkey\fP, \fBoverstatestage\fP, \fBpprint\fP, \fBraw\fP, \fBtxt\fP, \fByaml\fP .UNINDENT .UNINDENT .sp Some outputters are formatted only for data returned from specific functions; for instance, the \fBgrains\fP outputter will not work for non\-grains data. .sp If an outputter is used that does not support the data passed into it, then Salt will fall back on the \fBpprint\fP outputter and display the return data using the Python \fBpprint\fP standard library module. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 If using \fB\-\-out=json\fP, you will probably want \fB\-\-static\fP as well. Without the static option, you will get a separate JSON string per minion which makes JSON output invalid as a whole. This is due to using an iterative outputter. So if you want to feed it to a JSON parser, use \fB\-\-static\fP as well. .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B \-\-out\-indent OUTPUT_INDENT, \-\-output\-indent OUTPUT_INDENT Print the output indented by the provided value in spaces. Negative values disable indentation. Only applicable in outputters that support indentation. .UNINDENT .INDENT 0.0 .TP .B \-\-out\-file=OUTPUT_FILE, \-\-output\-file=OUTPUT_FILE Write the output to the specified file. .UNINDENT .INDENT 0.0 .TP .B \-\-no\-color Disable all colored output .UNINDENT .INDENT 0.0 .TP .B \-\-force\-color Force colored output .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 When using colored output the color codes are as follows: .sp \fBgreen\fP denotes success, \fBred\fP denotes failure, \fBblue\fP denotes changes and success and \fByellow\fP denotes a expected future change in configuration. .UNINDENT .UNINDENT .UNINDENT .SS Actions .INDENT 0.0 .TP .B \-l ARG, \-\-list=ARG List the public keys. The args \fBpre\fP, \fBun\fP, and \fBunaccepted\fP will list unaccepted/unsigned keys. \fBacc\fP or \fBaccepted\fP will list accepted/signed keys. \fBrej\fP or \fBrejected\fP will list rejected keys. Finally, \fBall\fP will list all keys. .UNINDENT .INDENT 0.0 .TP .B \-L, \-\-list\-all List all public keys. (Deprecated: use \fB\-\-list all\fP) .UNINDENT .INDENT 0.0 .TP .B \-a ACCEPT, \-\-accept=ACCEPT Accept the specified public key (use \-\-include\-all to match rejected keys in addition to pending keys). Globs are supported. .UNINDENT .INDENT 0.0 .TP .B \-A, \-\-accept\-all Accepts all pending keys. .UNINDENT .INDENT 0.0 .TP .B \-r REJECT, \-\-reject=REJECT Reject the specified public key (use \-\-include\-all to match accepted keys in addition to pending keys). Globs are supported. .UNINDENT .INDENT 0.0 .TP .B \-R, \-\-reject\-all Rejects all pending keys. .UNINDENT .INDENT 0.0 .TP .B \-\-include\-all Include non\-pending keys when accepting/rejecting. .UNINDENT .INDENT 0.0 .TP .B \-p PRINT, \-\-print=PRINT Print the specified public key. .UNINDENT .INDENT 0.0 .TP .B \-P, \-\-print\-all Print all public keys .UNINDENT .INDENT 0.0 .TP .B \-d DELETE, \-\-delete=DELETE Delete the specified key. Globs are supported. .UNINDENT .INDENT 0.0 .TP .B \-D, \-\-delete\-all Delete all keys. .UNINDENT .INDENT 0.0 .TP .B \-f FINGER, \-\-finger=FINGER Print the specified key\(aqs fingerprint. .UNINDENT .INDENT 0.0 .TP .B \-F, \-\-finger\-all Print all keys\(aq fingerprints. .UNINDENT .SS Key Generation Options .INDENT 0.0 .TP .B \-\-gen\-keys=GEN_KEYS Set a name to generate a keypair for use with salt .UNINDENT .INDENT 0.0 .TP .B \-\-gen\-keys\-dir=GEN_KEYS_DIR Set the directory to save the generated keypair. Only works with \(aqgen_keys_dir\(aq option; default is the current directory. .UNINDENT .INDENT 0.0 .TP .B \-\-keysize=KEYSIZE Set the keysize for the generated key, only works with the \(aq\-\-gen\-keys\(aq option, the key size must be 2048 or higher, otherwise it will be rounded up to 2048. The default is 2048. .UNINDENT .INDENT 0.0 .TP .B \-\-gen\-signature Create a signature file of the master\(aqs public\-key named master_pubkey_signature. The signature can be sent to a minion in the master\(aqs auth\-reply and enables the minion to verify the master\(aqs public\-key cryptographically. This requires a new signing\-key\-pair which can be auto\-created with the \-\-auto\-create parameter. .UNINDENT .INDENT 0.0 .TP .B \-\-priv=PRIV The private\-key file to create a signature with .UNINDENT .INDENT 0.0 .TP .B \-\-signature\-path=SIGNATURE_PATH The path where the signature file should be written .UNINDENT .INDENT 0.0 .TP .B \-\-pub=PUB The public\-key file to create a signature for .UNINDENT .INDENT 0.0 .TP .B \-\-auto\-create Auto\-create a signing key\-pair if it does not yet exist .UNINDENT .SS See also .sp \fBsalt(7)\fP \fBsalt\-master(1)\fP \fBsalt\-minion(1)\fP .SS salt\-master .SS \fBsalt\-master\fP .sp The Salt master daemon, used to control the Salt minions .SS Synopsis .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt\-master [ options ] .ft P .fi .UNINDENT .UNINDENT .SS Description .sp The master daemon controls the Salt minions .SS Options .INDENT 0.0 .TP .B \-\-version Print the version of Salt that is running. .UNINDENT .INDENT 0.0 .TP .B \-\-versions\-report Show program\(aqs dependencies and version number, and then exit .UNINDENT .INDENT 0.0 .TP .B \-h, \-\-help Show the help message and exit .UNINDENT .INDENT 0.0 .TP .B \-c CONFIG_DIR, \-\-config\-dir=CONFIG_dir The location of the Salt configuration directory. This directory contains the configuration files for Salt master and minions. The default location on most systems is \fB/etc/salt\fP\&. .UNINDENT .INDENT 0.0 .TP .B \-u USER, \-\-user=USER Specify user to run salt\-master .UNINDENT .INDENT 0.0 .TP .B \-d, \-\-daemon Run salt\-master as a daemon .UNINDENT .INDENT 0.0 .TP .B \-\-pid\-file PIDFILE Specify the location of the pidfile. Default: /var/run/salt\-master\&.pid .UNINDENT .SS Logging Options .sp Logging options which override any settings defined on the configuration files. .INDENT 0.0 .TP .B \-l LOG_LEVEL, \-\-log\-level=LOG_LEVEL Console logging log level. One of \fBall\fP, \fBgarbage\fP, \fBtrace\fP, \fBdebug\fP, \fBinfo\fP, \fBwarning\fP, \fBerror\fP, \fBquiet\fP\&. Default: \fBwarning\fP\&. .UNINDENT .INDENT 0.0 .TP .B \-\-log\-file=LOG_FILE Log file path. Default: /var/log/salt/master\&. .UNINDENT .INDENT 0.0 .TP .B \-\-log\-file\-level=LOG_LEVEL_LOGFILE Logfile logging log level. One of \fBall\fP, \fBgarbage\fP, \fBtrace\fP, \fBdebug\fP, \fBinfo\fP, \fBwarning\fP, \fBerror\fP, \fBquiet\fP\&. Default: \fBwarning\fP\&. .UNINDENT .SS See also .sp \fBsalt(1)\fP \fBsalt(7)\fP \fBsalt\-minion(1)\fP .SS salt\-minion .SS \fBsalt\-minion\fP .sp The Salt minion daemon, receives commands from a remote Salt master. .SS Synopsis .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt\-minion [ options ] .ft P .fi .UNINDENT .UNINDENT .SS Description .sp The Salt minion receives commands from the central Salt master and replies with the results of said commands. .SS Options .INDENT 0.0 .TP .B \-\-version Print the version of Salt that is running. .UNINDENT .INDENT 0.0 .TP .B \-\-versions\-report Show program\(aqs dependencies and version number, and then exit .UNINDENT .INDENT 0.0 .TP .B \-h, \-\-help Show the help message and exit .UNINDENT .INDENT 0.0 .TP .B \-c CONFIG_DIR, \-\-config\-dir=CONFIG_dir The location of the Salt configuration directory. This directory contains the configuration files for Salt master and minions. The default location on most systems is \fB/etc/salt\fP\&. .UNINDENT .INDENT 0.0 .TP .B \-u USER, \-\-user=USER Specify user to run salt\-minion .UNINDENT .INDENT 0.0 .TP .B \-d, \-\-daemon Run salt\-minion as a daemon .UNINDENT .INDENT 0.0 .TP .B \-\-pid\-file PIDFILE Specify the location of the pidfile. Default: /var/run/salt\-minion\&.pid .UNINDENT .SS Logging Options .sp Logging options which override any settings defined on the configuration files. .INDENT 0.0 .TP .B \-l LOG_LEVEL, \-\-log\-level=LOG_LEVEL Console logging log level. One of \fBall\fP, \fBgarbage\fP, \fBtrace\fP, \fBdebug\fP, \fBinfo\fP, \fBwarning\fP, \fBerror\fP, \fBquiet\fP\&. Default: \fBwarning\fP\&. .UNINDENT .INDENT 0.0 .TP .B \-\-log\-file=LOG_FILE Log file path. Default: /var/log/salt/minion\&. .UNINDENT .INDENT 0.0 .TP .B \-\-log\-file\-level=LOG_LEVEL_LOGFILE Logfile logging log level. One of \fBall\fP, \fBgarbage\fP, \fBtrace\fP, \fBdebug\fP, \fBinfo\fP, \fBwarning\fP, \fBerror\fP, \fBquiet\fP\&. Default: \fBwarning\fP\&. .UNINDENT .SS See also .sp \fBsalt(1)\fP \fBsalt(7)\fP \fBsalt\-master(1)\fP .SS salt\-proxy .SS \fBsalt\-proxy\fP .sp Receives commands from a Salt master and proxies these commands to devices that are unable to run a full minion. .SS Synopsis .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt\-proxy [ options ] .ft P .fi .UNINDENT .UNINDENT .SS Description .sp The Salt proxy minion receives commands from a Salt master, transmits appropriate commands to devices that are unable to run a minion, and replies with the results of said commands. .SS Options .INDENT 0.0 .TP .B \-\-proxyid The minion id that this proxy will assume. This is required. .UNINDENT .INDENT 0.0 .TP .B \-\-version Print the version of Salt that is running. .UNINDENT .INDENT 0.0 .TP .B \-\-versions\-report Show program\(aqs dependencies and version number, and then exit .UNINDENT .INDENT 0.0 .TP .B \-h, \-\-help Show the help message and exit .UNINDENT .INDENT 0.0 .TP .B \-c CONFIG_DIR, \-\-config\-dir=CONFIG_dir The location of the Salt configuration directory. This directory contains the configuration files for Salt master and minions. The default location on most systems is \fB/etc/salt\fP\&. .UNINDENT .INDENT 0.0 .TP .B \-u USER, \-\-user=USER Specify user to run salt\-proxy .UNINDENT .INDENT 0.0 .TP .B \-d, \-\-daemon Run salt\-proxy as a daemon .UNINDENT .INDENT 0.0 .TP .B \-\-pid\-file PIDFILE Specify the location of the pidfile. Default: \fB/var/run/salt\-proxy\-.pid\fP .UNINDENT .SS Logging Options .sp Logging options which override any settings defined on the configuration files. .INDENT 0.0 .TP .B \-l LOG_LEVEL, \-\-log\-level=LOG_LEVEL Console logging log level. One of \fBall\fP, \fBgarbage\fP, \fBtrace\fP, \fBdebug\fP, \fBinfo\fP, \fBwarning\fP, \fBerror\fP, \fBquiet\fP\&. Default: \fBwarning\fP\&. .UNINDENT .INDENT 0.0 .TP .B \-\-log\-file=LOG_FILE Log file path. Default: /var/log/salt/minion\&. .UNINDENT .INDENT 0.0 .TP .B \-\-log\-file\-level=LOG_LEVEL_LOGFILE Logfile logging log level. One of \fBall\fP, \fBgarbage\fP, \fBtrace\fP, \fBdebug\fP, \fBinfo\fP, \fBwarning\fP, \fBerror\fP, \fBquiet\fP\&. Default: \fBwarning\fP\&. .UNINDENT .SS See also .sp \fBsalt(1)\fP \fBsalt(7)\fP \fBsalt\-master(1)\fP \fBsalt\-minion(1)\fP .SS salt\-run .SS \fBsalt\-run\fP .sp Execute a Salt runner .SS Synopsis .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt\-run RUNNER .ft P .fi .UNINDENT .UNINDENT .SS Description .sp salt\-run is the frontend command for executing \fBSalt Runners\fP\&. Salt runners are simple modules used to execute convenience functions on the master .SS Options .INDENT 0.0 .TP .B \-\-version Print the version of Salt that is running. .UNINDENT .INDENT 0.0 .TP .B \-\-versions\-report Show program\(aqs dependencies and version number, and then exit .UNINDENT .INDENT 0.0 .TP .B \-h, \-\-help Show the help message and exit .UNINDENT .INDENT 0.0 .TP .B \-c CONFIG_DIR, \-\-config\-dir=CONFIG_dir The location of the Salt configuration directory. This directory contains the configuration files for Salt master and minions. The default location on most systems is \fB/etc/salt\fP\&. .UNINDENT .INDENT 0.0 .TP .B \-t TIMEOUT, \-\-timeout=TIMEOUT The timeout in seconds to wait for replies from the Salt minions. The timeout number specifies how long the command line client will wait to query the minions and check on running jobs. Default: 1 .UNINDENT .INDENT 0.0 .TP .B \-\-hard\-crash Raise any original exception rather than exiting gracefully. Default is False. .UNINDENT .INDENT 0.0 .TP .B \-d, \-\-doc, \-\-documentation Display documentation for runners, pass a module or a runner to see documentation on only that module/runner. .UNINDENT .SS Logging Options .sp Logging options which override any settings defined on the configuration files. .INDENT 0.0 .TP .B \-l LOG_LEVEL, \-\-log\-level=LOG_LEVEL Console logging log level. One of \fBall\fP, \fBgarbage\fP, \fBtrace\fP, \fBdebug\fP, \fBinfo\fP, \fBwarning\fP, \fBerror\fP, \fBquiet\fP\&. Default: \fBwarning\fP\&. .UNINDENT .INDENT 0.0 .TP .B \-\-log\-file=LOG_FILE Log file path. Default: /var/log/salt/master\&. .UNINDENT .INDENT 0.0 .TP .B \-\-log\-file\-level=LOG_LEVEL_LOGFILE Logfile logging log level. One of \fBall\fP, \fBgarbage\fP, \fBtrace\fP, \fBdebug\fP, \fBinfo\fP, \fBwarning\fP, \fBerror\fP, \fBquiet\fP\&. Default: \fBwarning\fP\&. .UNINDENT .SS See also .sp \fBsalt(1)\fP \fBsalt\-master(1)\fP \fBsalt\-minion(1)\fP .SS salt\-ssh .SS \fBsalt\-ssh\fP .SS Synopsis .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt\-ssh \(aq*\(aq [ options ] sys.doc salt\-ssh \-E \(aq.*\(aq [ options ] sys.doc cmd .ft P .fi .UNINDENT .UNINDENT .SS Description .sp Salt SSH allows for salt routines to be executed using only SSH for transport .SS Options .INDENT 0.0 .TP .B \-r, \-\-raw, \-\-raw\-shell Execute a raw shell command. .UNINDENT .INDENT 0.0 .TP .B \-\-priv Specify the SSH private key file to be used for authentication. .UNINDENT .INDENT 0.0 .TP .B \-\-roster Define which roster system to use, this defines if a database backend, scanner, or custom roster system is used. Default is the flat file roster. .UNINDENT .INDENT 0.0 .TP .B \-\-roster\-file Define an alternative location for the default roster file location. The default roster file is called \fBroster\fP and is found in the same directory as the master config file. .sp New in version 2014.1.0. .UNINDENT .INDENT 0.0 .TP .B \-\-refresh, \-\-refresh\-cache Force a refresh of the master side data cache of the target\(aqs data. This is needed if a target\(aqs grains have been changed and the auto refresh timeframe has not been reached. .UNINDENT .INDENT 0.0 .TP .B \-\-max\-procs Set the number of concurrent minions to communicate with. This value defines how many processes are opened up at a time to manage connections, the more running process the faster communication should be, default is 25. .UNINDENT .INDENT 0.0 .TP .B \-i, \-\-ignore\-host\-keys Disables StrictHostKeyChecking to relax acceptance of new and unknown host keys. .UNINDENT .INDENT 0.0 .TP .B \-\-no\-host\-keys Fully ignores ssh host keys which by default are honored and connections would ask for approval. Useful if the host key of a remote server has changed and would still error with \-\-ignore\-host\-keys. .UNINDENT .INDENT 0.0 .TP .B \-\-passwd Set the default password to attempt to use when authenticating. .UNINDENT .INDENT 0.0 .TP .B \-\-key\-deploy Set this flag to attempt to deploy the authorized ssh key with all minions. This combined with \-\-passwd can make initial deployment of keys very fast and easy. .UNINDENT .INDENT 0.0 .TP .B \-\-version Print the version of Salt that is running. .UNINDENT .INDENT 0.0 .TP .B \-\-versions\-report Show program\(aqs dependencies and version number, and then exit .UNINDENT .INDENT 0.0 .TP .B \-h, \-\-help Show the help message and exit .UNINDENT .INDENT 0.0 .TP .B \-c CONFIG_DIR, \-\-config\-dir=CONFIG_dir The location of the Salt configuration directory. This directory contains the configuration files for Salt master and minions. The default location on most systems is \fB/etc/salt\fP\&. .UNINDENT .SS Target Selection .sp The default matching that Salt utilizes is shell\-style globbing around the minion id. See \fI\%https://docs.python.org/2/library/fnmatch.html#module\-fnmatch\fP\&. .INDENT 0.0 .TP .B \-E, \-\-pcre The target expression will be interpreted as a PCRE regular expression rather than a shell glob. .UNINDENT .SS Logging Options .sp Logging options which override any settings defined on the configuration files. .INDENT 0.0 .TP .B \-l LOG_LEVEL, \-\-log\-level=LOG_LEVEL Console logging log level. One of \fBall\fP, \fBgarbage\fP, \fBtrace\fP, \fBdebug\fP, \fBinfo\fP, \fBwarning\fP, \fBerror\fP, \fBquiet\fP\&. Default: \fBwarning\fP\&. .UNINDENT .INDENT 0.0 .TP .B \-\-log\-file=LOG_FILE Log file path. Default: /var/log/salt/ssh\&. .UNINDENT .INDENT 0.0 .TP .B \-\-log\-file\-level=LOG_LEVEL_LOGFILE Logfile logging log level. One of \fBall\fP, \fBgarbage\fP, \fBtrace\fP, \fBdebug\fP, \fBinfo\fP, \fBwarning\fP, \fBerror\fP, \fBquiet\fP\&. Default: \fBwarning\fP\&. .UNINDENT .SS Output Options .INDENT 0.0 .TP .B \-\-out Pass in an alternative outputter to display the return of data. This outputter can be any of the available outputters: .INDENT 7.0 .INDENT 3.5 \fBgrains\fP, \fBhighstate\fP, \fBjson\fP, \fBkey\fP, \fBoverstatestage\fP, \fBpprint\fP, \fBraw\fP, \fBtxt\fP, \fByaml\fP .UNINDENT .UNINDENT .sp Some outputters are formatted only for data returned from specific functions; for instance, the \fBgrains\fP outputter will not work for non\-grains data. .sp If an outputter is used that does not support the data passed into it, then Salt will fall back on the \fBpprint\fP outputter and display the return data using the Python \fBpprint\fP standard library module. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 If using \fB\-\-out=json\fP, you will probably want \fB\-\-static\fP as well. Without the static option, you will get a separate JSON string per minion which makes JSON output invalid as a whole. This is due to using an iterative outputter. So if you want to feed it to a JSON parser, use \fB\-\-static\fP as well. .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B \-\-out\-indent OUTPUT_INDENT, \-\-output\-indent OUTPUT_INDENT Print the output indented by the provided value in spaces. Negative values disable indentation. Only applicable in outputters that support indentation. .UNINDENT .INDENT 0.0 .TP .B \-\-out\-file=OUTPUT_FILE, \-\-output\-file=OUTPUT_FILE Write the output to the specified file. .UNINDENT .INDENT 0.0 .TP .B \-\-no\-color Disable all colored output .UNINDENT .INDENT 0.0 .TP .B \-\-force\-color Force colored output .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 When using colored output the color codes are as follows: .sp \fBgreen\fP denotes success, \fBred\fP denotes failure, \fBblue\fP denotes changes and success and \fByellow\fP denotes a expected future change in configuration. .UNINDENT .UNINDENT .UNINDENT .SS See also .sp \fBsalt(7)\fP \fBsalt\-master(1)\fP \fBsalt\-minion(1)\fP .SS salt\-syndic .SS \fBsalt\-syndic\fP .sp The Salt syndic daemon, a special minion that passes through commands from a higher master .SS Synopsis .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt\-syndic [ options ] .ft P .fi .UNINDENT .UNINDENT .SS Description .sp The Salt syndic daemon, a special minion that passes through commands from a higher master. .SS Options .INDENT 0.0 .TP .B \-\-version Print the version of Salt that is running. .UNINDENT .INDENT 0.0 .TP .B \-\-versions\-report Show program\(aqs dependencies and version number, and then exit .UNINDENT .INDENT 0.0 .TP .B \-h, \-\-help Show the help message and exit .UNINDENT .INDENT 0.0 .TP .B \-c CONFIG_DIR, \-\-config\-dir=CONFIG_dir The location of the Salt configuration directory. This directory contains the configuration files for Salt master and minions. The default location on most systems is \fB/etc/salt\fP\&. .UNINDENT .INDENT 0.0 .TP .B \-u USER, \-\-user=USER Specify user to run salt\-syndic .UNINDENT .INDENT 0.0 .TP .B \-d, \-\-daemon Run salt\-syndic as a daemon .UNINDENT .INDENT 0.0 .TP .B \-\-pid\-file PIDFILE Specify the location of the pidfile. Default: /var/run/salt\-syndic\&.pid .UNINDENT .SS Logging Options .sp Logging options which override any settings defined on the configuration files. .INDENT 0.0 .TP .B \-l LOG_LEVEL, \-\-log\-level=LOG_LEVEL Console logging log level. One of \fBall\fP, \fBgarbage\fP, \fBtrace\fP, \fBdebug\fP, \fBinfo\fP, \fBwarning\fP, \fBerror\fP, \fBquiet\fP\&. Default: \fBwarning\fP\&. .UNINDENT .INDENT 0.0 .TP .B \-\-log\-file=LOG_FILE Log file path. Default: /var/log/salt/master\&. .UNINDENT .INDENT 0.0 .TP .B \-\-log\-file\-level=LOG_LEVEL_LOGFILE Logfile logging log level. One of \fBall\fP, \fBgarbage\fP, \fBtrace\fP, \fBdebug\fP, \fBinfo\fP, \fBwarning\fP, \fBerror\fP, \fBquiet\fP\&. Default: \fBwarning\fP\&. .UNINDENT .SS See also .sp \fBsalt(1)\fP \fBsalt\-master(1)\fP \fBsalt\-minion(1)\fP .SS salt\-api .SS \fBsalt\-api\fP .sp Start interfaces used to remotely connect to the salt master .SS Synopsis .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt\-api .ft P .fi .UNINDENT .UNINDENT .SS Description .sp The Salt API system manages network api connectors for the Salt Master .SS Options .INDENT 0.0 .TP .B \-\-version Print the version of Salt that is running. .UNINDENT .INDENT 0.0 .TP .B \-\-versions\-report Show program\(aqs dependencies and version number, and then exit .UNINDENT .INDENT 0.0 .TP .B \-h, \-\-help Show the help message and exit .UNINDENT .INDENT 0.0 .TP .B \-c CONFIG_DIR, \-\-config\-dir=CONFIG_dir The location of the Salt configuration directory. This directory contains the configuration files for Salt master and minions. The default location on most systems is \fB/etc/salt\fP\&. .UNINDENT .INDENT 0.0 .TP .B \-d, \-\-daemon Run the salt\-api as a daemon .UNINDENT .INDENT 0.0 .TP .B \-\-pid\-file=PIDFILE Specify the location of the pidfile. Default: /var/run/salt\-api.pid .UNINDENT .SS Logging Options .sp Logging options which override any settings defined on the configuration files. .INDENT 0.0 .TP .B \-l LOG_LEVEL, \-\-log\-level=LOG_LEVEL Console logging log level. One of \fBall\fP, \fBgarbage\fP, \fBtrace\fP, \fBdebug\fP, \fBinfo\fP, \fBwarning\fP, \fBerror\fP, \fBquiet\fP\&. Default: \fBwarning\fP\&. .UNINDENT .INDENT 0.0 .TP .B \-\-log\-file=LOG_FILE Log file path. Default: /var/log/salt/api\&. .UNINDENT .INDENT 0.0 .TP .B \-\-log\-file\-level=LOG_LEVEL_LOGFILE Logfile logging log level. One of \fBall\fP, \fBgarbage\fP, \fBtrace\fP, \fBdebug\fP, \fBinfo\fP, \fBwarning\fP, \fBerror\fP, \fBquiet\fP\&. Default: \fBwarning\fP\&. .UNINDENT .SS See also .sp \fBsalt\-api(7)\fP \fBsalt(7)\fP \fBsalt\-master(1)\fP .SS spm .SS \fBspm\fP .sp Salt Package Manager .SS Synopsis .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C spm [] .ft P .fi .UNINDENT .UNINDENT .SS Description .sp spm is the frontend command for managing Salt packages. Packages normally only include formulas, meaning a group of SLS files that install into the \fBfile_roots\fP on the Salt Master, but Salt modules can also be installed. .SS Options .INDENT 0.0 .TP .B \-y, \-\-assume\-yes Assume \fByes\fP instead of prompting the other whether or not to proceed with a particular command. Default is False. .UNINDENT .INDENT 0.0 .TP .B \-f, \-\-force When presented with a course of action that spm would normally refuse to perform, that action will be performed anyway. This is often destructive, and should be used with caution. .UNINDENT .SS Logging Options .sp Logging options which override any settings defined on the configuration files. .INDENT 0.0 .TP .B \-l LOG_LEVEL, \-\-log\-level=LOG_LEVEL Console logging log level. One of \fBall\fP, \fBgarbage\fP, \fBtrace\fP, \fBdebug\fP, \fBinfo\fP, \fBwarning\fP, \fBerror\fP, \fBquiet\fP\&. Default: \fBwarning\fP\&. .UNINDENT .INDENT 0.0 .TP .B \-\-log\-file=LOG_FILE Log file path. Default: /var/log/salt/spm\&. .UNINDENT .INDENT 0.0 .TP .B \-\-log\-file\-level=LOG_LEVEL_LOGFILE Logfile logging log level. One of \fBall\fP, \fBgarbage\fP, \fBtrace\fP, \fBdebug\fP, \fBinfo\fP, \fBwarning\fP, \fBerror\fP, \fBquiet\fP\&. Default: \fBwarning\fP\&. .UNINDENT .SS Commands .INDENT 0.0 .TP .B update_repo Connect to remote repositories locally configured on the system and download their metadata. .UNINDENT .INDENT 0.0 .TP .B install Install a package from a configured SPM repository. Requires a package name. .UNINDENT .INDENT 0.0 .TP .B remove Remove an installed package from the system. Requires a package name. .UNINDENT .INDENT 0.0 .TP .B info List information about an installed package. Requires a package name. .UNINDENT .INDENT 0.0 .TP .B files List files belonging to an installed package. Requires a package name. .UNINDENT .INDENT 0.0 .TP .B local Perform one of the above options (except for remove) on a package file, instead of on a package in a repository, or an installed package. Requires a valid path to a local file on the system. .UNINDENT .INDENT 0.0 .TP .B build Build a package from a directory containing a FORMULA file. Requires a valid path to a local directory on the system. .UNINDENT .INDENT 0.0 .TP .B create_repo Scan a directory for valid SPM package files and build an SPM\-METADATA file in that directory which describes them. .UNINDENT .SS See also .sp \fBsalt(1)\fP \fBsalt\-master(1)\fP \fBsalt\-minion(1)\fP .SH SALT MODULE REFERENCE .sp This section contains a list of the Python modules that are used to extend the various subsystems within Salt. .SS auth modules .TS center; |l|l|. _ T{ \fBauto\fP T} T{ An "Always Approved" eauth interface to test against, not intended for T} _ T{ \fBdjango\fP T} T{ Provide authentication using Django Web Framework T} _ T{ \fBkeystone\fP T} T{ Provide authentication using OpenStack Keystone T} _ T{ \fBldap\fP T} T{ Provide authentication using simple LDAP binds T} _ T{ \fBmysql\fP T} T{ Provide authentication using MySQL. T} _ T{ \fBpam\fP T} T{ Authenticate against PAM T} _ T{ \fBpki\fP T} T{ Authenticate via a PKI certificate. T} _ T{ \fBrest\fP T} T{ Provide authentication using a REST call T} _ T{ \fBsharedsecret\fP T} T{ Provide authentication using configured shared secret T} _ T{ \fBstormpath\fP T} T{ Provide authentication using Stormpath. T} _ T{ \fByubico\fP T} T{ Provide authentication using YubiKey. T} _ .TE .SS salt.auth.auto .sp An "Always Approved" eauth interface to test against, not intended for production use .INDENT 0.0 .TP .B salt.auth.auto.auth(username, password) Authenticate! .UNINDENT .SS salt.auth.django .sp Provide authentication using Django Web Framework .INDENT 0.0 .TP .B depends .INDENT 7.0 .IP \(bu 2 Django Web Framework .UNINDENT .UNINDENT .sp Django authentication depends on the presence of the django framework in the \fBPYTHONPATH\fP, the Django project\(aqs \fBsettings.py\fP file being in the \fBPYTHONPATH\fP and accessible via the \fBDJANGO_SETTINGS_MODULE\fP environment variable. .sp Django auth can be defined like any other eauth module: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C external_auth: django: fred: \- .* \- \(aq@runner\(aq .ft P .fi .UNINDENT .UNINDENT .sp This will authenticate Fred via Django and allow him to run any execution module and all runners. .sp The authorization details can optionally be located inside the Django database. The relevant entry in the \fBmodels.py\fP file would look like this: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C class SaltExternalAuthModel(models.Model): user_fk = models.ForeignKey(auth.User) minion_matcher = models.CharField() minion_fn = models.CharField() .ft P .fi .UNINDENT .UNINDENT .sp The \fBexternal_auth\fP clause in the master config would then look like this: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C external_auth: django: ^model: .ft P .fi .UNINDENT .UNINDENT .sp When a user attempts to authenticate via Django, Salt will import the package indicated via the keyword \fB^model\fP\&. That model must have the fields indicated above, though the model DOES NOT have to be named \(aqSaltExternalAuthModel\(aq. .INDENT 0.0 .TP .B salt.auth.django.auth(username, password) Simple Django auth .UNINDENT .INDENT 0.0 .TP .B salt.auth.django.django_auth_setup() Prepare the connection to the Django authentication framework .UNINDENT .INDENT 0.0 .TP .B salt.auth.django.retrieve_auth_entries(u=None) .INDENT 7.0 .TP .B Parameters \fBu\fP \-\- Username to filter for .TP .B Returns Dictionary that can be slotted into the \fB__opts__\fP structure for eauth that designates the user associated ACL .UNINDENT .sp Database records such as: .TS center; |l|l|l|. _ T{ username T} T{ minion_or_fn_matcher T} T{ minion_fn T} _ T{ fred T} T{ T} T{ test.ping T} _ T{ fred T} T{ server1 T} T{ network.interfaces T} _ T{ fred T} T{ server1 T} T{ raid.list T} _ T{ fred T} T{ server2 T} T{ \&.* T} _ T{ guru T} T{ \&.* T} T{ T} _ T{ smartadmin T} T{ server1 T} T{ \&.* T} _ .TE .sp Should result in an eauth config such as: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C fred: \- test.ping \- server1: \- network.interfaces \- raid.list \- server2: \- .* guru: \- .* smartadmin: \- server1: \- .* .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.auth.keystone .sp Provide authentication using OpenStack Keystone .INDENT 0.0 .TP .B depends .INDENT 7.0 .IP \(bu 2 keystoneclient Python module .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.auth.keystone.auth(username, password) Try and authenticate .UNINDENT .INDENT 0.0 .TP .B salt.auth.keystone.get_auth_url() Try and get the URL from the config, else return localhost .UNINDENT .SS salt.auth.ldap .sp Provide authentication using simple LDAP binds .INDENT 0.0 .TP .B depends .INDENT 7.0 .IP \(bu 2 ldap Python module .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.auth.ldap.auth(username, password) Simple LDAP auth .UNINDENT .INDENT 0.0 .TP .B salt.auth.ldap.expand_ldap_entries(entries, opts=None) .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBentries\fP \-\- ldap subtree in external_auth config option .IP \(bu 2 \fBopts\fP \-\- Opts to use when __opts__ not defined .UNINDENT .TP .B Returns Dictionary with all allowed operations .UNINDENT .sp Takes the ldap subtree in the external_auth config option and expands it with actual minion names .INDENT 7.0 .TP .B webadmins%: .INDENT 7.0 .IP \(bu 2 .INDENT 2.0 .TP .B server1 .INDENT 7.0 .IP \(bu 2 \&.* .UNINDENT .UNINDENT .IP \(bu 2 ldap(OU=webservers,dc=int,dc=bigcompany,dc=com) \- test.ping \- service.restart .IP \(bu 2 ldap(OU=Domain Controllers,dc=int,dc=bigcompany,dc=com) \- allowed_fn_list_attribute^ .UNINDENT .UNINDENT .sp This function only gets called if auth.ldap.activedirectory = True .UNINDENT .INDENT 0.0 .TP .B salt.auth.ldap.groups(username, **kwargs) Authenticate against an LDAP group .sp Behavior is highly dependent on if Active Directory is in use. .sp AD handles group membership very differently than OpenLDAP. See the External Authentication documentation for a thorough discussion of available parameters for customizing the search. .sp OpenLDAP allows you to search for all groups in the directory and returns members of those groups. Then we check against the username entered. .UNINDENT .SS salt.auth.mysql .sp Provide authentication using MySQL. .sp When using MySQL as an authentication backend, you will need to create or use an existing table that has a username and a password column. .sp To get started, create a simple table that holds just a username and a password. The password field will hold a SHA256 checksum. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C CREATE TABLE \(gausers\(ga ( \(gaid\(ga int(11) NOT NULL AUTO_INCREMENT, \(gausername\(ga varchar(25) DEFAULT NULL, \(gapassword\(ga varchar(70) DEFAULT NULL, PRIMARY KEY (\(gaid\(ga) ) ENGINE=InnoDB AUTO_INCREMENT=2 DEFAULT CHARSET=latin1; .ft P .fi .UNINDENT .UNINDENT .sp To create a user within MySQL, execute the following statement. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C INSERT INTO users VALUES (NULL, \(aqdiana\(aq, SHA2(\(aqsecret\(aq, 256)) .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C mysql_auth: hostname: localhost database: SaltStack username: root password: letmein auth_sql: \(aqSELECT username FROM users WHERE username = "{0}" AND password = SHA2("{1}", 256)\(aq .ft P .fi .UNINDENT .UNINDENT .sp The \fIauth_sql\fP contains the SQL that will validate a user to ensure they are correctly authenticated. This is where you can specify other SQL queries to authenticate users. .sp Enable MySQL authentication. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C external_auth: mysql: damian: \- test.* .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .TP .B depends .INDENT 7.0 .IP \(bu 2 MySQL\-python Python module .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.auth.mysql.auth(username, password) Authenticate using a MySQL user table .UNINDENT .SS salt.auth.pam .sp Authenticate against PAM .sp Provides an authenticate function that will allow the caller to authenticate a user against the Pluggable Authentication Modules (PAM) on the system. .sp Implemented using ctypes, so no compilation is necessary. .sp There is one extra configuration option for pam. The \fIpam_service\fP that is authenticated against. This defaults to \fIlogin\fP .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C auth.pam.service: login .ft P .fi .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 PAM authentication will not work for the \fBroot\fP user. .sp The Python interface to PAM does not support authenticating as \fBroot\fP\&. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B class salt.auth.pam.PamConv Wrapper class for pam_conv structure .UNINDENT .INDENT 0.0 .TP .B class salt.auth.pam.PamHandle Wrapper class for pam_handle_t .UNINDENT .INDENT 0.0 .TP .B class salt.auth.pam.PamMessage Wrapper class for pam_message structure .UNINDENT .INDENT 0.0 .TP .B class salt.auth.pam.PamResponse Wrapper class for pam_response structure .UNINDENT .INDENT 0.0 .TP .B salt.auth.pam.auth(username, password, **kwargs) Authenticate via pam .UNINDENT .INDENT 0.0 .TP .B salt.auth.pam.authenticate(username, password) Returns True if the given username and password authenticate for the given service. Returns False otherwise .sp \fBusername\fP: the username to authenticate .sp \fBpassword\fP: the password in plain text .UNINDENT .INDENT 0.0 .TP .B salt.auth.pam.groups(username, *args, **kwargs) Retrieve groups for a given user for this auth provider .sp Uses system groups .UNINDENT .SS salt.auth.pki .sp Authenticate via a PKI certificate. .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 This module is Experimental and should be used with caution .UNINDENT .UNINDENT .sp Provides an authenticate function that will allow the caller to authenticate a user via their public cert against a pre\-defined Certificate Authority. .sp TODO: Add a \(aqca_dir\(aq option to configure a directory of CA files, a la Apache. .INDENT 0.0 .TP .B depends .INDENT 7.0 .IP \(bu 2 pyOpenSSL module .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.auth.pki.auth(username, password, **kwargs) Returns True if the given user cert (password is the cert contents) was issued by the CA and if cert\(aqs Common Name is equal to username. .sp Returns False otherwise. .INDENT 7.0 .TP .B \fBusername\fP: we need it to run the auth function from CLI/API; it should be in master config auth/acl .TP .B \fBpassword\fP: contents of user certificate (pem\-encoded user public key); why "password"? For CLI, it\(aqs the only available name .UNINDENT .sp Configure the CA cert in the master config file: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C external_auth: pki: ca_file: /etc/pki/tls/ca_certs/trusted\-ca.crt your_user: \- .* .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.auth.rest module .sp Provide authentication using a REST call .sp REST auth can be defined like any other eauth module: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C external_auth: rest: ^url: https://url/for/rest/call fred: \- .* \- \(aq@runner\(aq .ft P .fi .UNINDENT .UNINDENT .sp If there are entries underneath the ^url entry then they are merged with any responses from the REST call. In the above example, assuming the REST call does not return any additional ACLs, this will authenticate Fred via a REST call and allow him to run any execution module and all runners. .sp The REST call should return a JSON object that maps to a regular eauth YAML structure as above. .INDENT 0.0 .TP .B salt.auth.rest.auth(username, password) REST authentication .UNINDENT .SS salt.auth.sharedsecret .sp Provide authentication using configured shared secret .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C external_auth: sharedsecret: fred: \- .* \- \(aq@jobs\(aq .ft P .fi .UNINDENT .UNINDENT .sp The shared secret should be added to the master configuration, for example in /etc/salt/master.d/sharedsecret.conf (make sure that file is only readable by the user running the master): .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C sharedsecret: OIUHF_CHANGE_THIS_12h88 .ft P .fi .UNINDENT .UNINDENT .sp This auth module should be used with caution. It was initially designed to work with a frontal that takes care of authentication (for example kerberos) and places the shared secret in the HTTP headers to the salt\-api call. This salt\-api call should really be done on localhost to avoid someone eavesdropping on the shared secret. .sp See the documentation for cherrypy to setup the headers in your frontal. .sp New in version Beryllium. .INDENT 0.0 .TP .B salt.auth.sharedsecret.auth(username, sharedsecret, **kwargs) Shared secret authentication .UNINDENT .SS salt.auth.stormpath .sp Provide authentication using Stormpath. .sp This driver requires some extra configuration beyond that which Stormpath normally requires. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C stormpath: apiid: 1234567890 apikey: 1234567890/ABCDEF # Can use an application ID application: 6789012345 # Or can use a directory ID directory: 3456789012 # But not both .ft P .fi .UNINDENT .UNINDENT .sp New in version 2015.8.0. .INDENT 0.0 .TP .B salt.auth.stormpath.auth(username, password) Authenticate using a Stormpath directory or application .UNINDENT .SS salt.auth.yubico .sp Provide authentication using YubiKey. .sp New in version 2015.5.0. .INDENT 0.0 .TP .B depends yubico\-client Python module .UNINDENT .sp To get your YubiKey API key you will need to visit the website below. .sp \fI\%https://upgrade.yubico.com/getapikey/\fP .sp The resulting page will show the generated Client ID (aka AuthID or API ID) and the generated API key (Secret Key). Make a note of both and use these two values in your /etc/salt/master configuration. .INDENT 0.0 .INDENT 3.5 /etc/salt/master .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C yubico_users: damian: id: 12345 key: ABCDEFGHIJKLMNOPQRSTUVWXYZ .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C external_auth: yubico: damian: \- test.* .ft P .fi .UNINDENT .UNINDENT .UNINDENT .UNINDENT .sp Please wait five to ten minutes after generating the key before testing so that the API key will be updated on all the YubiCloud servers. .INDENT 0.0 .TP .B salt.auth.yubico.auth(username, password) Authenticate against yubico server .UNINDENT .SS beacon modules .TS center; |l|l|. _ T{ \fBadb\fP T} T{ Beacon to emit adb device state changes for Android devices T} _ T{ \fBavahi_announce\fP T} T{ Beacon to announce via avahi (zeroconf) T} _ T{ \fBbonjour_announce\fP T} T{ Beacon to announce via Bonjour (zeroconf) T} _ T{ \fBbtmp\fP T} T{ Beacon to fire events at failed login of users T} _ T{ \fBdiskusage\fP T} T{ Beacon to monitor disk usage. T} _ T{ \fBglxinfo\fP T} T{ Beacon to emit when a display is available to a linux machine T} _ T{ \fBhaproxy\fP T} T{ Watch current connections of haproxy server backends. T} _ T{ \fBinotify\fP T} T{ Watch files and translate the changes into salt events T} _ T{ \fBjournald\fP T} T{ A simple beacon to watch journald for specific entries T} _ T{ \fBload\fP T} T{ Beacon to emit system load averages T} _ T{ \fBmemusage\fP T} T{ Beacon to monitor memory usage. T} _ T{ \fBnetwork_info\fP T} T{ Beacon to monitor statistics from ethernet adapters T} _ T{ \fBnetwork_settings\fP T} T{ Beacon to monitor network adapter setting changes on Linux T} _ T{ \fBpkg\fP T} T{ Watch for pkgs that have upgrades, then fire an event. T} _ T{ \fBproxy_example\fP T} T{ Example beacon to use with salt\-proxy T} _ T{ \fBps\fP T} T{ Send events covering service status T} _ T{ \fBsalt_proxy\fP T} T{ Beacon to manage and report the status of T} _ T{ \fBservice\fP T} T{ Send events covering service status T} _ T{ \fBsh\fP T} T{ Watch the shell commands being executed actively. T} _ T{ \fBstatus\fP T} T{ The status beacon is intended to send a basic health check event up to the master, this allows for event driven routines based on presence to be set up. T} _ T{ \fBtwilio_txt_msg\fP T} T{ Beacon to emit Twilio text messages T} _ T{ \fBwtmp\fP T} T{ Beacon to fire events at login of users as registered in the wtmp file T} _ .TE .SS salt.beacons.adb module .sp Beacon to emit adb device state changes for Android devices .sp New in version 2016.3.0. .INDENT 0.0 .TP .B salt.beacons.adb.beacon(config) Emit the status of all devices returned by adb .sp Specify the device states that should emit an event, there will be an event for each device with the event type and device specified. .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C beacons: adb: \- states: \- offline \- unauthorized \- missing \- no_devices_event: True \- battery_low: 25 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.beacons.avahi_announce module .sp Beacon to announce via avahi (zeroconf) .sp New in version 2016.11.0. .SS Dependencies .INDENT 0.0 .IP \(bu 2 python\-avahi .IP \(bu 2 dbus\-python .UNINDENT .INDENT 0.0 .TP .B salt.beacons.avahi_announce.beacon(config) Broadcast values via zeroconf .sp If the announced values are static, it is adviced to set run_once: True (do not poll) on the beacon configuration. .INDENT 7.0 .TP .B The following are required configuration settings: \(aqservicetype\(aq: The service type to announce. \(aqport\(aq: The port of the service to announce. \(aqtxt\(aq: The TXT record of the service being announced as a dict. .INDENT 7.0 .INDENT 3.5 .INDENT 0.0 .TP .B Grains can be used to define TXT values using the syntax: grains. .TP .B or: grains.[i] .UNINDENT .sp where i is an integer representing the index of the grain to use. If the grain is not a list, the index is ignored. .UNINDENT .UNINDENT .TP .B The following are optional configuration settings: .INDENT 7.0 .TP .B \(aqservicename\(aq: Set the name of the service. Will use the hostname from __grains__[\(aqhost\(aq] if not set. .TP .B \(aqreset_on_change\(aq: If true and there is a change in TXT records detected, it will stop announcing the service and then restart announcing the service. This interruption in service announcement may be desirable if the client relies on changes in the browse records to update its cache of the TXT records. Defaults to False. .TP .B \(aqreset_wait\(aq: The number of seconds to wait after announcement stops announcing and before it restarts announcing in the case where there is a change in TXT records detected and \(aqreset_on_change\(aq is True. Defaults to 0. .TP .B \(aqcopy_grains\(aq: If set to True, it will copy the grains passed into the beacon when it backs them up to check for changes on the next iteration. Normally, instead of copy, it would use straight value assignment. This will allow detection of changes to grains where the grains are modified in\-place instead of completely replaced. In\-place grains changes are not currently done in the main Salt code but may be done due to a custom plug\-in. Defaults to False. .UNINDENT .UNINDENT .sp Example Config .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C beacons: avahi_announce: run_once: True servicetype: _demo._tcp port: 1234 txt: ProdName: grains.productname SerialNo: grains.serialnumber Comments: \(aqthis is a test\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.beacons.bonjour_announce module .sp Beacon to announce via Bonjour (zeroconf) .INDENT 0.0 .TP .B salt.beacons.bonjour_announce.beacon(config) Broadcast values via zeroconf .sp If the announced values are static, it is adviced to set run_once: True (do not poll) on the beacon configuration. .INDENT 7.0 .TP .B The following are required configuration settings: \(aqservicetype\(aq: The service type to announce. \(aqport\(aq: The port of the service to announce. \(aqtxt\(aq: The TXT record of the service being announced as a dict. .INDENT 7.0 .INDENT 3.5 .INDENT 0.0 .TP .B Grains can be used to define TXT values using the syntax: grains. .TP .B or: grains.[i] .UNINDENT .sp where i is an integer representing the index of the grain to use. If the grain is not a list, the index is ignored. .UNINDENT .UNINDENT .TP .B The following are optional configuration settings: .INDENT 7.0 .TP .B \(aqservicename\(aq: Set the name of the service. Will use the hostname from __grains__[\(aqhost\(aq] if not set. .TP .B \(aqreset_on_change\(aq: If true and there is a change in TXT records detected, it will stop announcing the service and then restart announcing the service. This interruption in service announcement may be desirable if the client relies on changes in the browse records to update its cache of the TXT records. Defaults to False. .TP .B \(aqreset_wait\(aq: The number of seconds to wait after announcement stops announcing and before it restarts announcing in the case where there is a change in TXT records detected and \(aqreset_on_change\(aq is True. Defaults to 0. .TP .B \(aqcopy_grains\(aq: If set to True, it will copy the grains passed into the beacon when it backs them up to check for changes on the next iteration. Normally, instead of copy, it would use straight value assignment. This will allow detection of changes to grains where the grains are modified in\-place instead of completely replaced. In\-place grains changes are not currently done in the main Salt code but may be done due to a custom plug\-in. Defaults to False. .UNINDENT .UNINDENT .sp Example Config .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C beacons: bonjour_announce: run_once: True servicetype: _demo._tcp port: 1234 txt: ProdName: grains.productname SerialNo: grains.serialnumber Comments: \(aqthis is a test\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.beacons.btmp .sp Beacon to fire events at failed login of users .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C beacons: btmp: {} .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.beacons.btmp.beacon(config) Read the last btmp file and return information on the failed logins .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C beacons: btmp: {} .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.beacons.diskusage .sp Beacon to monitor disk usage. .sp New in version 2015.5.0. .INDENT 0.0 .TP .B depends python\-psutil .UNINDENT .INDENT 0.0 .TP .B salt.beacons.diskusage.beacon(config) Monitor the disk usage of the minion .sp Specify thresholds for each disk and only emit a beacon if any of them are exceeded. .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C beacons: diskusage: \- /: 63% \- /mnt/nfs: 50% .ft P .fi .UNINDENT .UNINDENT .sp Windows drives must be quoted to avoid yaml syntax errors .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C beacons: diskusage: \- interval: 120 \- \(aqc:\(aq: 90% \- \(aqd:\(aq: 50% .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.beacons.glxinfo module .sp Beacon to emit when a display is available to a linux machine .sp New in version 2016.3.0. .INDENT 0.0 .TP .B salt.beacons.glxinfo.beacon(config) Emit the status of a connected display to the minion .sp Mainly this is used to detect when the display fails to connect for whatever reason. .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C beacons: glxinfo: user: frank screen_event: True .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.beacons.haproxy module .sp Watch current connections of haproxy server backends. Fire an event when over a specified threshold. .sp New in version 2016.11.0. .INDENT 0.0 .TP .B salt.beacons.haproxy.beacon(config) Check if current number of sessions of a server for a specific haproxy backend is over a defined threshold. .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C beacons: haproxy: \- www\-backend: threshold: 45 servers: \- web1 \- web2 \- interval: 120 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.beacons.inotify .sp Watch files and translate the changes into salt events .INDENT 0.0 .TP .B depends .INDENT 7.0 .IP \(bu 2 pyinotify Python module >= 0.9.5 .UNINDENT .TP .B Caution Using generic mask options like open, access, ignored, and closed_nowrite with reactors can easily cause the reactor to loop on itself. To mitigate this behavior, consider setting the \fIdisable_during_state_run\fP flag to \fITrue\fP in the beacon configuration. .TP .B note The \fIinotify\fP beacon only works on OSes that have \fIinotify\fP kernel support. Currently this excludes FreeBSD, macOS, and Windows. .UNINDENT .INDENT 0.0 .TP .B salt.beacons.inotify.beacon(config) Watch the configured files .sp Example Config .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C beacons: inotify: /path/to/file/or/dir: mask: \- open \- create \- close_write recurse: True auto_add: True exclude: \- /path/to/file/or/dir/exclude1 \- /path/to/file/or/dir/exclude2 \- /path/to/file/or/dir/regex[a\-m]*$: regex: True .ft P .fi .UNINDENT .UNINDENT .sp The mask list can contain the following events (the default mask is create, delete, and modify): .INDENT 7.0 .IP \(bu 2 access \- File accessed .IP \(bu 2 attrib \- File metadata changed .IP \(bu 2 close_nowrite \- Unwritable file closed .IP \(bu 2 close_write \- Writable file closed .IP \(bu 2 create \- File created in watched directory .IP \(bu 2 delete \- File deleted from watched directory .IP \(bu 2 delete_self \- Watched file or directory deleted .IP \(bu 2 modify \- File modified .IP \(bu 2 moved_from \- File moved out of watched directory .IP \(bu 2 moved_to \- File moved into watched directory .IP \(bu 2 move_self \- Watched file moved .IP \(bu 2 open \- File opened .UNINDENT .sp The mask can also contain the following options: .INDENT 7.0 .IP \(bu 2 dont_follow \- Don\(aqt dereference symbolic links .IP \(bu 2 excl_unlink \- Omit events for children after they have been unlinked .IP \(bu 2 oneshot \- Remove watch after one event .IP \(bu 2 onlydir \- Operate only if name is directory .UNINDENT .INDENT 7.0 .TP .B recurse: Recursively watch files in the directory .TP .B auto_add: Automatically start watching files that are created in the watched directory .TP .B exclude: Exclude directories or files from triggering events in the watched directory. Can use regex if regex is set to True .UNINDENT .UNINDENT .SS salt.beacons.journald .sp A simple beacon to watch journald for specific entries .INDENT 0.0 .TP .B salt.beacons.journald.beacon(config) The journald beacon allows for the systemd journal to be parsed and linked objects to be turned into events. .sp This beacons config will return all sshd jornal entries .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C beacons: journald: sshd: SYSLOG_IDENTIFIER: sshd PRIORITY: 6 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.beacons.load .sp Beacon to emit system load averages .INDENT 0.0 .TP .B salt.beacons.load.beacon(config) Emit the load averages of this host. .sp Specify thresholds for each load average and only emit a beacon if any of them are exceeded. .sp \fIonchangeonly\fP: when \fIonchangeonly\fP is True the beacon will fire events only when the load average pass one threshold. Otherwise, it will fire an event at each beacon interval. The default is False. .INDENT 7.0 .TP .B \fIemitatstartup\fP: when \fIemitatstartup\fP is False the beacon will not fire event when the minion is reload. Applicable only when \fIonchangeonly\fP is True. The default is True. .UNINDENT .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C beacons: load: 1m: \- 0.0 \- 2.0 5m: \- 0.0 \- 1.5 15m: \- 0.1 \- 1.0 emitatstartup: True onchangeonly: False .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.beacons.memusage module .sp Beacon to monitor memory usage. .sp New in version 2016.3.0. .INDENT 0.0 .TP .B depends python\-psutil .UNINDENT .INDENT 0.0 .TP .B salt.beacons.memusage.beacon(config) Monitor the memory usage of the minion .sp Specify thresholds for percent used and only emit a beacon if it is exceeded. .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C beacons: memusage: \- percent: 63% .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.beacons.network_info .sp Beacon to monitor statistics from ethernet adapters .sp New in version 2015.5.0. .INDENT 0.0 .TP .B salt.beacons.network_info.beacon(config) Emit the network statistics of this host. .sp Specify thresholds for each network stat and only emit a beacon if any of them are exceeded. .sp Emit beacon when any values are equal to configured values. .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C beacons: network_info: eth0: \- type: equal \- bytes_sent: 100000 \- bytes_recv: 100000 \- packets_sent: 100000 \- packets_recv: 100000 \- errin: 100 \- errout: 100 \- dropin: 100 \- dropout: 100 .ft P .fi .UNINDENT .UNINDENT .sp Emit beacon when any values are greater than configured values. .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C beacons: network_info: eth0: \- type: greater \- bytes_sent: 100000 \- bytes_recv: 100000 \- packets_sent: 100000 \- packets_recv: 100000 \- errin: 100 \- errout: 100 \- dropin: 100 \- dropout: 100 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.beacons.network_settings .sp Beacon to monitor network adapter setting changes on Linux .sp New in version 2016.3.0. .INDENT 0.0 .TP .B class salt.beacons.network_settings.Hashabledict Helper class that implements a hash function for a dictionary .UNINDENT .INDENT 0.0 .TP .B salt.beacons.network_settings.beacon(config) Watch for changes on network settings .sp By default, the beacon will emit when there is a value change on one of the settings on watch. The config also support the onvalue parameter for each setting, which instruct the beacon to only emit if the setting changed to the value defined. .sp Example Config .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C beacons: network_settings: eth0: ipaddr: promiscuity: onvalue: 1 eth1: linkmode: .ft P .fi .UNINDENT .UNINDENT .sp The config above will check for value changes on eth0 ipaddr and eth1 linkmode. It will also emit if the promiscuity value changes to 1. .sp Beacon items can use the * wildcard to make a definition apply to several interfaces. For example an eth* would apply to all ethernet interfaces. .sp Setting the argument coalesce = True will combine all the beacon results on a single event. The example below shows how to trigger coalesced results: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C beacons: network_settings: coalesce: True eth0: ipaddr: promiscuity: .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.beacons.pkg .sp Watch for pkgs that have upgrades, then fire an event. .sp New in version 2016.3.0. .INDENT 0.0 .TP .B salt.beacons.pkg.beacon(config) Check if installed packages are the latest versions and fire an event for those that have upgrades. .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C beacons: pkg: \- pkgs: \- zsh \- apache2 \- refresh: True .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.beacons.proxy_example module .sp Example beacon to use with salt\-proxy .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C beacons: proxy_example: endpoint: beacon .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.beacons.proxy_example.beacon(config) Called several times each second \fI\%https://docs.saltstack.com/en/latest/topics/beacons/#the\-beacon\-function\fP .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C beacons: proxy_example: endpoint: beacon .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.beacons.ps module .sp Send events covering service status .INDENT 0.0 .TP .B salt.beacons.ps.beacon(config) Scan for processes and fire events .sp Example Config .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C beacons: ps: salt\-master: running mysql: stopped .ft P .fi .UNINDENT .UNINDENT .sp The config above sets up beacons to check that processes are running or stopped. .UNINDENT .SS salt.beacons.salt_proxy module .sp Beacon to manage and report the status of one or more salt proxy processes .sp New in version 2015.8.3. .INDENT 0.0 .TP .B salt.beacons.salt_proxy.beacon(proxies) Handle configured proxies .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C beacons: salt_proxy: \- p8000: {} \- p8001: {} .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.beacons.service .sp Send events covering service status .INDENT 0.0 .TP .B salt.beacons.service.beacon(config) Scan for the configured services and fire events .sp Example Config .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C beacons: service: salt\-master: mysql: .ft P .fi .UNINDENT .UNINDENT .sp The config above sets up beacons to check for the salt\-master and mysql services. .sp The config also supports two other parameters for each service: .sp \fIonchangeonly\fP: when \fIonchangeonly\fP is True the beacon will fire events only when the service status changes. Otherwise, it will fire an event at each beacon interval. The default is False. .sp \fIemitatstartup\fP: when \fIemitatstartup\fP is False the beacon will not fire event when the minion is reload. Applicable only when \fIonchangeonly\fP is True. The default is True. .sp \fIuncleanshutdown\fP: If \fIuncleanshutdown\fP is present it should point to the location of a pid file for the service. Most services will not clean up this pid file if they are shutdown uncleanly (e.g. via \fIkill \-9\fP) or if they are terminated through a crash such as a segmentation fault. If the file is present, then the beacon will add \fIuncleanshutdown: True\fP to the event. If not present, the field will be False. The field is only added when the service is NOT running. Omitting the configuration variable altogether will turn this feature off. .sp Please note that some init systems can remove the pid file if the service registers as crashed. One such example is nginx on CentOS 7, where the service unit removes the pid file when the service shuts down (IE: the pid file is observed as removed when kill \-9 is sent to the nginx master process). The \(aquncleanshutdown\(aq option might not be of much use there, unless the unit file is modified. .sp Here is an example that will fire an event whenever the state of nginx changes and report an uncleanshutdown. This example is for Arch, which places nginx\(aqs pid file in \fI/run\fP\&. .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C beacons: service: nginx: onchangeonly: True uncleanshutdown: /run/nginx.pid .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.beacons.sh .sp Watch the shell commands being executed actively. This beacon requires strace. .INDENT 0.0 .TP .B salt.beacons.sh.beacon(config) Scan the shell execve routines. This beacon will convert all login shells .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C beacons: sh: {} .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.beacons.status module .sp The status beacon is intended to send a basic health check event up to the master, this allows for event driven routines based on presence to be set up. .sp The intention of this beacon is to add the config options to add monitoring stats to the health beacon making it a one stop shop for gathering systems health and status data .sp New in version 2016.11.0. .sp To configure this beacon to use the defaults, set up an empty dict for it in the minion config: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C beacons: status: {} .ft P .fi .UNINDENT .UNINDENT .sp By default, all of the information from the following execution module functions will be returned: .INDENT 0.0 .INDENT 3.5 .INDENT 0.0 .IP \(bu 2 loadavg .IP \(bu 2 cpustats .IP \(bu 2 meminfo .IP \(bu 2 vmstats .IP \(bu 2 time .UNINDENT .UNINDENT .UNINDENT .sp You can also configure your own set of functions to be returned: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C beacons: status: \- time: \- all \- loadavg: \- all .ft P .fi .UNINDENT .UNINDENT .sp You may also configure only certain fields from each function to be returned. For instance, the \fBloadavg\fP function returns the following fields: .INDENT 0.0 .INDENT 3.5 .INDENT 0.0 .IP \(bu 2 1\-min .IP \(bu 2 5\-min .IP \(bu 2 15\-min .UNINDENT .UNINDENT .UNINDENT .sp If you wanted to return only the \fB1\-min\fP and \fB5\-min\fP fields for \fBloadavg\fP then you would configure: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C beacons: status: \- loadavg: \- 1\-min \- 5\-min .ft P .fi .UNINDENT .UNINDENT .sp Other functions only return a single value instead of a dictionary. With these, you may specify \fBall\fP or \fB0\fP\&. The following are both valid: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C beacons: status: \- time: \- all beacons: status: \- time: \- 0 .ft P .fi .UNINDENT .UNINDENT .sp If a \fBstatus\fP function returns a list, you may return the index marker or markers for specific list items: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C beacons: status: \- w: \- 0 \- 1 \- 2 .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.beacons.status.beacon(config) Return status for requested information .UNINDENT .SS salt.beacons.twilio_txt_msg .sp Beacon to emit Twilio text messages .INDENT 0.0 .TP .B salt.beacons.twilio_txt_msg.beacon(config) Emit a dict name "texts" whose value is a list of texts. .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C beacons: twilio_txt_msg: account_sid: "" auth_token: "" twilio_number: "+15555555555" interval: 10 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.beacons.wtmp .sp Beacon to fire events at login of users as registered in the wtmp file .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C beacons: wtmp: {} .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.beacons.wtmp.beacon(config) Read the last wtmp file and return information on the logins .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C beacons: wtmp: {} .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS engine modules .TS center; |l|l|. _ T{ \fBdocker_events\fP T} T{ Send events from Docker events T} _ T{ \fBhttp_logstash\fP T} T{ HTTP Logstash engine T} _ T{ \fBlogentries\fP T} T{ An engine that sends events to the Logentries logging service. T} _ T{ \fBlogstash\fP T} T{ An engine that reads messages from the salt event bus and pushes them onto a logstash endpoint. T} _ T{ \fBreactor\fP T} T{ Setup Reactor T} _ T{ \fBredis_sentinel\fP T} T{ An engine that reads messages from the redis sentinel pubsub and sends reactor events based on the channels they are subscribed to. T} _ T{ \fBslack\fP T} T{ An engine that reads messages from Slack and sends them to the Salt event bus. T} _ T{ \fBsqs_events\fP T} T{ An engine that continuously reads messages from SQS and fires them as events. T} _ T{ \fBtest\fP T} T{ A simple test engine, not intended for real use but as an example T} _ T{ \fBthorium\fP T} T{ Manage the Thorium complex event reaction system T} _ .TE .SS salt.engines.docker_events module .sp Send events from Docker events :Depends: Docker API >= 1.22 .INDENT 0.0 .TP .B salt.engines.docker_events.start(docker_url=\(aqunix://var/run/docker.sock\(aq, timeout=60, tag=\(aqsalt/engines/docker_events\(aq) Scan for Docker events and fire events .sp Example Config .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C engines: docker_events: docker_url: unix://var/run/docker.sock .ft P .fi .UNINDENT .UNINDENT .sp The config above sets up engines to listen for events from the Docker daemon and publish them to the Salt event bus. .UNINDENT .SS salt.engines.http_logstash .SS HTTP Logstash engine .sp An engine that reads messages from the salt event bus and pushes them onto a logstash endpoint via HTTP requests. .INDENT 0.0 .TP .B configuration Example configuration .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C engines: \- http_logstash: url: http://blabla.com/salt\-stuff tags: \- salt/job/*/new \- salt/job/*/ret/* funs: \- probes.results \- bgp.config .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.engines.http_logstash.start(url, funs=None, tags=None) Listen to salt events and forward them to logstash via HTTP. .UNINDENT .SS salt.engines.logentries .sp An engine that sends events to the Logentries logging service. .INDENT 0.0 .TP .B maintainer Jimmy Tang (\fI\%jimmy_tang@rapid7.com\fP) .TP .B maturity New .TP .B depends ssl, certifi .TP .B platform all .UNINDENT .sp To enable this engine the master and/or minion will need the following python libraries .INDENT 0.0 .INDENT 3.5 ssl certifi .UNINDENT .UNINDENT .sp If you are running a new enough version of python then the ssl library will be present already. .sp You will also need the following values configured in the minion or master config. .INDENT 0.0 .TP .B configuration .INDENT 7.0 .TP .B Example configuration .INDENT 7.0 .TP .B engines: .INDENT 7.0 .IP \(bu 2 logentries: endpoint: data.logentries.com port: 10000 token: 057af3e2\-1c05\-47c5\-882a\-5cd644655dbf .UNINDENT .UNINDENT .UNINDENT .UNINDENT .sp The \(aqtoken\(aq can be obtained from the Logentries service. .sp To test this engine .INDENT 0.0 .INDENT 3.5 .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq test.ping cmd.run uptime .ft P .fi .UNINDENT .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.engines.logentries.start(endpoint=\(aqdata.logentries.com\(aq, port=10000, token=None, tag=\(aqsalt/engines/logentries\(aq) Listen to salt events and forward them to Logentries .UNINDENT .SS salt.engines.logstash .sp An engine that reads messages from the salt event bus and pushes them onto a logstash endpoint. .INDENT 0.0 .TP .B configuration .INDENT 7.0 .TP .B Example configuration .INDENT 7.0 .TP .B engines: .INDENT 7.0 .IP \(bu 2 logstash: host: log.my_network.com port: 5959 .UNINDENT .UNINDENT .UNINDENT .TP .B depends logstash .UNINDENT .INDENT 0.0 .TP .B salt.engines.logstash.start(host, port=5959, tag=\(aqsalt/engine/logstash\(aq) Listen to salt events and forward them to logstash .UNINDENT .SS salt.engines.reactor module .sp Setup Reactor .sp Example Config in Master or Minion config .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C engines: reactor: refresh_interval: 60 worker_threads: 10 worker_hwm: 10000 reactor: \- \(aqsalt/cloud/*/destroyed\(aq: \- /srv/reactor/destroy/*.sls .ft P .fi .UNINDENT .UNINDENT .SS salt.engines.redis_sentinel module .sp An engine that reads messages from the redis sentinel pubsub and sends reactor events based on the channels they are subscribed to. .INDENT 0.0 .TP .B configuration .INDENT 7.0 .TP .B Example configuration .INDENT 7.0 .TP .B engines: .INDENT 7.0 .IP \(bu 2 .INDENT 2.0 .TP .B redis_sentinel: .INDENT 7.0 .TP .B hosts: matching: \(aqboard*\(aq port: 26379 interface: eth2 .TP .B channels: .INDENT 7.0 .IP \(bu 2 \(aq+switch\-master\(aq .IP \(bu 2 \(aq+odown\(aq .IP \(bu 2 \(aq\-odown\(aq .UNINDENT .UNINDENT .UNINDENT .UNINDENT .UNINDENT .UNINDENT .TP .B depends redis .UNINDENT .SS salt.engines.slack module .sp An engine that reads messages from Slack and sends them to the Salt event bus. Alternatively Salt commands can be sent to the Salt master via Slack by setting the control parameter to \fBTrue\fP and using command prefaced with a \fB!\fP\&. .INDENT 0.0 .TP .B configuration Example configuration .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C engines: slack: token: \(aqxoxb\-xxxxxxxxxx\-xxxxxxxxxxxxxxxxxxxxxxxx\(aq control: True valid_users: \- garethgreenaway valid_commands: \- test.ping \- cmd.run \- list_jobs \- list_commands aliases: list_jobs: cmd: jobs.list_jobs list_commands: cmd: pillar.get salt:engines:slack:valid_commands target=saltmaster .ft P .fi .UNINDENT .UNINDENT .TP .B depends slackclient .UNINDENT .INDENT 0.0 .TP .B salt.engines.slack.start(token, aliases=None, valid_users=None, valid_commands=None, control=False, trigger=\(aq!\(aq, tag=\(aqsalt/engines/slack\(aq) Listen to Slack events and forward them to Salt .UNINDENT .SS salt.engines.sqs_events .sp An engine that continuously reads messages from SQS and fires them as events. .sp Note that long polling is utilized to avoid excessive CPU usage. .sp New in version 2015.8.0. .INDENT 0.0 .TP .B depends boto .UNINDENT .SS Configuration .sp This engine can be run on the master or on a minion. .sp Example Config: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C sqs.keyid: GKTADJGHEIQSXMKKRBJ08H sqs.key: askdjghsdfjkghWupUjasdflkdfklgjsdfjajkghs sqs.message_format: json .ft P .fi .UNINDENT .UNINDENT .sp Explicit sqs credentials are accepted but this engine can also utilize IAM roles assigned to the instance through Instance Profiles. Dynamic credentials are then automatically obtained from AWS API and no further configuration is necessary. More Information available at: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/iam\-roles\-for\-amazon\-ec2.html .ft P .fi .UNINDENT .UNINDENT .sp If IAM roles are not (or for \fBboto\fP version < 2.5.1) used you need to specify them either in a pillar or in the config file of the master or minion, as appropriate: .sp To deserialize the message from json: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C sqs.message_format: json .ft P .fi .UNINDENT .UNINDENT .sp It\(aqs also possible to specify key, keyid and region via a profile: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C sqs.keyid: GKTADJGHEIQSXMKKRBJ08H sqs.key: askdjghsdfjkghWupUjasdflkdfklgjsdfjajkghs .ft P .fi .UNINDENT .UNINDENT .sp A region may also be specified in the configuration: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C sqs.region: us\-east\-1 .ft P .fi .UNINDENT .UNINDENT .sp If a region is not specified, the default is us\-east\-1. .sp It\(aqs also possible to specify key, keyid and region via a profile: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C myprofile: keyid: GKTADJGHEIQSXMKKRBJ08H key: askdjghsdfjkghWupUjasdflkdfklgjsdfjajkghs region: us\-east\-1 .ft P .fi .UNINDENT .UNINDENT .sp Additionally you can define cross account sqs: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C engines: \- sqs_events: queue: prod owner_acct_id: 111111111111 .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.engines.sqs_events.start(queue, profile=None, tag=\(aqsalt/engine/sqs\(aq, owner_acct_id=None) Listen to sqs and fire message on event bus .UNINDENT .SS salt.engines.test .sp A simple test engine, not intended for real use but as an example .INDENT 0.0 .TP .B salt.engines.test.start() Listen to events and write them to a log file .UNINDENT .SS salt.engines.thorium module .sp Manage the Thorium complex event reaction system .INDENT 0.0 .TP .B salt.engines.thorium.start(grains=False, grain_keys=None, pillar=False, pillar_keys=None) Execute the Thorium runtime .UNINDENT .SS fileserver modules .TS center; |l|l|. _ T{ \fBazurefs\fP T} T{ The backend for serving files from the Azure blob storage service. T} _ T{ \fBgitfs\fP T} T{ Git Fileserver Backend T} _ T{ \fBhgfs\fP T} T{ Mercurial Fileserver Backend T} _ T{ \fBminionfs\fP T} T{ Fileserver backend which serves files pushed to the Master T} _ T{ \fBroots\fP T} T{ The default file server backend T} _ T{ \fBs3fs\fP T} T{ Amazon S3 Fileserver Backend T} _ T{ \fBsvnfs\fP T} T{ Subversion Fileserver Backend T} _ .TE .SS salt.fileserver.azurefs .sp The backend for serving files from the Azure blob storage service. .sp To enable, add \fBazurefs\fP to the \fBfileserver_backend\fP option in the Master config file. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C fileserver_backend: \- azurefs .ft P .fi .UNINDENT .UNINDENT .sp Each environment is configured as a storage container. The name of the container must match the name of the environment. The \fBstorage_account\fP is the name of the storage account inside Azure where the container lives, and the \fBstorage_key\fP is the access key used for that storage account: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C azurefs_envs: base: storage_account: my_storage storage_key: frehgfw34fWGegG07fwsfw343tGFDSDGDFGD== .ft P .fi .UNINDENT .UNINDENT .sp With this configuration, multiple storage accounts can be used with a single salt instrastructure. .SS salt.fileserver.gitfs .sp Git Fileserver Backend .sp With this backend, branches and tags in a remote git repository are exposed to salt as different environments. .sp To enable, add \fBgit\fP to the \fBfileserver_backend\fP option in the Master config file. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C fileserver_backend: \- git .ft P .fi .UNINDENT .UNINDENT .sp As of Salt 2014.7.0, the Git fileserver backend supports \fI\%GitPython\fP, \fI\%pygit2\fP, and \fI\%dulwich\fP to provide the Python interface to git. If more than one of these are present, the order of preference for which one will be chosen is the same as the order in which they were listed: pygit2, GitPython, dulwich (keep in mind, this order is subject to change). .sp An optional master config parameter (\fBgitfs_provider\fP) can be used to specify which provider should be used. .sp More detailed information on how to use gitfs can be found in the Gitfs Walkthrough\&. .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 Minimum requirements .sp To use \fI\%GitPython\fP for gitfs requires a minimum GitPython version of 0.3.0, as well as the git CLI utility. Instructions for installing GitPython can be found here\&. .sp To use \fI\%pygit2\fP for gitfs requires a minimum \fI\%pygit2\fP version of 0.20.3. \fI\%pygit2\fP 0.20.3 requires \fI\%libgit2\fP 0.20.0. \fI\%pygit2\fP and \fI\%libgit2\fP are developed alongside one another, so it is recommended to keep them both at the same major release to avoid unexpected behavior. For example, \fI\%pygit2\fP 0.21.x requires \fI\%libgit2\fP 0.21.x, \fI\%pygit2\fP 0.22.x will require \fI\%libgit2\fP 0.22.x, etc. .sp To find stale refs, pygit2 additionally requires the git CLI utility to be installed. .UNINDENT .UNINDENT .SS salt.fileserver.hgfs .sp Mercurial Fileserver Backend .sp To enable, add \fBhg\fP to the \fBfileserver_backend\fP option in the Master config file. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C fileserver_backend: \- hg .ft P .fi .UNINDENT .UNINDENT .sp After enabling this backend, branches, bookmarks, and tags in a remote mercurial repository are exposed to salt as different environments. This feature is managed by the \fBfileserver_backend\fP option in the salt master config file. .sp This fileserver has an additional option \fBhgfs_branch_method\fP that will set the desired branch method. Possible values are: \fBbranches\fP, \fBbookmarks\fP, or \fBmixed\fP\&. If using \fBbranches\fP or \fBmixed\fP, the \fBdefault\fP branch will be mapped to \fBbase\fP\&. .sp Changed in version 2014.1.0: The \fBhgfs_base\fP master config parameter was added, allowing for a branch other than \fBdefault\fP to be used for the \fBbase\fP environment, and allowing for a \fBbase\fP environment to be specified when using an \fBhgfs_branch_method\fP of \fBbookmarks\fP\&. .INDENT 0.0 .TP .B depends .INDENT 7.0 .IP \(bu 2 mercurial .IP \(bu 2 python bindings for mercurial (\fBpython\-hglib\fP) .UNINDENT .UNINDENT .SS salt.fileserver.minionfs .sp Fileserver backend which serves files pushed to the Master .sp The \fBcp.push\fP function allows Minions to push files up to the Master. Using this backend, these pushed files are exposed to other Minions via the Salt fileserver. .sp To enable minionfs, \fBfile_recv\fP needs to be set to \fBTrue\fP in the master config file (otherwise \fBcp.push\fP will not be allowed to push files to the Master), and \fBminion\fP must be added to the \fBfileserver_backends\fP list. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C fileserver_backend: \- minion .ft P .fi .UNINDENT .UNINDENT .sp Other minionfs settings include: \fBminionfs_whitelist\fP, \fBminionfs_blacklist\fP, \fBminionfs_mountpoint\fP, and \fBminionfs_env\fP\&. .sp \fBSEE ALSO:\fP .INDENT 0.0 .INDENT 3.5 tutorial\-minionfs .UNINDENT .UNINDENT .SS salt.fileserver.roots .sp The default file server backend .sp This fileserver backend serves files from the Master\(aqs local filesystem. If \fBfileserver_backend\fP is not defined in the Master config file, then this backend is enabled by default. If it \fIis\fP defined then \fBroots\fP must be in the \fBfileserver_backend\fP list to enable this backend. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C fileserver_backend: \- roots .ft P .fi .UNINDENT .UNINDENT .sp Fileserver environments are defined using the \fBfile_roots\fP configuration option. .SS salt.fileserver.s3fs .sp Amazon S3 Fileserver Backend .sp This backend exposes directories in S3 buckets as Salt environments. To enable this backend, add \fBs3fs\fP to the \fBfileserver_backend\fP option in the Master config file. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C fileserver_backend: \- s3fs .ft P .fi .UNINDENT .UNINDENT .sp S3 credentials must also be set in the master config file: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C s3.keyid: GKTADJGHEIQSXMKKRBJ08H s3.key: askdjghsdfjkghWupUjasdflkdfklgjsdfjajkghs .ft P .fi .UNINDENT .UNINDENT .sp Alternatively, if on EC2 these credentials can be automatically loaded from instance metadata. .sp This fileserver supports two modes of operation for the buckets: .INDENT 0.0 .IP 1. 3 \fBA single bucket per environment\fP .INDENT 3.0 .INDENT 3.5 .sp .nf .ft C s3.buckets: production: \- bucket1 \- bucket2 staging: \- bucket3 \- bucket4 .ft P .fi .UNINDENT .UNINDENT .IP 2. 3 \fBMultiple environments per bucket\fP .INDENT 3.0 .INDENT 3.5 .sp .nf .ft C s3.buckets: \- bucket1 \- bucket2 \- bucket3 \- bucket4 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .sp Note that bucket names must be all lowercase both in the AWS console and in Salt, otherwise you may encounter \fBSignatureDoesNotMatch\fP errors. .sp A multiple\-environment bucket must adhere to the following root directory structure: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C s3://// .ft P .fi .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 This fileserver back\-end requires the use of the MD5 hashing algorithm. MD5 may not be compliant with all security policies. .UNINDENT .UNINDENT .SS salt.fileserver.svnfs .sp Subversion Fileserver Backend .sp After enabling this backend, branches, and tags in a remote subversion repository are exposed to salt as different environments. To enable this backend, add \fBsvn\fP to the \fBfileserver_backend\fP option in the Master config file. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C fileserver_backend: \- svn .ft P .fi .UNINDENT .UNINDENT .sp This backend assumes a standard svn layout with directories for \fBbranches\fP, \fBtags\fP, and \fBtrunk\fP, at the repository root. .INDENT 0.0 .TP .B depends .INDENT 7.0 .IP \(bu 2 subversion .IP \(bu 2 pysvn .UNINDENT .UNINDENT .sp Changed in version 2014.7.0: The paths to the trunk, branches, and tags have been made configurable, via the config options \fBsvnfs_trunk\fP, \fBsvnfs_branches\fP, and \fBsvnfs_tags\fP\&. \fBsvnfs_mountpoint\fP was also added. Finally, support for per\-remote configuration parameters was added. See the \fBdocumentation\fP for more information. .SS grains modules .TS center; |l|l|. _ T{ \fBchronos\fP T} T{ Generate chronos proxy minion grains. T} _ T{ \fBcore\fP T} T{ The static grains, these are the core, or built in grains. T} _ T{ \fBdisks\fP T} T{ Detect disks T} _ T{ \fBesxi\fP T} T{ Generate baseline proxy minion grains for ESXi hosts. T} _ T{ \fBextra\fP T} T{ T} _ T{ \fBfx2\fP T} T{ Generate baseline proxy minion grains for Dell FX2 chassis. T} _ T{ \fBjunos\fP T} T{ Grains for junos. T} _ T{ \fBmarathon\fP T} T{ Generate marathon proxy minion grains. T} _ T{ \fBmdadm\fP T} T{ Detect MDADM RAIDs T} _ T{ \fBopts\fP T} T{ Simple grain to merge the opts into the grains directly if the grain_opts T} _ T{ \fBphilips_hue\fP T} T{ Static grains for the Philips HUE lamps T} _ T{ \fBrest_sample\fP T} T{ Generate baseline proxy minion grains T} _ .TE .SS salt.grains.chronos .sp Generate chronos proxy minion grains. .sp New in version 2015.8.2. .SS salt.grains.core .sp The static grains, these are the core, or built in grains. .sp When grains are loaded they are not loaded in the same way that modules are loaded, grain functions are detected and executed, the functions MUST return a dict which will be applied to the main grains dict. This module will always be executed first, so that any grains loaded here in the core module can be overwritten just by returning dict keys with the same value as those returned here .INDENT 0.0 .TP .B salt.grains.core.append_domain() Return append_domain if set .UNINDENT .INDENT 0.0 .TP .B salt.grains.core.dns() Parse the resolver configuration file .INDENT 7.0 .INDENT 3.5 New in version 2016.3.0. .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.grains.core.get_machine_id() Provide the machine\-id .UNINDENT .INDENT 0.0 .TP .B salt.grains.core.get_master() Provides the minion with the name of its master. This is useful in states to target other services running on the master. .UNINDENT .INDENT 0.0 .TP .B salt.grains.core.get_server_id() Provides an integer based on the FQDN of a machine. Useful as server\-id in MySQL replication or anywhere else you\(aqll need an ID like this. .UNINDENT .INDENT 0.0 .TP .B salt.grains.core.hostname() Return fqdn, hostname, domainname .UNINDENT .INDENT 0.0 .TP .B salt.grains.core.hwaddr_interfaces() Provide a dict of the connected interfaces and their hw addresses (Mac Address) .UNINDENT .INDENT 0.0 .TP .B salt.grains.core.id_() Return the id .UNINDENT .INDENT 0.0 .TP .B salt.grains.core.ip4_interfaces() Provide a dict of the connected interfaces and their ip4 addresses The addresses will be passed as a list for each interface .UNINDENT .INDENT 0.0 .TP .B salt.grains.core.ip6_interfaces() Provide a dict of the connected interfaces and their ip6 addresses The addresses will be passed as a list for each interface .UNINDENT .INDENT 0.0 .TP .B salt.grains.core.ip_fqdn() Return ip address and FQDN grains .UNINDENT .INDENT 0.0 .TP .B salt.grains.core.ip_interfaces() Provide a dict of the connected interfaces and their ip addresses The addresses will be passed as a list for each interface .UNINDENT .INDENT 0.0 .TP .B salt.grains.core.locale_info() .INDENT 7.0 .TP .B Provides defaultlanguage defaultencoding .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.grains.core.os_data() Return grains pertaining to the operating system .UNINDENT .INDENT 0.0 .TP .B salt.grains.core.path() Return the path .UNINDENT .INDENT 0.0 .TP .B salt.grains.core.pythonexecutable() Return the python executable in use .UNINDENT .INDENT 0.0 .TP .B salt.grains.core.pythonpath() Return the Python path .UNINDENT .INDENT 0.0 .TP .B salt.grains.core.pythonversion() Return the Python version .UNINDENT .INDENT 0.0 .TP .B salt.grains.core.saltpath() Return the path of the salt module .UNINDENT .INDENT 0.0 .TP .B salt.grains.core.saltversion() Return the version of salt .UNINDENT .INDENT 0.0 .TP .B salt.grains.core.saltversioninfo() Return the version_info of salt .INDENT 7.0 .INDENT 3.5 New in version 0.17.0. .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.grains.core.zmqversion() Return the zeromq version .UNINDENT .SS salt.grains.disks .sp Detect disks .INDENT 0.0 .TP .B salt.grains.disks.disks() Return list of disk devices .UNINDENT .SS salt.grains.esxi .sp Generate baseline proxy minion grains for ESXi hosts. .sp \&., versionadded:: 2015.8.4 .SS salt.grains.extra .INDENT 0.0 .TP .B salt.grains.extra.config() Return the grains set in the grains file .UNINDENT .INDENT 0.0 .TP .B salt.grains.extra.shell() Return the default shell to use on this system .UNINDENT .SS salt.grains.fx2 .sp Generate baseline proxy minion grains for Dell FX2 chassis. The challenge is that most of Salt isn\(aqt bootstrapped yet, so we need to repeat a bunch of things that would normally happen in proxy/fx2.py\-\-just enough to get data from the chassis to include in grains. .SS salt.grains.junos .sp Grains for junos. NOTE this is a little complicated\-\-junos can only be accessed via salt\-proxy\-minion.Thus, some grains make sense to get them from the minion (PYTHONPATH), but others don\(aqt (ip_interfaces) .SS salt.grains.marathon .sp Generate marathon proxy minion grains. .sp New in version 2015.8.2. .SS salt.grains.mdadm .sp Detect MDADM RAIDs .INDENT 0.0 .TP .B salt.grains.mdadm.mdadm() Return list of mdadm devices .UNINDENT .SS salt.grains.opts .sp Simple grain to merge the opts into the grains directly if the grain_opts configuration value is set .INDENT 0.0 .TP .B salt.grains.opts.opts() Return the minion configuration settings .UNINDENT .SS salt.grains.philips_hue .sp Static grains for the Philips HUE lamps .sp New in version 2015.8.3. .SS salt.grains.rest_sample .sp Generate baseline proxy minion grains .INDENT 0.0 .TP .B salt.grains.rest_sample.proxy_functions(proxy) The loader will execute functions with one argument and pass a reference to the proxymodules LazyLoader object. However, grains sometimes get called before the LazyLoader object is setup so \fIproxy\fP might be None. .UNINDENT .SS 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: .TS center; |l|l|. _ T{ Execution Module T} T{ Used for T} _ T{ \fBaptpkg\fP T} T{ Debian/Ubuntu\-based distros which use \fBapt\-get(8)\fP for package management T} _ T{ \fBbrew\fP T} T{ Mac OS software management using \fI\%Homebrew\fP T} _ T{ \fBebuild\fP T} T{ Gentoo\-based systems (utilizes the \fBportage\fP python module as well as \fBemerge(1)\fP) T} _ T{ \fBfreebsdpkg\fP T} T{ FreeBSD\-based OSes using \fBpkg_add(1)\fP T} _ T{ \fBopenbsdpkg\fP T} T{ OpenBSD\-based OSes using \fBpkg_add(1)\fP T} _ T{ \fBpacman\fP T} T{ Arch Linux\-based distros using \fBpacman(8)\fP T} _ T{ \fBpkgin\fP T} T{ NetBSD\-based OSes using \fBpkgin(1)\fP T} _ T{ \fBpkgng\fP T} T{ FreeBSD\-based OSes using \fBpkg(8)\fP T} _ T{ \fBpkgutil\fP T} T{ Solaris\-based OSes using \fI\%OpenCSW\fP\(aqs \fBpkgutil(1)\fP T} _ T{ \fBsolarispkg\fP T} T{ Solaris\-based OSes using \fBpkgadd(1M)\fP T} _ T{ \fBsolarisips\fP T} T{ Solaris\-based OSes using IPS \fBpkg(1)\fP T} _ T{ \fBwin_pkg\fP T} T{ Salt\(aqs Windows Package Manager .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_exists(name, path) Check if the given path is an alternative for a name. .sp New in version 2015.8.4. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq alternatives.check_exists name path .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 .INDENT 0.0 .TP .B salt.modules.alternatives.show_link(name) Display master link for the alternative .sp New in version 2015.8.13,2016.3.4,2016.11.0. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq alternatives.show_link editor .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.apache .sp Support for Apache .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 The functions in here are generic functions designed to work with all implementations of Apache. Debian\-specific functions have been moved into deb_apache.py, but will still load under the \fBapache\fP namespace when a Debian\-based system is detected. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.apache.config(name, config, edit=True) Create VirtualHost configuration files .INDENT 7.0 .TP .B name File for the virtual host .TP .B config VirtualHost configurations .UNINDENT .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 This function is not meant to be used from the command line. Config is meant to be an ordered dict of all of the apache configs. .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq apache.config /etc/httpd/conf.d/ports.conf config="[{\(aqListen\(aq: \(aq22\(aq}]" .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 (\fBapachectl \-V\fP) .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 (\fBapachectl \-M\fP) .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 \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 The server\-status handler is disabled by default. In order for this function to work it needs to be enabled. See \fI\%http://httpd.apache.org/docs/2.2/mod/mod_status.html\fP .UNINDENT .UNINDENT .sp The following configuration needs to exists in pillar/grains. Each entry nested in \fBapache.server\-status\fP is a profile of a vhost/server. This would give support for multiple apache servers/vhosts. .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C apache.server\-status: default: url: http://localhost/server\-status user: someuser pass: password realm: \(aqauthentication realm for digest passwords\(aq timeout: 5 .ft P .fi .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 (\fBapachectl \-l\fP) .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 HTTP user using the \fBhtpasswd\fP command. If the \fBhtpasswd\fP file does not exist, it will be created. Valid options that can be passed are: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C n Don\(aqt update file; display results on stdout. m Force MD5 hashing of the password (default). d Force CRYPT(3) hashing of the password. p Do not hash the password (plaintext). s Force SHA1 hashing of the password. .ft P .fi .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 HTTP user from the specified \fBhtpasswd\fP file. .sp CLI Example: .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 (\fBapachectl \-v\fP) .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 by using \fB\-t 10\fP\&. .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.apcups .sp Module for apcupsd .INDENT 0.0 .TP .B salt.modules.apcups.status() Return apcaccess output .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq apcups.status .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.apcups.status_battery() Return true if running on battery power .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq apcups.status_battery .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.apcups.status_charge() Return battery charge .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq apcups.status_charge .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.apcups.status_load() Return load .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq apcups.status_load .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.apf .SS Support for Advanced Policy Firewall (APF) .INDENT 0.0 .TP .B maintainer Mostafa Hussein <\fI\%mostafa.hussein91@gmail.com\fP> .TP .B maturity new .TP .B depends python\-iptables .TP .B platform Linux .UNINDENT .INDENT 0.0 .TP .B salt.modules.apf.allow(ip, port=None) Add host (IP/FQDN) to allow_hosts.rules and immediately load new rule into firewall CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq apf.allow 127.0.0.1 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.apf.deny(ip) Add host (IP/FQDN) to deny_hosts.rules and immediately load new rule into firewall CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq apf.deny 1.2.3.4 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.apf.disable() Stop (flush) all firewall rules CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq apf.disable .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.apf.enable() Load all firewall rules CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq apf.enable .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.apf.refresh() Refresh & resolve dns names in trust rules CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq apf.refresh .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.apf.reload() Stop (flush) & reload firewall rules CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq apf.reload .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.apf.remove(ip) Remove host from [glob]*_hosts.rules and immediately remove rule from firewall CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq apf.remove 1.2.3.4 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.apf.running() Check apf status CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq apf.running .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.aptpkg .sp Support for APT (Advanced Packaging Tool) .sp \fBIMPORTANT:\fP .INDENT 0.0 .INDENT 3.5 If you feel that Salt should be using this module to manage packages on a minion, and it is using a different module (or gives an error similar to \fI\(aqpkg.install\(aq is not available\fP), see here\&. .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 For virtual package support, either the \fBpython\-apt\fP or \fBdctrl\-tools\fP package must be installed. .sp For repository management, the \fBpython\-apt\fP package must be installed. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.aptpkg.autoremove(list_only=False, purge=False) New in version 2015.5.0. .sp Remove packages not required by another package using \fBapt\-get autoremove\fP\&. .INDENT 7.0 .TP .B list_only False Only retrieve the list of packages to be auto\-removed, do not actually perform the auto\-removal. .TP .B purge False Also remove package config data when autoremoving packages. .sp New in version 2015.8.0. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.autoremove salt \(aq*\(aq pkg.autoremove list_only=True salt \(aq*\(aq pkg.autoremove purge=True .ft P .fi .UNINDENT .UNINDENT .UNINDENT .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.del_repo_key(name=None, **kwargs) New in version 2015.8.0. .sp Remove a repo key using \fBapt\-key del\fP .INDENT 7.0 .TP .B name Repo from which to remove the key. Unnecessary if \fBkeyid\fP is passed. .TP .B keyid The KeyID of the GPG key to remove .TP .B keyid_ppa False If set to \fBTrue\fP, the repo\(aqs GPG key ID will be looked up from ppa.launchpad.net and removed. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 Setting this option to \fBTrue\fP requires that the \fBname\fP param also be passed. .UNINDENT .UNINDENT .UNINDENT .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.del_repo_key keyid=0123ABCD salt \(aq*\(aq pkg.del_repo_key name=\(aqppa:foo/bar\(aq keyid_ppa=True .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.aptpkg.expand_repo_def(**kwargs) 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 This is designed to be called from pkgrepo states and will have little use being called on 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_dict httpd salt \(aq*\(aq pkg.file_dict httpd postfix salt \(aq*\(aq pkg.file_dict .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.hold(name=None, pkgs=None, sources=None, **kwargs) New in version 2014.7.0. .sp Set package in \(aqhold\(aq state, meaning it will not be upgraded. .INDENT 7.0 .TP .B name The name of the package, e.g., \(aqtmux\(aq .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.hold .ft P .fi .UNINDENT .UNINDENT .TP .B pkgs A list of packages to hold. Must be passed as a python list. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.hold pkgs=\(aq["foo", "bar"]\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.aptpkg.info_installed(*names) Return the information of the named package(s) installed on the system. .sp New in version 2015.8.1. .INDENT 7.0 .TP .B names The names of the packages for which to return information. .UNINDENT .sp CLI example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.info_installed salt \(aq*\(aq pkg.info_installed ... .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, reinstall=False, **kwargs) Changed in version 2015.8.12,2016.3.3,2016.11.0: On minions running systemd>=205, \fI\%systemd\-run(1)\fP is now used to isolate commands which modify installed packages from the \fBsalt\-minion\fP daemon\(aqs control group. This is done to keep systemd from killing any apt\-get/dpkg commands spawned by Salt when the \fBsalt\-minion\fP service is restarted. (see \fBKillMode\fP in the \fI\%systemd.kill(5)\fP manpage for more information). If desired, usage of \fI\%systemd\-run(1)\fP can be suppressed by setting a \fBconfig option\fP called \fBsystemd.scope\fP, with a value of \fBFalse\fP (no quotes). .sp 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. .UNINDENT .sp cache_valid_time .INDENT 7.0 .INDENT 3.5 New in version 2016.11.0. .sp Skip refreshing the package database if refresh has already occurred within seconds .UNINDENT .UNINDENT .INDENT 7.0 .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. .TP .B reinstall False Specifying reinstall=True will use \fBapt\-get install \-\-reinstall\fP rather than simply \fBapt\-get install\fP for requested packages that are already installed. .sp If a version is specified with the requested package, then \fBapt\-get install \-\-reinstall\fP will only be used if the installed version matches the requested version. .sp New in version 2015.8.0. .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 2014.7.0. .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. .TP .B install_recommends Whether to install the packages marked as recommended. Default is True. .sp New in version 2015.5.0. .TP .B only_upgrade Only upgrade the packages, if they are already installed. Default is False. .sp New in version 2015.5.0. .TP .B force_conf_new Always install the new version of any configuration files. .sp New in version 2015.8.0. .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 cache_valid_time .INDENT 7.0 .INDENT 3.5 New in version 2016.11.0. .sp Skip refreshing the package database if refresh has already occurred within seconds .UNINDENT .UNINDENT .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 \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 External dependencies .sp Virtual package resolution requires the \fBdctrl\-tools\fP package to be installed. Virtual packages will show a version of \fB1\fP\&. .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, dist_upgrade=True, **kwargs) List all available package upgrades. .INDENT 7.0 .TP .B refresh Whether to refresh the package database before listing upgrades. Default: True. .UNINDENT .sp cache_valid_time .INDENT 7.0 .INDENT 3.5 New in version 2016.11.0. .sp Skip refreshing the package database if refresh has already occurred within seconds .UNINDENT .UNINDENT .INDENT 7.0 .TP .B dist_upgrade Whether to list the upgrades using dist\-upgrade vs upgrade. Default is to use dist\-upgrade. .UNINDENT .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 \fBppa:/repo\fP format is acceptable. \fBppa:\fP 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 .INDENT 0.0 .TP .B comps a comma separated list of components for the repo, e.g. \fBmain\fP .TP .B file a file name to be used .TP .B keyserver keyserver to get gpg key from .TP .B keyid key id to load with the keyserver argument .TP .B key_url URL to a GPG key to add to the APT GPG keyring .TP .B consolidate if \fBTrue\fP, will attempt to de\-dup and consolidate sources .TP .B comments Sometimes you want to supply additional information, but not as enabled configuration. Anything supplied for this list will be saved in the repo configuration with a comment marker (#) in front. .sp New in version 2015.8.9. .UNINDENT .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 Due to the way keys are stored for APT, there is a known issue where the key won\(aqt be updated unless another change is made at the same time. Keys should be properly added on initial configuration. .UNINDENT .UNINDENT .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.owner(*paths) New in version 2014.7.0. .sp Return the name of the package that owns the file. Multiple file paths can be passed. Like \fI\%pkg.version\fP, if a single path is passed, a string will be returned, and if multiple paths are passed, a dictionary of file/package name pairs will be returned. .sp If the file is not owned by a package, or is not present on the minion, then an empty string will be returned for that path. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.owner /usr/bin/apachectl salt \(aq*\(aq pkg.owner /usr/bin/apachectl /usr/bin/basename .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.aptpkg.purge(name=None, pkgs=None, **kwargs) Changed in version 2015.8.12,2016.3.3,2016.11.0: On minions running systemd>=205, \fI\%systemd\-run(1)\fP is now used to isolate commands which modify installed packages from the \fBsalt\-minion\fP daemon\(aqs control group. This is done to keep systemd from killing any apt\-get/dpkg commands spawned by Salt when the \fBsalt\-minion\fP service is restarted. (see \fBKillMode\fP in the \fI\%systemd.kill(5)\fP manpage for more information). If desired, usage of \fI\%systemd\-run(1)\fP can be suppressed by setting a \fBconfig option\fP called \fBsystemd.scope\fP, with a value of \fBFalse\fP (no quotes). .sp Remove packages via \fBapt\-get purge\fP along with all configuration files. .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(cache_valid_time=0) 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 cache_valid_time .INDENT 7.0 .INDENT 3.5 New in version 2016.11.0. .sp Skip refreshing the package database if refresh has already occurred within seconds .UNINDENT .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) Changed in version 2015.8.12,2016.3.3,2016.11.0: On minions running systemd>=205, \fI\%systemd\-run(1)\fP is now used to isolate commands which modify installed packages from the \fBsalt\-minion\fP daemon\(aqs control group. This is done to keep systemd from killing any apt\-get/dpkg commands spawned by Salt when the \fBsalt\-minion\fP service is restarted. (see \fBKillMode\fP in the \fI\%systemd.kill(5)\fP manpage for more information). If desired, usage of \fI\%systemd\-run(1)\fP can be suppressed by setting a \fBconfig option\fP called \fBsystemd.scope\fP, with a value of \fBFalse\fP (no quotes). .sp 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 .IP \(bu 2 install .IP \(bu 2 hold .IP \(bu 2 deinstall .IP \(bu 2 purge .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.unhold(name=None, pkgs=None, sources=None, **kwargs) New in version 2014.7.0. .sp Set package current in \(aqhold\(aq state to install state, meaning it will be upgraded. .INDENT 7.0 .TP .B name The name of the package, e.g., \(aqtmux\(aq .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.unhold .ft P .fi .UNINDENT .UNINDENT .TP .B pkgs A list of packages to hold. Must be passed as a python list. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.unhold pkgs=\(aq["foo", "bar"]\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.aptpkg.upgrade(refresh=True, dist_upgrade=False, **kwargs) Changed in version 2015.8.12,2016.3.3,2016.11.0: On minions running systemd>=205, \fI\%systemd\-run(1)\fP is now used to isolate commands which modify installed packages from the \fBsalt\-minion\fP daemon\(aqs control group. This is done to keep systemd from killing any apt\-get/dpkg commands spawned by Salt when the \fBsalt\-minion\fP service is restarted. (see \fBKillMode\fP in the \fI\%systemd.kill(5)\fP manpage for more information). If desired, usage of \fI\%systemd\-run(1)\fP can be suppressed by setting a \fBconfig option\fP called \fBsystemd.scope\fP, with a value of \fBFalse\fP (no quotes). .sp Upgrades all packages via \fBapt\-get upgrade\fP or \fBapt\-get dist\-upgrade\fP if \fBdist_upgrade\fP is \fBTrue\fP\&. .sp Returns a dictionary containing the changes: .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 .INDENT 7.0 .TP .B dist_upgrade Whether to perform the upgrade using dist\-upgrade vs upgrade. Default is to use upgrade. .sp New in version 2014.7.0. .UNINDENT .sp cache_valid_time .INDENT 7.0 .INDENT 3.5 New in version 2016.11.0. .sp Skip refreshing the package database if refresh has already occurred within seconds .UNINDENT .UNINDENT .INDENT 7.0 .TP .B force_conf_new Always install the new version of any configuration files. .sp New in version 2015.8.0. .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, ignore_epoch=False) 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. .INDENT 7.0 .TP .B ignore_epoch False Set to \fBTrue\fP to ignore the epoch when comparing versions .sp New in version 2015.8.10,2016.3.2. .UNINDENT .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 (non\-Windows) archive calls .sp New in version 2014.1.0. .INDENT 0.0 .TP .B salt.modules.archive.cmd_unzip(zip_file, dest, excludes=None, options=None, template=None, runas=None, trim_output=False, password=None) New in version 2015.5.0: In versions 2014.7.x and earlier, this function was known as \fBarchive.unzip\fP\&. .sp Uses the \fBunzip\fP command to unpack zip files. This command is part of the \fI\%Info\-ZIP\fP suite of tools, and is typically packaged as simply \fBunzip\fP\&. .INDENT 7.0 .TP .B zip_file Path of zip file to be unpacked .TP .B dest The destination directory into which the file should be unpacked .TP .B excludes None Comma\-separated list of files not to unpack. Can also be passed in a Python list. .TP .B template None Can be set to \(aqjinja\(aq or another supported template engine to render the command arguments before execution: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq archive.cmd_unzip template=jinja /tmp/zipfile.zip \(aq/tmp/{{grains.id}}\(aq excludes=file_1,file_2 .ft P .fi .UNINDENT .UNINDENT .TP .B options Optional when using \fBzip\fP archives, ignored when usign other archives files. This is mostly used to overwrite exsiting files with \fBo\fP\&. This options are only used when \fBunzip\fP binary is used. .sp New in version 2016.3.1. .TP .B runas None Unpack the zip file as the specified user. Defaults to the user under which the minion is running. .sp New in version 2015.5.0. .TP .B trim_output False The number of files we should output on success before the rest are trimmed, if this is set to True then it will default to 100 .TP .B password Password to use with password protected zip files .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 This is not considered secure. It is recommended to instead use \fI\%archive.unzip\fP for password\-protected ZIP files. If a password is used here, then the unzip command run to extract the ZIP file will not show up in the minion log like most shell commands Salt runs do. However, the password will still be present in the events logged to the minion log at the \fBdebug\fP log level. If the minion is logging at \fBdebug\fP (or more verbose), then be advised that the password will appear in the log. .UNINDENT .UNINDENT .sp New in version 2016.11.0. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq archive.cmd_unzip /tmp/zipfile.zip /home/strongbad/ excludes=file_1,file_2 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.archive.cmd_zip(zip_file, sources, template=None, cwd=None, runas=None) New in version 2015.5.0: In versions 2014.7.x and earlier, this function was known as \fBarchive.zip\fP\&. .sp Uses the \fBzip\fP command to create zip files. This command is part of the \fI\%Info\-ZIP\fP suite of tools, and is typically packaged as simply \fBzip\fP\&. .INDENT 7.0 .TP .B zip_file Path of zip file to be created .TP .B sources Comma\-separated list of sources to include in the zip file. Sources can also be passed in a Python list. .TP .B template None Can be set to \(aqjinja\(aq or another supported template engine to render the command arguments before execution: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq archive.cmd_zip template=jinja /tmp/zipfile.zip /tmp/sourcefile1,/tmp/{{grains.id}}.txt .ft P .fi .UNINDENT .UNINDENT .TP .B cwd None Use this argument along with relative paths in \fBsources\fP to create zip files which do not contain the leading directories. If not specified, the zip file will be created as if the cwd was \fB/\fP, and creating a zip file of \fB/foo/bar/baz.txt\fP will contain the parent directories \fBfoo\fP and \fBbar\fP\&. To create a zip file containing just \fBbaz.txt\fP, the following command would be used: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq archive.cmd_zip /tmp/baz.zip baz.txt cwd=/foo/bar .ft P .fi .UNINDENT .UNINDENT .sp New in version 2014.7.1. .TP .B runas None Create the zip file as the specified user. Defaults to the user under which the minion is running. .sp New in version 2015.5.0. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq archive.cmd_zip /tmp/zipfile.zip /tmp/sourcefile1,/tmp/sourcefile2 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.archive.gunzip(gzipfile, template=None, runas=None, options=None) Uses the gunzip command to unpack gzip files .INDENT 7.0 .TP .B template None Can be set to \(aqjinja\(aq or another supported template engine to render the command arguments before execution: .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 .TP .B runas None The user with which to run the gzip command line .TP .B options None Pass any additional arguments to gzip .sp New in version 2016.3.4. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C # Create /tmp/sourcefile.txt salt \(aq*\(aq archive.gunzip /tmp/sourcefile.txt.gz salt \(aq*\(aq archive.gunzip /tmp/sourcefile.txt options=\(aq\-\-verbose\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.archive.gzip(sourcefile, template=None, runas=None, options=None) Uses the gzip command to create gzip files .INDENT 7.0 .TP .B template None Can be set to \(aqjinja\(aq or another supported template engine to render the command arguments before execution: .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 .TP .B runas None The user with which to run the gzip command line .TP .B options None Pass any additional arguments to gzip .sp New in version 2016.3.4. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C # Create /tmp/sourcefile.txt.gz salt \(aq*\(aq archive.gzip /tmp/sourcefile.txt salt \(aq*\(aq archive.gzip /tmp/sourcefile.txt options=\(aq\-9 \-\-verbose\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.archive.is_encrypted(name, clean=False, saltenv=\(aqbase\(aq) New in version 2016.11.0. .sp Returns \fBTrue\fP if the zip archive is password\-protected, \fBFalse\fP if not. If the specified file is not a ZIP archive, an error will be raised. .INDENT 7.0 .TP .B name The path / URL of the archive to check. .TP .B clean False Set this value to \fBTrue\fP to delete the path referred to by \fBname\fP once the contents have been listed. This option should be used with care. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 If there is an error listing the archive\(aqs contents, the cached file will not be removed, to allow for troubleshooting. .UNINDENT .UNINDENT .UNINDENT .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq archive.is_encrypted /path/to/myfile.zip salt \(aq*\(aq archive.is_encrypted salt://foo.zip salt \(aq*\(aq archive.is_encrypted salt://foo.zip saltenv=dev salt \(aq*\(aq archive.is_encrypted https://domain.tld/myfile.zip clean=True salt \(aq*\(aq archive.is_encrypted ftp://10.1.2.3/foo.zip .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.archive.list(name, archive_format=None, options=None, strip_components=None, clean=False, verbose=False, saltenv=\(aqbase\(aq) New in version 2016.11.0. .sp Changed in version 2016.11.2: The \fI\%rarfile\fP Python module is now supported for listing the contents of rar archives. This is necessary on minions with older releases of the \fBrar\fP CLI tool, which do not support listing the contents in a parsable format. .sp List the files and directories in an tar, zip, or rar archive. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 This function will only provide results for XZ\-compressed archives if the \fI\%xz\fP CLI command is available, as Python does not at this time natively support XZ compression in its \fI\%tarfile\fP module. Keep in mind however that most Linux distros ship with \fI\%xz\fP already installed. .sp To check if a given minion has \fI\%xz\fP, the following Salt command can be run: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt minion_id cmd.which xz .ft P .fi .UNINDENT .UNINDENT .sp If \fBNone\fP is returned, then \fI\%xz\fP is not present and must be installed. It is widely available and should be packaged as either \fBxz\fP or \fBxz\-utils\fP\&. .UNINDENT .UNINDENT .INDENT 7.0 .TP .B name Path/URL of archive .TP .B archive_format Specify the format of the archive (\fBtar\fP, \fBzip\fP, or \fBrar\fP). If this argument is omitted, the archive format will be guessed based on the value of the \fBname\fP parameter. .TP .B options \fBFor tar archives only.\fP This function will, by default, try to use the \fI\%tarfile\fP module from the Python standard library to get a list of files/directories. If this method fails, then it will fall back to using the shell to decompress the archive to stdout and pipe the results to \fBtar \-tf \-\fP to produce a list of filenames. XZ\-compressed archives are already supported automatically, but in the event that the tar archive uses a different sort of compression not supported natively by \fI\%tarfile\fP, this option can be used to specify a command that will decompress the archive to stdout. For example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt minion_id archive.list /path/to/foo.tar.gz options=\(aqgzip \-\-decompress \-\-stdout\(aq .ft P .fi .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 It is not necessary to manually specify options for gzip\(aqed archives, as gzip compression is natively supported by \fI\%tarfile\fP\&. .UNINDENT .UNINDENT .TP .B strip_components This argument specifies a number of top\-level directories to strip from the results. This is similar to the paths that would be extracted if \fB\-\-strip\-components\fP (or \fB\-\-strip\fP) were used when extracting tar archives. .sp New in version 2016.11.2. .TP .B clean False Set this value to \fBTrue\fP to delete the path referred to by \fBname\fP once the contents have been listed. This option should be used with care. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 If there is an error listing the archive\(aqs contents, the cached file will not be removed, to allow for troubleshooting. .UNINDENT .UNINDENT .TP .B verbose False If \fBFalse\fP, this function will return a list of files/dirs in the archive. If \fBTrue\fP, it will return a dictionary categorizing the paths into separate keys containing the directory names, file names, and also directories/files present in the top level of the archive. .sp Changed in version 2016.11.2: This option now includes symlinks in their own list. Before, they were included with files. .TP .B saltenv base Specifies the fileserver environment from which to retrieve \fBarchive\fP\&. This is only applicable when \fBarchive\fP is a file from the \fBsalt://\fP fileserver. .UNINDENT .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq archive.list /path/to/myfile.tar.gz salt \(aq*\(aq archive.list /path/to/myfile.tar.gz strip_components=1 salt \(aq*\(aq archive.list salt://foo.tar.gz salt \(aq*\(aq archive.list https://domain.tld/myfile.zip salt \(aq*\(aq archive.list ftp://10.1.2.3/foo.rar .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.archive.rar(rarfile, sources, template=None, cwd=None, runas=None) Uses \fI\%rar for Linux\fP to create rar files .INDENT 7.0 .TP .B rarfile Path of rar file to be created .TP .B sources Comma\-separated list of sources to include in the rar file. Sources can also be passed in a Python list. .TP .B cwd None Run the rar command from the specified directory. Use this argument along with relative file paths to create rar files which do not contain the leading directories. If not specified, this will default to the home directory of the user under which the salt minion process is running. .sp New in version 2014.7.1. .TP .B template None Can be set to \(aqjinja\(aq or another supported template engine to render the command arguments before execution: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq archive.rar template=jinja /tmp/rarfile.rar \(aq/tmp/sourcefile1,/tmp/{{grains.id}}.txt\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .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 .UNINDENT .INDENT 0.0 .TP .B salt.modules.archive.tar(options, tarfile, sources=None, dest=None, cwd=None, template=None, runas=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 tar command .sp Changed in version 2015.8.0: The mandatory \fI\-\fP prefixing has been removed. An options string beginning with a \fI\-\-long\-option\fP, would have uncharacteristically needed its first \fI\-\fP removed under the former scheme. .sp Also, tar will parse its options differently if short options are used with or without a preceding \fI\-\fP, so it is better to not confuse the user into thinking they\(aqre using the non\-\fI\-\fP format, when really they are using the with\-\fI\-\fP format. .TP .B tarfile The filename of the tar archive to pack/unpack .TP .B sources Comma delimited list of files to \fBpack\fP into the tarfile. Can also be passed as a Python list. .TP .B dest The destination directory into which to \fBunpack\fP the tarfile .TP .B cwd None The directory in which the tar command should be executed. If not specified, will default to the home directory of the user under which the salt minion process is running. .TP .B template None Can be set to \(aqjinja\(aq or another supported template engine to render the command arguments before execution: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq archive.tar \-cjvf /tmp/salt.tar.bz2 {{grains.saltpath}} template=jinja .ft P .fi .UNINDENT .UNINDENT .UNINDENT .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C # Create a tarfile salt \(aq*\(aq archive.tar \-cjvf /tmp/tarfile.tar.bz2 /tmp/file_1,/tmp/file_2 # Unpack a tarfile salt \(aq*\(aq archive.tar xf foo.tar dest=/target/directory .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.archive.unrar(rarfile, dest, excludes=None, template=None, runas=None, trim_output=False) Uses \fI\%rar for Linux\fP to unpack rar files .INDENT 7.0 .TP .B rarfile Name of rar file to be unpacked .TP .B dest The destination directory into which to \fBunpack\fP the rar file .TP .B template None Can be set to \(aqjinja\(aq or another supported template engine to render the command arguments before execution: .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 .TP .B trim_output False The number of files we should output on success before the rest are trimmed, if this is set to True then it will default to 100 .UNINDENT .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 .UNINDENT .INDENT 0.0 .TP .B salt.modules.archive.unzip(zip_file, dest, excludes=None, options=None, template=None, runas=None, trim_output=False, password=None, extract_perms=True) Uses the \fBzipfile\fP Python module to unpack zip files .sp Changed in version 2015.5.0: This function was rewritten to use Python\(aqs native zip file support. The old functionality has been preserved in the new function \fI\%archive.cmd_unzip\fP\&. For versions 2014.7.x and earlier, see the \fI\%archive.cmd_zip\fP documentation. .INDENT 7.0 .TP .B zip_file Path of zip file to be unpacked .TP .B dest The destination directory into which the file should be unpacked .TP .B excludes None Comma\-separated list of files not to unpack. Can also be passed in a Python list. .TP .B options This options are only used when \fBunzip\fP binary is used. In this function is ignored. .sp New in version 2016.3.1. .TP .B template None Can be set to \(aqjinja\(aq or another supported template engine to render the command arguments before execution: .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 .TP .B runas None Unpack the zip file as the specified user. Defaults to the user under which the minion is running. .TP .B trim_output False The number of files we should output on success before the rest are trimmed, if this is set to True then it will default to 100 .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 .INDENT 7.0 .TP .B password Password to use with password protected zip files .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 The password will be present in the events logged to the minion log file at the \fBdebug\fP log level. If the minion is logging at \fBdebug\fP (or more verbose), then be advised that the password will appear in the log. .UNINDENT .UNINDENT .sp New in version 2016.3.0. .TP .B extract_perms True The Python \fI\%zipfile\fP module does not extract file/directory attributes by default. When this argument is set to \fBTrue\fP, Salt will attempt to apply the file permision attributes to the extracted files/folders. .sp On Windows, only the read\-only flag will be extracted as set within the zip file, other attributes (i.e. user/group permissions) are ignored. .sp Set this argument to \fBFalse\fP to disable this behavior. .sp New in version 2016.11.0. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq archive.unzip /tmp/zipfile.zip /home/strongbad/ password=\(aqBadPassword\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.archive.zip(zip_file, sources, template=None, cwd=None, runas=None) Uses the \fBzipfile\fP Python module to create zip files .sp Changed in version 2015.5.0: This function was rewritten to use Python\(aqs native zip file support. The old functionality has been preserved in the new function \fI\%archive.cmd_zip\fP\&. For versions 2014.7.x and earlier, see the \fI\%archive.cmd_zip\fP documentation. .INDENT 7.0 .TP .B zip_file Path of zip file to be created .TP .B sources Comma\-separated list of sources to include in the zip file. Sources can also be passed in a Python list. .TP .B template None Can be set to \(aqjinja\(aq or another supported template engine to render the command arguments before execution: .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 .TP .B cwd None Use this argument along with relative paths in \fBsources\fP to create zip files which do not contain the leading directories. If not specified, the zip file will be created as if the cwd was \fB/\fP, and creating a zip file of \fB/foo/bar/baz.txt\fP will contain the parent directories \fBfoo\fP and \fBbar\fP\&. To create a zip file containing just \fBbaz.txt\fP, the following command would be used: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq archive.zip /tmp/baz.zip baz.txt cwd=/foo/bar .ft P .fi .UNINDENT .UNINDENT .TP .B runas None Create the zip file as the specified user. Defaults to the user under which the minion is running. .UNINDENT .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 .UNINDENT .SS salt.modules.artifactory .sp Module for fetching artifacts from Artifactory .INDENT 0.0 .TP .B salt.modules.artifactory.get_latest_release(artifactory_url, repository, group_id, artifact_id, packaging, target_dir=\(aq/tmp\(aq, target_file=None, classifier=None, username=None, password=None) Gets the latest release of the artifact .INDENT 7.0 .TP .B artifactory_url URL of artifactory instance .TP .B repository Release repository in artifactory to retrieve artifact from, for example: libs\-releases .TP .B group_id Group Id of the artifact .TP .B artifact_id Artifact Id of the artifact .TP .B packaging Packaging type (jar,war,ear,etc) .TP .B target_dir Target directory to download artifact to (default: /tmp) .TP .B target_file Target file to download artifact to (by default it is target_dir/artifact_id\-version.packaging) .TP .B classifier Artifact classifier name (ex: sources,javadoc,etc). Optional parameter. .TP .B username Artifactory username. Optional parameter. .TP .B password Artifactory password. Optional parameter. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.artifactory.get_latest_snapshot(artifactory_url, repository, group_id, artifact_id, packaging, target_dir=\(aq/tmp\(aq, target_file=None, classifier=None, username=None, password=None) Gets latest snapshot of the given artifact .INDENT 7.0 .TP .B artifactory_url URL of artifactory instance .TP .B repository Snapshot repository in artifactory to retrieve artifact from, for example: libs\-snapshots .TP .B group_id Group Id of the artifact .TP .B artifact_id Artifact Id of the artifact .TP .B packaging Packaging type (jar,war,ear,etc) .TP .B target_dir Target directory to download artifact to (default: /tmp) .TP .B target_file Target file to download artifact to (by default it is target_dir/artifact_id\-snapshot_version.packaging) .TP .B classifier Artifact classifier name (ex: sources,javadoc,etc). Optional parameter. .TP .B username Artifactory username. Optional parameter. .TP .B password Artifactory password. Optional parameter. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.artifactory.get_release(artifactory_url, repository, group_id, artifact_id, packaging, version, target_dir=\(aq/tmp\(aq, target_file=None, classifier=None, username=None, password=None) Gets the specified release of the artifact .INDENT 7.0 .TP .B artifactory_url URL of artifactory instance .TP .B repository Release repository in artifactory to retrieve artifact from, for example: libs\-releases .TP .B group_id Group Id of the artifact .TP .B artifact_id Artifact Id of the artifact .TP .B packaging Packaging type (jar,war,ear,etc) .TP .B version Version of the artifact .TP .B target_dir Target directory to download artifact to (default: /tmp) .TP .B target_file Target file to download artifact to (by default it is target_dir/artifact_id\-version.packaging) .TP .B classifier Artifact classifier name (ex: sources,javadoc,etc). Optional parameter. .TP .B username Artifactory username. Optional parameter. .TP .B password Artifactory password. Optional parameter. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.artifactory.get_snapshot(artifactory_url, repository, group_id, artifact_id, packaging, version, snapshot_version=None, target_dir=\(aq/tmp\(aq, target_file=None, classifier=None, username=None, password=None) Gets snapshot of the desired version of the artifact .INDENT 7.0 .TP .B artifactory_url URL of artifactory instance .TP .B repository Snapshot repository in artifactory to retrieve artifact from, for example: libs\-snapshots .TP .B group_id Group Id of the artifact .TP .B artifact_id Artifact Id of the artifact .TP .B packaging Packaging type (jar,war,ear,etc) .TP .B version Version of the artifact .TP .B target_dir Target directory to download artifact to (default: /tmp) .TP .B target_file Target file to download artifact to (by default it is target_dir/artifact_id\-snapshot_version.packaging) .TP .B classifier Artifact classifier name (ex: sources,javadoc,etc). Optional parameter. .TP .B username Artifactory username. Optional parameter. .TP .B password Artifactory password. Optional parameter. .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.execute(context=None, lens=None, commands=(), load_path=None) Execute Augeas commands .sp New in version 2014.7.0. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq augeas.execute /files/etc/redis/redis.conf \e commands=\(aq["set bind 0.0.0.0", "set maxmemory 1G"]\(aq .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .TP .B context The Augeas context .TP .B lens The Augeas lens to use .TP .B commands The Augeas commands to execute .UNINDENT .sp New in version 2016.3.0. .INDENT 7.0 .TP .B load_path A colon\-spearated list of directories that modules should be searched in. This is in addition to the standard load path and the directories in AUGEAS_LENS_LIB. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.augeas_cfg.get(path, value=\(aq\(aq, load_path=None) 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 .INDENT 7.0 .TP .B path The path to get the value of .TP .B value The optional value to get .UNINDENT .sp New in version 2016.3.0. .INDENT 7.0 .TP .B load_path A colon\-spearated list of directories that modules should be searched in. This is in addition to the standard load path and the directories in AUGEAS_LENS_LIB. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.augeas_cfg.ls(path, load_path=None) 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 .INDENT 7.0 .TP .B path The path to list .UNINDENT .sp New in version 2016.3.0. .INDENT 7.0 .TP .B load_path A colon\-spearated list of directories that modules should be searched in. This is in addition to the standard load path and the directories in AUGEAS_LENS_LIB. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.augeas_cfg.match(path, value=\(aq\(aq, load_path=None) 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 .INDENT 7.0 .TP .B path The path to match .TP .B value The value to match on .UNINDENT .sp New in version 2016.3.0. .INDENT 7.0 .TP .B load_path A colon\-spearated list of directories that modules should be searched in. This is in addition to the standard load path and the directories in AUGEAS_LENS_LIB. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.augeas_cfg.remove(path, load_path=None) Get matches for path expression .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq augeas.remove \e /files/etc/sysctl.conf/net.ipv4.conf.all.log_martians .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .TP .B path The path to remove .UNINDENT .sp New in version 2016.3.0. .INDENT 7.0 .TP .B load_path A colon\-spearated list of directories that modules should be searched in. This is in addition to the standard load path and the directories in AUGEAS_LENS_LIB. .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, load_path=None) 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 .INDENT 7.0 .TP .B path The base of the recursive listing .UNINDENT .sp New in version 2016.3.0. .INDENT 7.0 .TP .B load_path A colon\-spearated list of directories that modules should be searched in. This is in addition to the standard load path and the directories in AUGEAS_LENS_LIB. .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 .sp CLI Example: .INDENT 7.0 .INDENT 3.5 salt \(aq*\(aq aws_sqs.create_queue .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.aws_sqs.delete_message(queue, region, receipthandle, opts=None, user=None) Delete one or more messages from a queue in a region .INDENT 7.0 .TP .B queue The name of the queue to delete messages from .TP .B region Region where SQS queues exists .TP .B receipthandle The ReceiptHandle of the message to delete. The ReceiptHandle is obtained in the return from receive_message .TP .B opts None Any additional options to add to the command line .TP .B user None Run as a user other than what the minion runs as .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq aws_sqs.delete_message receipthandle=\(aq\(aq .ft P .fi .UNINDENT .UNINDENT .sp New in version 2014.7.0. .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 .sp CLI Example: .INDENT 7.0 .INDENT 3.5 salt \(aq*\(aq aws_sqs.delete_queue .UNINDENT .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 .sp CLI Example: .INDENT 7.0 .INDENT 3.5 salt \(aq*\(aq aws_sqs.list_queues .UNINDENT .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 .sp CLI Example: .INDENT 7.0 .INDENT 3.5 salt \(aq*\(aq aws_sqs.queue_exists .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.aws_sqs.receive_message(queue, region, num=1, opts=None, user=None) Receive one or more messages from a queue in a region .INDENT 7.0 .TP .B queue The name of the queue to receive messages from .TP .B region Region where SQS queues exists .TP .B num 1 The max number of messages to receive .TP .B opts None Any additional options to add to the command line .TP .B user None Run as a user other than what the minion runs as .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq aws_sqs.receive_message salt \(aq*\(aq aws_sqs.receive_message num=10 .ft P .fi .UNINDENT .UNINDENT .sp New in version 2014.7.0. .UNINDENT .SS salt.modules.bamboohr .sp Support for BambooHR .sp New in version 2015.8.0. .sp Requires a \fBsubdomain\fP and an \fBapikey\fP in \fB/etc/salt/minion\fP: .INDENT 0.0 .TP .B salt.modules.bamboohr.list_employees(order_by=\(aqid\(aq) Show all employees for this company. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 salt myminion bamboohr.list_employees .UNINDENT .UNINDENT .sp By default, the return data will be keyed by ID. However, it can be ordered by any other field. Keep in mind that if the field that is chosen contains duplicate values (i.e., location is used, for a company which only has one location), then each duplicate value will be overwritten by the previous. Therefore, it is advisable to only sort by fields that are guaranteed to be unique. .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 salt myminion bamboohr.list_employees order_by=id salt myminion bamboohr.list_employees order_by=displayName salt myminion bamboohr.list_employees order_by=workEmail .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.bamboohr.list_meta_fields() Show all meta data fields for this company. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 salt myminion bamboohr.list_meta_fields .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.bamboohr.list_users(order_by=\(aqid\(aq) Show all users for this company. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 salt myminion bamboohr.list_users .UNINDENT .UNINDENT .sp By default, the return data will be keyed by ID. However, it can be ordered by any other field. Keep in mind that if the field that is chosen contains duplicate values (i.e., location is used, for a company which only has one location), then each duplicate value will be overwritten by the previous. Therefore, it is advisable to only sort by fields that are guaranteed to be unique. .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 salt myminion bamboohr.list_users order_by=id salt myminion bamboohr.list_users order_by=email .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.bamboohr.show_employee(emp_id, fields=None) Show all employees for this company. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 salt myminion bamboohr.show_employee 1138 .UNINDENT .UNINDENT .sp By default, the fields normally returned from bamboohr.list_employees are returned. These fields are: .INDENT 7.0 .INDENT 3.5 .INDENT 0.0 .IP \(bu 2 canUploadPhoto .IP \(bu 2 department .IP \(bu 2 displayName .IP \(bu 2 firstName .IP \(bu 2 id .IP \(bu 2 jobTitle .IP \(bu 2 lastName .IP \(bu 2 location .IP \(bu 2 mobilePhone .IP \(bu 2 nickname .IP \(bu 2 photoUploaded .IP \(bu 2 photoUrl .IP \(bu 2 workEmail .IP \(bu 2 workPhone .IP \(bu 2 workPhoneExtension .UNINDENT .UNINDENT .UNINDENT .sp If needed, a different set of fields may be specified, separated by commas: .sp CLI Example: .INDENT 7.0 .INDENT 3.5 salt myminion bamboohr.show_employee 1138 displayName,dateOfBirth .UNINDENT .UNINDENT .sp A list of available fields can be found at \fI\%http://www.bamboohr.com/api/documentation/employees.php\fP .UNINDENT .INDENT 0.0 .TP .B salt.modules.bamboohr.update_employee(emp_id, key=None, value=None, items=None) Update one or more items for this employee. Specifying an empty value will clear it for that employee. .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 salt myminion bamboohr.update_employee 1138 nickname Curly salt myminion bamboohr.update_employee 1138 nickname \(aq\(aq salt myminion bamboohr.update_employee 1138 items=\(aq{"nickname": "Curly"} salt myminion bamboohr.update_employee 1138 items=\(aq{"nickname": ""} .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.bcache module .sp Module for managing BCache sets .sp BCache is a block\-level caching mechanism similar to ZFS L2ARC/ZIL, dm\-cache and fscache. It works by formatting one block device as a cache set, then adding backend devices (which need to be formatted as such) to the set and activating them. .sp It\(aqs available in Linux mainline kernel since 3.10 .sp \fI\%https://www.kernel.org/doc/Documentation/bcache.txt\fP .sp This module needs the bcache userspace tools to function. .INDENT 0.0 .TP .B salt.modules.bcache.attach(dev=None) Attach a backing devices to a cache set If no dev is given, all backing devices will be attached. .sp CLI example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq bcache.attach sdc salt \(aq*\(aq bcache.attach /dev/bcache1 .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .TP .B Returns bool or None if nuttin\(aq happened .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.bcache.back_make(dev, cache_mode=\(aqwriteback\(aq, force=False, attach=True, bucket_size=None) Create a backing device for attachment to a set. Because the block size must be the same, a cache set already needs to exist. .sp CLI example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq bcache.back_make sdc cache_mode=writeback attach=True .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBcache_mode\fP \-\- writethrough, writeback, writearound or none. .IP \(bu 2 \fBforce\fP \-\- Overwrite existing bcaches .IP \(bu 2 \fBattach\fP \-\- Immediately attach the backing device to the set .IP \(bu 2 \fBbucket_size\fP \-\- Size of a bucket (see kernel doc) .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.bcache.cache_make(dev, reserved=None, force=False, block_size=None, bucket_size=None, attach=True) Create BCache cache on a block device. If blkdiscard is available the entire device will be properly cleared in advance. .sp CLI example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq bcache.cache_make sdb reserved=10% block_size=4096 .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBreserved\fP \-\- .sp if dev is a full device, create a partition table with this size empty. .sp \fBNOTE:\fP .INDENT 2.0 .INDENT 3.5 this increases the amount of reserved space available to SSD garbage collectors, potentially (vastly) increasing performance .UNINDENT .UNINDENT .IP \(bu 2 \fBblock_size\fP \-\- Block size of the cache; defaults to devices\(aq logical block size .IP \(bu 2 \fBforce\fP \-\- Overwrite existing BCache sets .IP \(bu 2 \fBattach\fP \-\- Attach all existing backend devices immediately .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.bcache.config(dev=None, **kwargs) Show or update config of a bcache device. .sp If no device is given, operate on the cache set itself. .sp CLI example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq bcache.config salt \(aq*\(aq bcache.config bcache1 salt \(aq*\(aq bcache.config errors=panic journal_delay_ms=150 salt \(aq*\(aq bcache.config bcache1 cache_mode=writeback writeback_percent=15 .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .TP .B Returns config or True/False .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.bcache.detach(dev=None) Detach a backing device(s) from a cache set If no dev is given, all backing devices will be attached. .sp Detaching a backing device will flush it\(aqs write cache. This should leave the underlying device in a consistent state, but might take a while. .sp CLI example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq bcache.detach sdc salt \(aq*\(aq bcache.detach bcache1 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.bcache.device(dev, stats=False, config=False, internals=False, superblock=False) Check the state of a single bcache device .sp CLI example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq bcache.device bcache0 salt \(aq*\(aq bcache.device /dev/sdc stats=True .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBstats\fP \-\- include statistics .IP \(bu 2 \fBsettings\fP \-\- include all settings .IP \(bu 2 \fBinternals\fP \-\- include all internals .IP \(bu 2 \fBsuperblock\fP \-\- include superblock info .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.bcache.start() Trigger a start of the full bcache system through udev. .sp CLI example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq bcache.start .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.bcache.status(stats=False, config=False, internals=False, superblock=False, alldevs=False) Show the full status of the BCache system and optionally all it\(aqs involved devices .sp CLI example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq bcache.status salt \(aq*\(aq bcache.status stats=True salt \(aq*\(aq bcache.status internals=True alldevs=True .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBstats\fP \-\- include statistics .IP \(bu 2 \fBconfig\fP \-\- include settings .IP \(bu 2 \fBinternals\fP \-\- include internals .IP \(bu 2 \fBsuperblock\fP \-\- include superblock .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.bcache.stop(dev=None) Stop a bcache device If no device is given, all backing devices will be detached from the cache, which will subsequently be stopped. .sp \fBWARNING:\fP .INDENT 7.0 .INDENT 3.5 \(aqStop\(aq on an individual backing device means hard\-stop; no attempt at flushing will be done and the bcache device will seemingly \(aqdisappear\(aq from the device lists .UNINDENT .UNINDENT .sp CLI example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq bcache.stop .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.bcache.super(dev) Read out BCache SuperBlock .sp CLI example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq bcache.device bcache0 salt \(aq*\(aq bcache.device /dev/sdc .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.bcache.uuid(dev=None) Return the bcache UUID of a block device. If no device is given, the Cache UUID is returned. .sp CLI example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq bcache.uuid salt \(aq*\(aq bcache.uuid /dev/sda salt \(aq*\(aq bcache.uuid bcache0 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.beacons .sp Module for managing the Salt beacons on a minion .sp New in version 2015.8.0. .INDENT 0.0 .TP .B salt.modules.beacons.add(name, beacon_data, **kwargs) Add a beacon on the minion .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBname\fP \-\- Name of the beacon to configure .IP \(bu 2 \fBbeacon_data\fP \-\- Dictionary or list containing configuration for beacon. .UNINDENT .TP .B Returns Boolean and status message on success or failure of add. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq beacons.add ps "{\(aqsalt\-master\(aq: \(aqstopped\(aq, \(aqapache2\(aq: \(aqstopped\(aq}" .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.beacons.delete(name, **kwargs) Delete a beacon item .INDENT 7.0 .TP .B Parameters \fBname\fP \-\- Name of the beacon to delete .TP .B Returns Boolean and status message on success or failure of delete. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq beacons.delete ps salt \(aq*\(aq beacons.delete load .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.beacons.disable(**kwargs) Disable all beaconsd jobs on the minion .INDENT 7.0 .TP .B Returns Boolean and status message on success or failure of disable. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq beacons.disable .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.beacons.disable_beacon(name, **kwargs) Disable beacon on the minion .INDENT 7.0 .TP .B Name Name of the beacon to disable. .TP .B Returns Boolean and status message on success or failure of disable. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq beacons.disable_beacon ps .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.beacons.enable(**kwargs) Enable all beacons on the minion .INDENT 7.0 .TP .B Returns Boolean and status message on success or failure of enable. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq beacons.enable .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.beacons.enable_beacon(name, **kwargs) Enable beacon on the minion .INDENT 7.0 .TP .B Name Name of the beacon to enable. .TP .B Returns Boolean and status message on success or failure of enable. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq beacons.enable_beacon ps .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.beacons.list(return_yaml=True) List the beacons currently configured on the minion .INDENT 7.0 .TP .B Parameters \fBreturn_yaml\fP \-\- Whether to return YAML formatted output, default True .TP .B Returns List of currently configured Beacons. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq beacons.list .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.beacons.modify(name, beacon_data, **kwargs) Modify an existing beacon .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBname\fP \-\- Name of the beacon to configure .IP \(bu 2 \fBbeacon_data\fP \-\- Dictionary or list containing updated configuration for beacon. .UNINDENT .TP .B Returns Boolean and status message on success or failure of modify. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq beacons.modify ps "{\(aqsalt\-master\(aq: \(aqstopped\(aq, \(aqapache2\(aq: \(aqstopped\(aq}" .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.beacons.save() Save all beacons on the minion .INDENT 7.0 .TP .B Returns Boolean and status message on success or failure of save. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq beacons.save .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.bigip .INDENT 0.0 .TP .B An execution module which can manipulate an f5 bigip via iControl REST .INDENT 7.0 .TP .B maturity develop .TP .B platform f5_bigip_11.6 .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.bigip.add_pool_member(hostname, username, password, name, member) A function to connect to a bigip device and add a new member to an existing pool. .INDENT 7.0 .TP .B hostname The host/address of the bigip device .TP .B username The iControl REST username .TP .B password The iControl REST password .TP .B name The name of the pool to modify .TP .B member The name of the member to add i.e. 10.1.1.2:80 .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq bigip.add_pool_members bigip admin admin my\-pool 10.2.2.1:80 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.bigip.commit_transaction(hostname, username, password, label) A function to connect to a bigip device and commit an existing transaction. .INDENT 7.0 .TP .B hostname The host/address of the bigip device .TP .B username The iControl REST username .TP .B password The iControl REST password .TP .B label the label of this transaction stored within the grain: \fBbigip_f5_trans: