.\" Man page generated from reStructuredText. . .TH "SALT" "7" "Nov 18, 2021" "3002.6" "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 INTRODUCTION TO SALT .sp We’re not just talking about NaCl. .SS The 30 second summary .sp Salt is: .INDENT 0.0 .IP \(bu 2 \fBA configuration management system.\fP Salt is capable of maintaining remote nodes in defined states. For example, it can ensure that specific packages are installed and that specific services are running. .IP \(bu 2 \fBA distributed remote execution system used to execute commands and query data on remote nodes.\fP Salt can query and execute commands either on individual nodes or by using an arbitrary selection criteria. .UNINDENT .sp It was developed in order to bring the best solutions found in the world of remote execution together and make them better, faster, and more malleable. Salt accomplishes this through its ability to handle large loads of information, and not just dozens but hundreds and even thousands of individual servers quickly through a simple and manageable interface. .SS Simplicity .sp Providing versatility between massive scale deployments and smaller systems may seem daunting, but Salt is very simple to set up and maintain, regardless of the size of the project. The architecture of Salt is designed to work with any number of servers, from a handful of local network systems to international deployments across different data centers. The topology is a simple server/client model with the needed functionality built into a single set of daemons. While the default configuration will work with little to no modification, Salt can be fine tuned to meet specific needs. .SS Parallel execution .sp The core functions of Salt: .INDENT 0.0 .IP \(bu 2 enable commands to remote systems to be called in parallel rather than serially .IP \(bu 2 use a secure and encrypted protocol .IP \(bu 2 use the smallest and fastest network payloads possible .IP \(bu 2 provide a simple programming interface .UNINDENT .sp Salt also introduces more granular controls to the realm of remote execution, allowing systems to be targeted not just by hostname, but also by system properties. .SS Builds on proven technology .sp Salt takes advantage of a number of technologies and techniques. The networking layer is built with the excellent \fI\%ZeroMQ\fP networking library, so the Salt daemon includes a viable and transparent AMQ broker. Salt uses public keys for authentication with the master daemon, then uses faster \fI\%AES\fP encryption for payload communication; authentication and encryption are integral to Salt. Salt takes advantage of communication via \fI\%msgpack\fP, enabling fast and light network traffic. .SS Python client interface .sp In order to allow for simple expansion, Salt execution routines can be written as plain Python modules. The data collected from Salt executions can be sent back to the master server, or to any arbitrary program. Salt can be called from a simple Python API, or from the command line, so that Salt can be used to execute one\-off commands as well as operate as an integral part of a larger application. .SS Fast, flexible, scalable .sp The result is a system that can execute commands at high speed on target server groups ranging from one to very many servers. Salt is very fast, easy to set up, amazingly malleable and provides a single remote execution architecture that can manage the diverse requirements of any number of servers. The Salt infrastructure brings together the best of the remote execution world, amplifies its capabilities and expands its range, resulting in a system that is as versatile as it is practical, suitable for any network. .SS Open .sp Salt is developed under the \fI\%Apache 2.0 license\fP, and can be used for open and proprietary projects. Please submit your expansions back to the Salt project so that we can all benefit together as Salt grows. Please feel free to sprinkle Salt around your systems and let the deliciousness come forth. .SS Salt Community .sp Join the Salt! .sp There are many ways to participate in and communicate with the Salt community. .sp Salt has an active IRC channel and a mailing list. .SS Mailing List .sp Join the \fI\%salt\-users mailing list\fP\&. It is the best place to ask questions about Salt and see whats going on with Salt development! The Salt mailing list is hosted by Google Groups. It is open to new members. .sp Additionally, all users of Salt should be subscribed to the Announcements mailing list which contains important updates about Salt, such as new releaes and security\-related announcements. This list is low\-traffic. .SS IRC .sp The \fB#salt\fP IRC channel is hosted on the popular \fI\%Freenode\fP network. You can use the \fI\%Freenode webchat client\fP right from your browser. \fI\%Logs of the IRC channel activity\fP are also available. .sp If you wish to discuss the development of Salt itself join us in \fB#salt\-devel\fP\&. .SS Follow on Github .sp The Salt code is developed via Github. Follow Salt for constant updates on what is happening in Salt development: .sp \fI\%https://github.com/saltstack/salt\fP .sp Long\-term planning and strategic decisions are handled via Salt Enhancement Proposals and can be found on GitHub. .SS Blogs .sp SaltStack Inc. keeps a \fI\%blog\fP with recent news and advancements: .sp \fI\%http://www.saltstack.com/blog/\fP .SS Example Salt States .sp The official \fBsalt\-states\fP repository is: \fI\%https://github.com/SS\-archive/salt\-states\fP .sp A few examples of salt states from the community: .INDENT 0.0 .IP \(bu 2 \fI\%https://github.com/blast\-hardcheese/blast\-salt\-states\fP .IP \(bu 2 \fI\%https://github.com/kevingranade/kevingranade\-salt\-state\fP .IP \(bu 2 \fI\%https://github.com/uggedal/states\fP .IP \(bu 2 \fI\%https://github.com/mattmcclean/salt\-openstack/tree/master/salt\fP .IP \(bu 2 \fI\%https://github.com/rentalita/ubuntu\-setup/\fP .IP \(bu 2 \fI\%https://github.com/brutasse/states\fP .IP \(bu 2 \fI\%https://github.com/bclermont/states\fP .IP \(bu 2 \fI\%https://github.com/pcrews/salt\-data\fP .UNINDENT .SS Follow on Open Hub .sp \fI\%https://www.openhub.net/p/salt\fP .SS Other community links .INDENT 0.0 .IP \(bu 2 \fI\%Salt Stack Inc.\fP .IP \(bu 2 \fI\%Subreddit\fP .IP \(bu 2 \fI\%YouTube\fP .IP \(bu 2 \fI\%Facebook\fP .IP \(bu 2 \fI\%Twitter\fP .IP \(bu 2 \fI\%Wikipedia page\fP .IP \(bu 2 \fI\%Stack Overflow\fP .UNINDENT .SS Hack the Source .sp If you want to get involved with the development of source code or the documentation efforts, please review the contributing documentation! .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 salt version returns from all connected Salt minions. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq test.version .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 Debian release contains old outdated Salt releases. 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 10 (Buster) and Debian 9 (Stretch) 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 Archived builds from unsupported branches: .INDENT 0.0 .IP \(bu 2 \fI\%Archive 1\fP .IP \(bu 2 \fI\%Archive 2\fP .UNINDENT .sp If looking to use archives, the same directions from the \fI\%Debian install directions\fP can be used by replacing the URL paths with the appropriate archive location. The repository configuration endpoint also needs to be adjusted to point to the archives. Here is an example \fBsed\fP command: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C # Salt repo configurations are found in the /etc/apt/sources.list.d/saltstack.list directory sed \-i \(aqs/repo.saltstack.com/archive.repo.saltstack.com/g\(aq /etc/apt/sources.list.d/saltstack.list .ft P .fi .UNINDENT .UNINDENT .UNINDENT .UNINDENT .sp \fBWARNING:\fP .INDENT 0.0 .INDENT 3.5 Regular security support for Debian 8 ended on June 30th 2018. As a result, 3000.3 and 2019.2.5 will be the last Salt releases for which Debian 8 packages are created. Debian 8 also reached LTS EOL on June 30 2020. .sp 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. Debian 7 also reached LTS EOL on May 31 2018. .UNINDENT .UNINDENT .SS Installation from the Debian / Raspbian Official Repository .sp The Debian distributions contain mostly old Salt packages built by the Debian Salt Team. You can install Salt components directly from Debian but it is recommended to use the instructions above for the packages from the official Salt repository. .sp On Jessie 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\-systemd/jessie\-backports 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 Latest Debian Release: .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 Arista EOS Salt minion installation guide .sp The Salt minion for Arista EOS is distributed as a SWIX extension and can be installed directly on the switch. The EOS network operating system is based on old Fedora distributions and the installation of the \fBsalt\-minion\fP requires backports. This SWIX extension contains the necessary backports, together with the Salt basecode. .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 This SWIX extension has been tested on Arista DCS\-7280SE\-68\-R, running EOS 4.17.5M and vEOS 4.18.3F. .UNINDENT .UNINDENT .SS Important Notes .sp This package is in beta, make sure to test it carefully before running it in production. .sp If confirmed working correctly, please report and add a note on this page with the platform model and EOS version. .sp If you want to uninstall this package, please refer to the \fI\%uninstalling\fP section. .SS Installation from the Official SaltStack Repository .sp Download the swix package and save it to flash. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C veos#copy https://salt\-eos.netops.life/salt\-eos\-latest.swix flash: veos#copy https://salt\-eos.netops.life/startup.sh flash: .ft P .fi .UNINDENT .UNINDENT .SS Install the Extension .sp Copy the Salt package to extension .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C veos#copy flash:salt\-eos\-latest.swix extension: .ft P .fi .UNINDENT .UNINDENT .sp Install the SWIX .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C veos#extension salt\-eos\-latest.swix force .ft P .fi .UNINDENT .UNINDENT .sp Verify the installation .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C veos#show extensions | include salt\-eos salt\-eos\-2017\-07\-19.swix 1.0.11/1.fc25 A, F 27 .ft P .fi .UNINDENT .UNINDENT .sp Change the Salt master IP address or FQDN, by edit the variable (SALT_MASTER) .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C veos#bash vi /mnt/flash/startup.sh .ft P .fi .UNINDENT .UNINDENT .sp Make sure you enable the eAPI with unix\-socket .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C veos(config)#management api http\-commands protocol unix\-socket no shutdown .ft P .fi .UNINDENT .UNINDENT .SS Post\-installation tasks .sp Generate Keys and host record and start Salt minion .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C veos#bash #sudo /mnt/flash/startup.sh .ft P .fi .UNINDENT .UNINDENT .sp \fBsalt\-minion\fP should be running .sp Copy the installed extensions to boot\-extensions .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C veos#copy installed\-extensions boot\-extensions .ft P .fi .UNINDENT .UNINDENT .sp Apply event\-handler to let EOS start salt\-minion during boot\-up .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C veos(config)#event\-handler boot\-up\-script trigger on\-boot action bash sudo /mnt/flash/startup.sh .ft P .fi .UNINDENT .UNINDENT .sp For more specific installation details of the \fBsalt\-minion\fP, please refer to Configuring Salt\&. .SS Uninstalling .sp If you decide to uninstall this package, the following steps are recommended for safety: .INDENT 0.0 .IP 1. 3 Remove the extension from boot\-extensions .UNINDENT .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C veos#bash rm /mnt/flash/boot\-extensions .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .IP 2. 3 Remove the extension from extensions folder .UNINDENT .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C veos#bash rm /mnt/flash/.extensions/salt\-eos\-latest.swix .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .IP 2. 3 Remove boot\-up script .UNINDENT .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C veos(config)#no event\-handler boot\-up\-script .ft P .fi .UNINDENT .UNINDENT .SS Additional Information .sp This SWIX extension contains the following RPM packages: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C libsodium\-1.0.11\-1.fc25.i686.rpm libstdc++\-6.2.1\-2.fc25.i686.rpm openpgm\-5.2.122\-6.fc24.i686.rpm python\-Jinja2\-2.8\-0.i686.rpm python\-PyYAML\-3.12\-0.i686.rpm python\-babel\-0.9.6\-5.fc18.noarch.rpm python\-backports\-1.0\-3.fc18.i686.rpm python\-backports\-ssl_match_hostname\-3.4.0.2\-1.fc18.noarch.rpm python\-backports_abc\-0.5\-0.i686.rpm python\-certifi\-2016.9.26\-0.i686.rpm python\-chardet\-2.0.1\-5.fc18.noarch.rpm python\-crypto\-1.4.1\-1.noarch.rpm python\-crypto\-2.6.1\-1.fc18.i686.rpm python\-futures\-3.1.1\-1.noarch.rpm python\-jtextfsm\-0.3.1\-0.noarch.rpm python\-kitchen\-1.1.1\-2.fc18.noarch.rpm python\-markupsafe\-0.18\-1.fc18.i686.rpm python\-msgpack\-python\-0.4.8\-0.i686.rpm python\-napalm\-base\-0.24.3\-1.noarch.rpm python\-napalm\-eos\-0.6.0\-1.noarch.rpm python\-netaddr\-0.7.18\-0.noarch.rpm python\-pyeapi\-0.7.0\-0.noarch.rpm python\-salt\-2017.7.0_1414_g2fb986f\-1.noarch.rpm python\-singledispatch\-3.4.0.3\-0.i686.rpm python\-six\-1.10.0\-0.i686.rpm python\-tornado\-4.4.2\-0.i686.rpm python\-urllib3\-1.5\-7.fc18.noarch.rpm python2\-zmq\-15.3.0\-2.fc25.i686.rpm zeromq\-4.1.4\-5.fc25.i686.rpm .ft P .fi .UNINDENT .UNINDENT .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 the FreeBSD ports tree at \fI\%sysutils/py\-salt\fP\&. .SS FreeBSD binary repo .sp Install Salt on FreeBSD via the official package repository. Salt is packaged both as a Python 2.7 or 3.7 version. .sp For Python 2.7 use: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C pkg install py27\-salt .ft P .fi .UNINDENT .UNINDENT .sp For Python 3.7 use: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C pkg install py37\-salt .ft P .fi .UNINDENT .UNINDENT .SS FreeBSD ports .sp Installation from ports: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C cd /usr/ports/sysutils/py\-salt make install .ft P .fi .UNINDENT .UNINDENT .sp Python 3.7 can be used by setting default Python version to 3.7: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C echo "DEFAULT_VERSIONS+= python=3.7" >> /etc/make.conf .ft P .fi .UNINDENT .UNINDENT .SS Post\-installation tasks .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 \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 Cisco Nexus Salt Minion Installation and Configuration Guide .sp This document describes the Salt Minion installation and configuration on Cisco Nexus switches. These instructions detail the process for managing the Nexus switches using a Proxy Minion or Native Minion on platforms that have GuestShell support. .SS Table of Contents .INDENT 0.0 .IP \(bu 2 \fI\%Cisco Nexus Salt Minion Installation and Configuration Guide\fP .INDENT 2.0 .IP \(bu 2 \fI\%Pre\-Install Tasks\fP .INDENT 2.0 .IP \(bu 2 \fI\%STEP 1: Verify Platform and Software Version Support\fP .IP \(bu 2 \fI\%STEP 2: Choose Salt Minion Type\fP .IP \(bu 2 \fI\%STEP 3: Network Connectivity\fP .UNINDENT .IP \(bu 2 \fI\%Salt Proxy Minion Configuration\fP .INDENT 2.0 .IP \(bu 2 \fI\%Proxy Minion Pillar Data\fP .UNINDENT .IP \(bu 2 \fI\%GuestShell Salt Minion Installation\fP .INDENT 2.0 .IP \(bu 2 \fI\%STEP 1a: Enable the Guestshell on low footprint N3ks\fP .IP \(bu 2 \fI\%STEP 1b: Enable the Guestshell\fP .IP \(bu 2 \fI\%STEP 2: Set Up Guestshell Network\fP .IP \(bu 2 \fI\%STEP 3: Install SaltStack Minion\fP .IP \(bu 2 \fI\%STEP 4: Configure SaltStack Minion\fP .UNINDENT .IP \(bu 2 \fI\%GuestShell Salt Minion Persistence\fP .IP \(bu 2 \fI\%References\fP .UNINDENT .UNINDENT .SS Pre\-Install Tasks .SS STEP 1: Verify Platform and Software Version Support .sp The following platforms and software versions have been certified to work with this version of Salt. .INDENT 0.0 .INDENT 3.5 .SS Platform / Software Minimum Requirements .TS center; |l|l|l|l|l|. _ T{ Supported Platforms T} T{ Minimum NX\-OS Version T} T{ SSH Proxy Minion T} T{ NX\-API Proxy Minion T} T{ GuestShell Minion T} _ T{ Cisco Nexus N3k T} T{ 7.0(3)I2(5) and later T} T{ Supported T} T{ Supported T} T{ Supported T} _ T{ Cisco Nexus N9k T} T{ 7.0(3)I2(5) and later T} T{ Supported T} T{ Supported T} T{ Supported T} _ T{ Cisco Nexus N6k T} T{ 7.3(0)N1(1) and later T} T{ Supported T} T{ Not Supported T} T{ Not Supported T} _ T{ Cisco Nexus N7k T} T{ 7.3(0)D1(1) and later T} T{ Supported T} T{ Supported T} T{ Not Supported T} _ .TE .SS Platform Models .TS center; |l|l|. _ T{ Platform T} T{ Description T} _ T{ N3k T} T{ Support includes N30xx, N31xx, N32xx and N35xx models T} _ T{ N6k T} T{ Support includes all N6xxx models T} _ T{ N7k T} T{ Support includes all N7xxx models T} _ T{ N9k T} T{ Support includes all N9xxx models T} _ .TE .UNINDENT .UNINDENT .SS STEP 2: Choose Salt Minion Type .sp Using the tables above, select the Salt Minion type. .INDENT 0.0 .TP .B Choices: .INDENT 7.0 .IP \(bu 2 \fBSSH\fP Proxy Minion (See \fI\%Salt Proxy Minion Configuration\fP Section) .IP \(bu 2 \fBNX\-API\fP Proxy Minion (See \fI\%Salt Proxy Minion Configuration\fP Section) .IP \(bu 2 .INDENT 2.0 .TP .B \fBGuestShell\fP Native Minion (See \fI\%GuestShell Salt Minion Installation\fP Section) .INDENT 7.0 .IP \(bu 2 Some platforms support a native minion installed directly on the NX\-OS device inside the GuestShell .IP \(bu 2 The GuestShell is a secure Linux container environment running CentOS .UNINDENT .UNINDENT .UNINDENT .UNINDENT .SS STEP 3: Network Connectivity .sp Ensure that IP reachability exists between the NX\-OS Salt Minion device and the SaltStack Master. .sp \fBNote:\fP The management interface exists in a separate VRF context and requires additional configuration as shown. .sp Example: Nexus CLI Configuration for connectivity via management interface .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C config term vrf context management ip name\-server 10.0.0.202 ip domain\-name mycompany.com ip route 0.0.0.0/0 10.0.0.1 interface mgmt0 vrf member management ip address 10.0.0.99/24 ntp server 10.0.0.201 use\-vrf management end .ft P .fi .UNINDENT .UNINDENT .SS Salt Proxy Minion Configuration .sp Here is a sample Proxy Minion directory structure .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C saltmaster:/srv/pillar$tree \&. ├── n3k\-proxy.sls ├── n7k\-proxy.sls └── top.sls .ft P .fi .UNINDENT .UNINDENT .sp This displays a top sls file and two proxy minion sls files for a Nexus 3k and Nexus 7k device. .sp Sample contents for the \fBtop.sls\fP file. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C saltmaster:/srv/pillar$cat top.sls base: n3k\-proxy: \- n3k\-proxy n7k\-proxy: \- n7k\-proxy .ft P .fi .UNINDENT .UNINDENT .SS Proxy Minion Pillar Data .sp Here is a sample Proxy Minion pillar data file. .sp All of the data for both ssh and nxapi proxy minion types can be stored in the same pillar data file. To choose \fBssh\fP or \fBnxapi\fP, simply set the \fBconnection:\fP parameter accordingly. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C saltmaster:/srv/pillar$cat n7k\-proxy.sls proxy: proxytype: nxos # Specify ssh or nxapi connection type (default is ssh) #connection: ssh connection: nxapi # Parameters Common to both SSH and NX\-API host: n7k.example.com username: admin password: password # SSH Parameters prompt_name: n7k ssh_args: \(aq\-o PubkeyAuthentication=no\(aq key_accept: True # NX\-API Parameters transport: https port: 443 verify: False # Option to prevent auto\-save after each configuration command. # Setting this to True will improve performance when using # nxos execution module functions to configure the device. no_save_config: True .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .IP \(bu 2 For the most current nxos proxy minion configuration options, See \fBsalt.proxy.nxos\fP .IP \(bu 2 For the most current list of nxos execution module functions, See \fBsalt.modules.nxos\fP .UNINDENT .SS GuestShell Salt Minion Installation .sp This section is only required when running the SaltStack Minion from the \fBguestshell\fP\&. .SS STEP 1a: Enable the Guestshell on low footprint N3ks .sp \fBNOTE:\fP Skip down to \fBSTEP 1b\fP if the target system is not a low footprint N3k. .sp Nexus 3xxx switches with 4 GB RAM and 1.6 GB bootflash are advised to use compacted images to reduce the storage resources consumed by the image. As part of the compaction process, the \fBguestshell.ova\fP is removed from the system image. To make use of the guestshell on these systems, the guestshell.ova may be downloaded and used to install the guestshell. .sp Guestshell OVA Download \fI\%Link\fP .sp Starting in release \fB9.2(1)\fP and onward, the .ova file can be copied to the \fBvolatile:\fP directory which frees up more space on \fBbootflash:\fP\&. .sp Copy the \fBguestshell.ova\fP file to \fBvolatile:\fP if supported, otherwise copy it to \fBbootflash:\fP .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C n3xxx# copy scp://admin@1.2.3.4/guestshell.ova volatile: vrf management guestshell.ova 100% 55MB 10.9MB/s 00:05 Copy complete, now saving to disk (please wait)... Copy complete. .ft P .fi .UNINDENT .UNINDENT .sp Use the \fBguestshell enable\fP command to install and enable guestshell. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C n3xxx# guestshell enable package volatile:guestshell.ova .ft P .fi .UNINDENT .UNINDENT .SS STEP 1b: Enable the Guestshell .sp The \fBguestshell\fP container environment is enabled by default on most platforms; however, the default disk and memory resources allotted to guestshell are typically too small to support SaltStack Minion requirements. The resource limits may be increased with the NX\-OS CLI \fBguestshell resize\fP commands as shown below. .INDENT 0.0 .INDENT 3.5 .SS Resource Requirements .TS center; |l|l|. _ T{ Resource T} T{ Recommended T} _ T{ Disk T} T{ \fB500 MB\fP T} _ T{ Memory T} T{ \fB350 MB\fP T} _ .TE .UNINDENT .UNINDENT .sp \fBshow guestshell detail\fP displays the current resource limits: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C n3k# show guestshell detail Virtual service guestshell+ detail State : Activated \&... Resource reservation Disk : 150 MB Memory : 128 MB .ft P .fi .UNINDENT .UNINDENT .sp \fBguestshell resize rootfs\fP sets disk size limits while \fBguestshell resize memory\fP sets memory limits. The resize commands do not take effect until after the guestshell container is (re)started by \fBguestshell reboot\fP or \fBguestshell enable\fP\&. .sp \fBExample.\fP Allocate resources for guestshell by setting new limits to 500MB disk and 350MB memory. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C n3k# guestshell resize rootfs 500 n3k# guestshell resize memory 350 n3k# guestshell reboot Are you sure you want to reboot the guest shell? (y/n) [n] y .ft P .fi .UNINDENT .UNINDENT .SS STEP 2: Set Up Guestshell Network .sp The \fBguestshell\fP is an independent CentOS container that does not inherit settings from NX\-OS. .INDENT 0.0 .IP \(bu 2 Use \fBguestshell\fP to enter the guestshell environment, then become root. .IP \(bu 2 \fIOptional:\fP Use \fBchvrf\fP to specify a vrf namespace; e.g. \fBsudo chvrf management\fP .UNINDENT .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C n3k# guestshell [guestshell@guestshell ~]$ sudo su \- # Optional: sudo chvrf management [root@guestshell guestshell]# .ft P .fi .UNINDENT .UNINDENT .sp \fBOPTIONAL: Add DNS Configuration\fP .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C [root@guestshell guestshell]# cat >> /etc/resolv.conf << EOF nameserver 10.0.0.202 domain mycompany.com EOF .ft P .fi .UNINDENT .UNINDENT .sp \fBOPTIONAL: Define proxy server variables if needed to allow network access to SaltStack package repositories\fP .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C export http_proxy=http://proxy.yourdomain.com: export https_proxy=https://proxy.yourdomain.com: .ft P .fi .UNINDENT .UNINDENT .SS STEP 3: Install SaltStack Minion .sp \fBOPTIONAL: Upgrade the pip installer\fP .INDENT 0.0 .INDENT 3.5 \fB[root@guestshell guestshell]# pip install \-\-upgrade pip\fP .UNINDENT .UNINDENT .sp Install the \fBcertifi\fP python package. .INDENT 0.0 .INDENT 3.5 \fB[root@guestshell guestshell]# pip install certifi\fP .UNINDENT .UNINDENT .sp The most current information on installing the SaltStack Minion in a Centos7 environment can be found \fI\%here\fP .sp Information from the install guide is provided here for convenience. .sp Run the following commands to install the SaltStack repository and key: .INDENT 0.0 .INDENT 3.5 \fB[root@guestshell guestshell]# yum install https://repo.saltstack.com/yum/redhat/salt\-repo\-latest\-2.el7.noarch.rpm\fP .UNINDENT .UNINDENT .sp Run the following command to force yum to revalidate the cache for each repository. .INDENT 0.0 .INDENT 3.5 \fB[root@guestshell guestshell]# yum clean expire\-cache\fP .UNINDENT .UNINDENT .sp Install the Salt Minion. .INDENT 0.0 .INDENT 3.5 \fB[root@guestshell guestshell]# yum install salt\-minion\fP .UNINDENT .UNINDENT .SS STEP 4: Configure SaltStack Minion .sp Make the following changes to the \fB/etc/salt/minion\fP configuration file in the NX\-OS GuestShell. .sp Change the \fBmaster:\fP directive to point to the SaltStack Master. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C \- #master: salt + master: saltmaster.example.com .ft P .fi .UNINDENT .UNINDENT .sp Change the \fBid:\fP directive to easily identify the minion running in the GuestShell. .sp Example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C \- #id: salt + id: n3k\-guestshell\-minion .ft P .fi .UNINDENT .UNINDENT .sp Start the Minion in the Guestshell and accept the key on the SaltStack Master. .INDENT 0.0 .INDENT 3.5 \fB[root@guestshell ~]# systemctl start salt\-minion\fP .UNINDENT .UNINDENT .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C saltmaster: salt\-key \-L Accepted Keys: Denied Keys: Unaccepted Keys: n3k\-guestshell\-minion Rejected Keys: .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C saltmaster: salt\-key \-A The following keys are going to be accepted: Unaccepted Keys: n3k\-guestshell\-minion Proceed? [n/Y] Y Key for minion n3k\-guestshell\-minion accepted. .ft P .fi .UNINDENT .UNINDENT .sp Ping the SaltStack Minion running in the Guestshell. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C saltmaster: salt n3k\-guestshell\-minion nxos.ping n3k\-guestshell\-minion: True .ft P .fi .UNINDENT .UNINDENT .SS GuestShell Salt Minion Persistence .sp This section documents SaltStack Minion persistence in the \fBguestshell\fP after system restarts and high availability switchovers. .sp The \fBguestshell\fP container does not automatically sync filesystem changes from the active processor to the standby processor. This means that SaltStack Minion installation files and related file changes will not be present on the standby until they are manually synced with the following NX\-OS exec command: .sp \fBguestshell sync\fP .sp The \fBguestshell\fP environment uses \fBsystemd\fP for service management. The SaltStack Minion provides a generic systemd script when installed, but a slight modification as shown below is needed for nodes that run Salt in the management (or other vrf) namespace: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C \-\-\- /usr/lib/systemd/system/salt\-minion.service.old +++ /usr/lib/systemd/system/salt\-minion.service [Unit] Description=The Salt Minion Documentation=man:salt\-minion(1) file:///usr/share/doc/salt/html/contents.html https://docs.saltstack.com/en/latest/contents.html After=network.target salt\-master.service [Service] KillMode=process Type=notify NotifyAccess=all LimitNOFILE=8192 \- ExecStart=/usr/bin/salt\-minion + ExecStart=/bin/nsenter \-\-net=/var/run/netns/management \-\- /usr/bin/salt\-minion [Install] WantedBy=multi\-user.target .ft P .fi .UNINDENT .UNINDENT .sp Change the \fBpidfile:\fP directive to point to the \fB/run\fP \fBtmpfs\fP location in the GuestShell. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C \- #pidfile: /var/run/salt\-minion.pid + pidfile: /run/salt\-minion.pid .ft P .fi .UNINDENT .UNINDENT .sp Next, enable the SaltStack Minion systemd service (the \fBenable\fP command adds it to systemd for autostarting on the next boot) and optionally start it now: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C systemctl enable salt\-minion systemctl start salt\-minion .ft P .fi .UNINDENT .UNINDENT .SS References .INDENT 0.0 .INDENT 3.5 .SS Nexus Document References .TS center; |l|l|. _ T{ References T} T{ Description T} _ T{ \fI\%GuestShell_N9k\fP T} T{ N9k Guestshell Programmability Guide T} _ T{ \fI\%GuestShell_N3k\fP T} T{ N3k Guestshell Programmability Guide T} _ .TE .UNINDENT .UNINDENT .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/py3\-progressbar net/py3\-msgpack net/py3\-zmq security/py3\-Cryptodome security/py3\-M2Crypto sysutils/py3\-distro textproc/py3\-MarkupSafe textproc/py3\-yaml www/py3\-jinja2 www/py3\-requests .ft P .fi .UNINDENT .UNINDENT .SS Installation .sp To install Salt from the OpenBSD package 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 \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 .INDENT 0.0 .IP \(bu 2 \fI\%Earlier builds from supported branches\fP .IP \(bu 2 \fI\%Archived builds from unsupported branches\fP .UNINDENT .UNINDENT .UNINDENT .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 .sp Macports isolates its dependencies from the OS, and installs salt in /opt/local by default, with config files under /opt/local/etc/salt. For best results, add /opt/local/bin to your PATH. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C sudo port install salt .ft P .fi .UNINDENT .UNINDENT .sp Variants allow selection of python version used to run salt, defaulting to python27, but also supporting python34, python35, and python36. To install salt with Python 3.6, use the python36 variant, for example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C sudo port install salt @python36 .ft P .fi .UNINDENT .UNINDENT .sp Startup items (for master, minion, and rest\-cherrypy API gateway, respectively) are installed by subport targets. These will register launchd LaunchDaemons as org.macports.salt\-minion, for example, to trigger automatic startup of the salt\-minion through launchd. LaunchDaemons for salt can be started and stopped without reboot using the macprots load and unload commands. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C sudo port install salt\-master salt\-minion salt\-api sudo port load salt\-master salt\-minion salt\-api .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 Archived builds from unsupported branches: .sp \fBRed Hat / CentOS\fP .INDENT 0.0 .IP \(bu 2 \fI\%Archive 1\fP .IP \(bu 2 \fI\%Archive 2\fP .UNINDENT .sp If looking to use archives, the same directions from the \fI\%RHEL/CentOS install directions\fP can be used by replacing the URL paths with the appropriate archive location. The repository configuration endpoint also needs to be adjusted to point to the archives. Here is an example \fBsed\fP command: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C # Salt repo configurations are found in the /etc/yum.repos.d/ directory sed \-i \(aqs/repo.saltstack.com/archive.repo.saltstack.com/g\(aq /etc/yum.repos.d/salt*.repo .ft P .fi .UNINDENT .UNINDENT .sp \fBAmazon Linux\fP .INDENT 0.0 .IP \(bu 2 \fI\%Archive 1\fP .IP \(bu 2 \fI\%Archive 2\fP .UNINDENT .sp If looking to use archives, the same directions from the \fI\%Amazon install directions\fP can be used by replacing the URL paths with the appropriate archive location. The repository configuration endpoint also needs to be adjusted to point to the archives. Here is an example \fBsed\fP command: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C # Salt repo configurations are found in the /etc/yum.repos.d/ directory sed \-i \(aqs/repo.saltstack.com/archive.repo.saltstack.com/g\(aq /etc/yum.repos.d/salt*.repo .ft P .fi .UNINDENT .UNINDENT .UNINDENT .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\&. .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 Packages in this repository are built by community, and it can take a little while until the latest stable SaltStack release becomes available. Using the SaltStack Repository is highly preferred, instead. .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 \fBpyzmq\fP 14.5.0 in the \fI\%SaltStack Repository\fP\&. .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. .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 is known to work on Solaris but community packages are unmaintained. .sp It is possible to install Salt on Solaris by using \fIsetuptools\fP\&. .sp For example, to install the develop version of salt: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C git clone https://github.com/saltstack/salt cd salt sudo python setup.py install \-\-force .ft P .fi .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 SaltStack does offer commercial support for Solaris which includes packages. Packages can be found on the \fI\%Downloads page of the Enterprise Installation Guide\fP and are downloadable with a \fISaltStack Enterprise\fP account. .UNINDENT .UNINDENT .SS Ubuntu .SS Installation from the Official SaltStack Repository .sp Packages for Ubuntu 20.04 (Focal), Ubuntu 18.04 (Bionic), and Ubuntu 16 (Xenial) are available in the SaltStack repository. .sp Instructions are at \fI\%https://repo.saltstack.com/#ubuntu\fP\&. .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 Archived builds from unsupported branches: .INDENT 0.0 .IP \(bu 2 \fI\%Archive 1\fP .IP \(bu 2 \fI\%Archive 2\fP .UNINDENT .sp If looking to use archives, the same directions from the \fI\%Ubuntu install directions\fP can be used by replacing the URL paths with the appropriate archive location. The repository configuration endpoint also needs to be adjusted to point to the archives. Here is an example \fBsed\fP command: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C # Salt repo configurations are found in the /etc/apt/sources.list.d/saltstack.list directory sed \-i \(aqs/repo.saltstack.com/archive.repo.saltstack.com/g\(aq /etc/apt/sources.list.d/saltstack.list .ft P .fi .UNINDENT .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 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 There are installers available for Python 3. Starting with Salt 3001, only Python 3 builds of the Windows Salt Minion will be built. Python 2 builds exist for earlier Salt Minion versions. .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 .INDENT 0.0 .IP \(bu 2 \fI\%Earlier builds from supported branches\fP .UNINDENT .sp Archived builds from unsupported branches: .INDENT 0.0 .IP \(bu 2 \fI\%Archive 1\fP .IP \(bu 2 \fI\%Archive 2\fP .UNINDENT .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 The installation executable installs dependencies that the Salt minion requires. .UNINDENT .UNINDENT .sp The 64bit and 32bit installers have been tested on Windows 8.1, Windows Server 2012 R2, Windows 10, Windows Server 2016, and Windows Server 2019. 32bit installers have only been tested on 64bit systems. 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. .SS Salt Minion Installation .sp If the system is missing the appropriate version of the Visual C++ Redistributable (vcredist) the user will be prompted to install it. Click \fBOK\fP to install the vcredist. Click \fBCancel\fP to abort the installation without making modifications to the system. .sp If Salt is already installed on the system the user will be prompted to remove the previous installation. Click \fBOK\fP to uninstall Salt without removing the configuration, PKI information, or cached files. Click \fBCancel\fP to abort the installation before making any modifications to the system. .sp After the Welcome and the License Agreement, the installer asks for two 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 If the installer finds an existing minion config file, these fields will be populated with values from the existing config, but they will be grayed out. There will also be a checkbox to use the existing config. If you continue, the existing config will be used. If the checkbox is unchecked, default values are displayed and can be changed. If you continue, the existing config file in \fBc:\esalt\econf\fP will be removed along with the \fBc:\esalt\econf\eminion.d\fP directory. The values entered will be used with the default config. .sp The final page allows you to start the minion service and optionally change its startup type. By default, the minion is set to \fBAutomatic\fP\&. You can change the minion start type to \fBAutomatic (Delayed Start)\fP by checking the \(aqDelayed Start\(aq checkbox. .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 Highstates that require a reboot may fail after reboot because salt continues the highstate before Windows has finished the booting process. This can be fixed by changing the startup type to \(aqAutomatic (Delayed Start)\(aq. The drawback is that it may increase the time it takes for the \(aqsalt\-minion\(aq service to actually start. .UNINDENT .UNINDENT .sp The \fBsalt\-minion\fP service will appear in the Windows Service Manager and can be managed there or from the command line 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 .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: .TS center; |l|l|. _ T{ Option T} T{ Description T} _ T{ \fB/master=\fP T} T{ A string value to set the IP address or hostname of the master. Default value is \(aqsalt\(aq. You can pass a single master or a comma\-separated list of masters. Setting the master will cause the installer to use the default config or a custom config if defined. T} _ T{ \fB/minion\-name=\fP T} T{ A string value to set the minion name. Default value is \(aqhostname\(aq. Setting the minion name causes the installer to use the default config or a custom config if defined. T} _ T{ \fB/start\-minion=\fP T} T{ 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. T} _ T{ \fB/start\-minion\-delayed\fP T} T{ Set the minion start type to \fBAutomatic (Delayed Start)\fP\&. T} _ T{ \fB/default\-config\fP T} T{ Overwrite the existing config if present with the default config for salt. Default is to use the existing config if present. If \fB/master\fP and/or \fB/minion\-name\fP is passed, those values will be used to update the new default config. T} _ T{ \fB/custom\-config=\fP T} T{ A string value specifying the name of a custom config file in the same path as the installer or the full path to a custom config file. If \fB/master\fP and/or \fB/minion\-name\fP is passed, those values will be used to update the new custom config. T} _ T{ \fB/S\fP T} T{ Runs the installation silently. Uses the above settings or the defaults. T} _ T{ \fB/?\fP T} T{ Displays command line help. T} _ .TE .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 \fB/start\-service\fP has been deprecated but will continue to function as expected for the time being. .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 \fB/default\-config\fP and \fB/custom\-config=\fP will backup an existing config if found. A timestamp and a \fB\&.bak\fP extension will be added. That includes the \fBminion\fP file and the \fBminion.d\fP directory. .UNINDENT .UNINDENT .sp Here are some examples of using the silent installer: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C # Install the Salt Minion # Configure the minion and start the service Salt\-Minion\-3001\-Py3\-AMD64\-Setup.exe /S /master=yoursaltmaster /minion\-name=yourminionname .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C # Install the Salt Minion # Configure the minion but don\(aqt start the minion service Salt\-Minion\-3001\-Py3\-AMD64\-Setup.exe /S /master=yoursaltmaster /minion\-name=yourminionname /start\-minion=0 .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C # Install the Salt Minion # Configure the minion using a custom config and configuring multimaster Salt\-Minion\-3001\-Py3\-AMD64\-Setup.exe /S /custom\-config=windows_minion /master=prod_master1,prod_master2 .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_2.ps1\fP T} T{ A PowerShell script that sets up a Python 2 build environment T} _ T{ \fBbuild_env_3.ps1\fP T} T{ A PowerShell script that sets up a Python 3 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 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. .sp Both scripts also accept an additional parameter to specify the version of Python to use. The default is 2. .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 2017.7.2 .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_2.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_2.ps1\fP powershell script and selecting \fBRun with PowerShell\fP .UNINDENT .UNINDENT .sp This will download and install Python 2 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 .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 If \fBpip\fP is still not recognized make sure that the Python Scripts folder is in the System \fB%PATH%\fP\&. (\fBC:\ePython2\eScripts\fP) .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 minion config file named \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 (2017.7.2) and the Python version as parameters. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C cd pkg\ewindows build_pkg.bat 2017.7.2 2 ^^^^^^^^ ^ | | # build version \-\- | # python version \-\-\-\-\-\- .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. If the python version is not passed, the default is 2. .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 2017.7.2 .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 2017.7.2 3 ^^^^^^^^ ^ | | # build version | # python version \-\- .ft P .fi .UNINDENT .UNINDENT .sp This will install everything needed to build a Windows installer for Salt using Python 3. 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.version .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 The SaltStack Repository has packages available for the following platforms: .INDENT 0.0 .IP \(bu 2 SLES 11 SP4 .IP \(bu 2 SLES 12 / SLES 12 SP1 through SP4 .IP \(bu 2 SLES 15 .IP \(bu 2 openSUSE Leap 15.0, 15.1, 42.2, 42.3 .IP \(bu 2 openSUSE Tumbleweed .UNINDENT .sp Instructions are at \fI\%https://repo.saltstack.com/#suse\fP\&. .SS Installation from the SUSE Repository .sp Since openSUSE 13.2, Salt has been 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 Leap or Tumbleweed systems, run the following as root: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C zypper install salt salt\-minion salt\-master .ft P .fi .UNINDENT .UNINDENT .SS SUSE Linux Enterprise .sp For SLES 15 and above run the following as root: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C 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 Proxy Minion Configuration .sp A proxy minion emulates the behaviour of a regular minion and inherits their options. .sp Similarly, the configuration file is \fB/etc/salt/proxy\fP and the proxy tries to connect to the DNS name "salt". .sp In addition to the regular minion options, there are several proxy\-specific \- see the proxy minion configuration reference\&. .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.version\fP command: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C [root@master ~]# salt alpha test.version alpha: 2018.3.4 .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.version alpha: 2018.3.4 bravo: 2018.3.4 charlie: 2018.3.4 delta: 2018.3.4 .ft P .fi .UNINDENT .UNINDENT .sp Each of the Minions should send a \fB2018.3.4\fP response as shown above, or any other salt version installed. .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 a user to install the Salt Minion or Master on a variety of system distributions and versions. .sp The Salt Bootstrap Script is a shell script is known as \fBbootstrap\-salt.sh\fP\&. It runs through a series of checks to determine the operating system type and version. It then installs the Salt binaries using the appropriate methods. .sp 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. .sp The Salt Bootstrap Script is maintained in a separate repo from Salt, complete with its own issues, pull requests, contributing guidelines, release protocol, etc. .sp To learn more, please see the Salt Bootstrap repo links: .INDENT 0.0 .IP \(bu 2 \fI\%Salt Bootstrap repo\fP .IP \(bu 2 \fI\%README\fP: includes supported operating systems, example usage, and more. .IP \(bu 2 \fI\%Contributing Guidelines\fP .IP \(bu 2 \fI\%Release Process\fP .UNINDENT .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 The Salt Bootstrap script can be found in the Salt repo under the \fBsalt/cloud/deploy/bootstrap\-salt.sh\fP path. Any changes to this file will be overwritten! Bug fixes and feature additions must be submitted via the \fI\%Salt Bootstrap repo\fP\&. Please see the Salt Bootstrap Script\(aqs \fI\%Release Process\fP for more information. .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 A network zone defines the security level of trust for the network. The user should choose an appropriate zone value for their setup. Possible values include: drop, block, public, external, dmz, work, home, internal, trusted. .sp 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 Windows .sp Windows Firewall is the default component of Microsoft Windows that provides firewalling and packet filtering. There are many 3rd party firewalls available for Windows, some of which use rules from the Windows Firewall. If you are experiencing problems see the vendor\(aqs specific documentation for opening the required ports. .sp The Windows Firewall can be configured using the Windows Interface or from the command line. .sp \fBWindows Firewall (interface)\fP: .INDENT 0.0 .IP 1. 3 Open the Windows Firewall Interface by typing \fBwf.msc\fP at the command prompt or in a run dialog (\fIWindows Key + R\fP) .IP 2. 3 Navigate to \fBInbound Rules\fP in the console tree .IP 3. 3 Add a new rule by clicking \fBNew Rule...\fP in the Actions area .IP 4. 3 Change the Rule Type to \fBPort\fP\&. Click \fBNext\fP .IP 5. 3 Set the Protocol to \fBTCP\fP and specify local ports \fB4505\-4506\fP\&. Click \fBNext\fP .IP 6. 3 Set the Action to \fBAllow the connection\fP\&. Click \fBNext\fP .IP 7. 3 Apply the rule to \fBDomain\fP, \fBPrivate\fP, and \fBPublic\fP\&. Click \fBNext\fP .IP 8. 3 Give the new rule a Name, ie: \fBSalt\fP\&. You may also add a description. Click \fBFinish\fP .UNINDENT .sp \fBWindows Firewall (command line)\fP: .sp The Windows Firewall rule can be created by issuing a single command. Run the following command from the command line or a run prompt: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C netsh advfirewall firewall add rule name="Salt" dir=in action=allow protocol=TCP localport=4505\-4506 .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 below line 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: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 addition 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:4506 .ft P .fi .UNINDENT .UNINDENT .sp Once this addition has 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 \-\-dports 4505:4506 \-j ACCEPT \-I INPUT \-s 10.1.3.0/24 \-p tcp \-\-dports 4505:4506 \-j ACCEPT # Allow Salt to communicate with Master on the loopback interface \-A INPUT \-i lo \-p tcp \-\-dports 4505:4506 \-j ACCEPT # Reject everything else \-A INPUT \-p tcp \-\-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.version\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 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\%https://aws.amazon.com/blogs/security/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. 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 .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.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. .UNINDENT .UNINDENT .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\%https://brew.sh/\fP .sp 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. .SS Step 2 \- Configuring The Minion VM .sp The Salt minion is going to run on a Virtual Machine. There are a lot of software options that let you run virtual machines on a mac, But for this tutorial we\(aqre going to use VirtualBox. In addition to virtualBox, we will use Vagrant, which allows you to create the base VM configuration. .sp Vagrant lets you build ready to use VM images, starting from an OS image and customizing it using "provisioners". In our case, we\(aqll use it to: .INDENT 0.0 .IP \(bu 2 Download the base Ubuntu image .IP \(bu 2 Install salt on that Ubuntu image (Salt is going to be the "provisioner" for the VM). .IP \(bu 2 Launch the VM .IP \(bu 2 SSH into the VM to debug .IP \(bu 2 Stop the VM once you\(aqre done. .UNINDENT .SS Install VirtualBox .sp Go get it here: \fI\%https://www.virtualbox.org/wiki/Downloads\fP (click on VirtualBox for macOS hosts => x86/amd64) .SS Install Vagrant .sp Go get it here: \fI\%https://www.vagrantup.com/downloads.html\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 Step 3 \- Connecting Master and Minion .SS Creating The Minion Configuration File .sp Create the \fB/etc/salt/minion\fP file. In that file, put the following lines, giving the ID for this minion, and the IP of the master: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C master: 10.0.2.2 id: \(aqminion1\(aq file_client: remote .ft P .fi .UNINDENT .UNINDENT .sp Minions authenticate with the master using keys. Keys are generated automatically if you don\(aqt provide one and 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.version .ft P .fi .UNINDENT .UNINDENT .sp You should see your minion answering with its salt version. It\(aqs now time to do some configuration. .SS Step 4 \- Configure Services to Install On the Minion .sp In this step we\(aqll use the Salt master to instruct our minion to install Nginx. .SS Checking the system\(aqs original state .sp First, make sure that an HTTP server is not installed on our minion. When opening a browser directed at \fBhttp://192.168.33.10/\fP You should get an error saying the site cannot be reached. .SS Initialize the top.sls file .sp System configuration is done in \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 _your_current_dir_ = ... ROOT_DIR = _your_current_dir_ + "/salt/root" # you need to edit this _location_of_source_code_ = ... INSTALL_DIR = _location_of_source_code_ CONFIG_DIR = ROOT_DIR + "/etc/salt" CACHE_DIR = ROOT_DIR + "/var/cache/salt" SOCK_DIR = ROOT_DIR + "/var/run/salt" SRV_ROOT_DIR = ROOT_DIR + "/srv" BASE_FILE_ROOTS_DIR = ROOT_DIR + "/srv/salt" BASE_PILLAR_ROOTS_DIR = ROOT_DIR + "/srv/pillar" BASE_MASTER_ROOTS_DIR = ROOT_DIR + "/srv/salt\-master" LOGS_DIR = ROOT_DIR + "/var/log/salt" PIDFILE_DIR = ROOT_DIR + "/var/run" CLOUD_DIR = INSTALL_DIR + "/cloud" BOOTSTRAP = CLOUD_DIR + "/deploy/bootstrap\-salt.sh" .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, it is not required to run the salt\-minion daemon. By default the salt\-minion daemon 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. .sp As of version 2016.11.0 you can have a running minion (with engines and beacons) without a master connection. If you wish to run the salt\-minion daemon you will need to set the \fBmaster_type\fP configuration setting to be set to \(aqdisable\(aq. .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\fP \- Python2 >= 2.7, Python3 >= 3.4 .IP \(bu 2 \fI\%msgpack\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 \- Python2 only dependency. Backport of the concurrent.futures package from Python 3.2 .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 .UNINDENT .sp \fBWARNING:\fP .INDENT 0.0 .INDENT 3.5 For historical reasons, Salt requires PyCrypto as a "lowest common denominator". However, \fI\%PyCrypto is unmaintained\fP and best practice is to manually upgrade to use a more maintained library such as \fI\%PyCryptodome\fP\&. See \fI\%Issue #52674\fP and \fI\%Issue #54115\fP for more info .UNINDENT .UNINDENT .sp Salt defaults to the \fI\%ZeroMQ\fP transport. The \fB\-\-salt\-transport\fP installation option is available, but currently only supports the \fBzeromq\fP option. This may be expanded in the future. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C python setup.py \-\-salt\-transport=zeromq 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=zeromq" 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. Atomic included configuration files can be placed in \fB/etc/salt/master.d/*.conf\fP\&. Warning: files with other suffixes than .conf will not be included. 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, must be an IP address. .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 \fBenable_ssh_minions\fP .sp Default: \fBFalse\fP .sp Tell the master to also use salt\-ssh when running commands against minions. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C enable_ssh_minions: True .ft P .fi .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 Cross\-minion communication is still not possible. The Salt mine and publish.publish do not work between minion types. .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, \fI\%autosign_grains_dir\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, \fButils\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 \fBextmod_whitelist/extmod_blacklist\fP .sp New in version 2017.7.0. .sp By using this dictionary, the modules that are synced to the master\(aqs extmod cache using \fIsaltutil.sync_*\fP can be limited. If nothing is set to a specific type, then all modules are accepted. To block all modules of a specific type, whitelist an empty list. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C extmod_whitelist: modules: \- custom_module engines: \- custom_engine pillars: [] extmod_blacklist: modules: \- specific_module .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .TP .B Valid options: .INDENT 7.0 .IP \(bu 2 modules .IP \(bu 2 states .IP \(bu 2 grains .IP \(bu 2 renderers .IP \(bu 2 returners .IP \(bu 2 output .IP \(bu 2 proxy .IP \(bu 2 runners .IP \(bu 2 wheel .IP \(bu 2 engines .IP \(bu 2 queues .IP \(bu 2 pillar .IP \(bu 2 utils .IP \(bu 2 sdb .IP \(bu 2 cache .IP \(bu 2 clouds .IP \(bu 2 tops .IP \(bu 2 roster .IP \(bu 2 tokens .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 \fBoutputter_dirs\fP .sp Default: \fB[]\fP .sp A list of additional directories to search for salt outputters in. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C outputter_dirs: [] .ft P .fi .UNINDENT .UNINDENT .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 \fBshow_timeout\fP .sp Default: \fBTrue\fP .sp Tell the client to show minions that have timed out. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C show_timeout: True .ft P .fi .UNINDENT .UNINDENT .SS \fBshow_jid\fP .sp Default: \fBFalse\fP .sp Tell the client to display the jid when a job is published. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C show_jid: False .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 \fBcolor_theme\fP .sp Default: \fB""\fP .sp Specifies a path to the color theme to use for colored command line output. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C color_theme: /etc/salt/color_theme .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: \fBFalse\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. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C enable_gpu_grains: True .ft P .fi .UNINDENT .UNINDENT .SS \fBskip_grains\fP .sp Default: \fBFalse\fP .sp MasterMinions should omit grains. A MasterMinion is "a minion function object for generic use on the master" that omit pillar. A RunnerClient creates a MasterMinion omitting states and renderer. Setting to True can improve master performance. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C skip_grains: True .ft P .fi .UNINDENT .UNINDENT .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 \fBmemcache_expire_seconds\fP .sp Default: \fB0\fP .sp Memcache is an additional cache layer that keeps a limited amount of data fetched from the minion data cache for a limited period of time in memory that makes cache operations faster. It doesn\(aqt make much sense for the \fBlocalfs\fP cache driver but helps for more complex drivers like \fBconsul\fP\&. .sp This option sets the memcache items expiration time. By default is set to \fB0\fP that disables the memcache. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C memcache_expire_seconds: 30 .ft P .fi .UNINDENT .UNINDENT .SS \fBmemcache_max_items\fP .sp Default: \fB1024\fP .sp Set memcache limit in items that are bank\-key pairs. I.e the list of minion_0/data, minion_0/mine, minion_1/data contains 3 items. This value depends on the count of minions usually targeted in your environment. The best one could be found by analyzing the cache log with \fBmemcache_debug\fP enabled. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C memcache_max_items: 1024 .ft P .fi .UNINDENT .UNINDENT .SS \fBmemcache_full_cleanup\fP .sp Default: \fBFalse\fP .sp If cache storage got full, i.e. the items count exceeds the \fBmemcache_max_items\fP value, memcache cleans up its storage. If this option set to \fBFalse\fP memcache removes the only one oldest value from its storage. If this set set to \fBTrue\fP memcache removes all the expired items and also removes the oldest one if there are no expired items. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C memcache_full_cleanup: True .ft P .fi .UNINDENT .UNINDENT .SS \fBmemcache_debug\fP .sp Default: \fBFalse\fP .sp Enable collecting the memcache stats and log it on \fIdebug\fP log level. If enabled memcache collect information about how many \fBfetch\fP calls has been done and how many of them has been hit by memcache. Also it outputs the rate value that is the result of division of the first two values. This should help to choose right values for the expiration time and the cache size. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C memcache_debug: True .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 \fBjob_cache_store_endtime\fP .sp New in version 2015.8.0. .sp Default: \fBFalse\fP .sp Specify whether the Salt Master should store end times for jobs as returns come in. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C job_cache_store_endtime: False .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. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C presence_events: False .ft P .fi .UNINDENT .UNINDENT .SS \fBping_on_rotate\fP .sp New in version 2014.7.0. .sp Default: \fBFalse\fP .sp 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. .sp To tell the master to ping all minions immediately after an AES key refresh, set \fBping_on_rotate\fP to \fBTrue\fP\&. This should mitigate the issue where a minion does not appear to initially respond after a key is rotated. .sp Note that enabling this 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. .sp If disabled, it is recommended to handle this event by listening for the \fBaes_key_rotate\fP event with the \fBkey\fP tag and acting appropriately. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C ping_on_rotate: 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 and \fBtcp\fP (experimental). This setting has a significant impact on performance and should not be changed unless you know what you are doing! .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! 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 \fBmaster_stats\fP .sp Default: False .sp Turning on the master stats enables runtime throughput and statistics events to be fired from the master event bus. These events will report on what functions have been run on the master and how long these runs have, on average, taken over a given period of time. .SS \fBmaster_stats_event_iter\fP .sp Default: 60 .sp The time in seconds to fire master_stats events. This will only fire in conjunction with receiving a request to the master, idle masters will not fire these events. .SS \fBsock_pool_size\fP .sp Default: 1 .sp To avoid blocking waiting while writing a data to a socket, we support socket pool for Salt applications. For example, a job with a large number of target host list can cause long period blocking waiting. The option is used by ZMQ and TCP transports, and the other transport methods don\(aqt need the socket pool by definition. Most of Salt tools, including CLI, are enough to use a single bucket of socket pool. On the other hands, it is highly recommended to set the size of socket pool larger than 1 for other Salt applications, especially Salt API, which must write data to socket concurrently. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C sock_pool_size: 15 .ft P .fi .UNINDENT .UNINDENT .SS \fBipc_mode\fP .sp Default: \fBipc\fP .sp The ipc strategy. (i.e., sockets versus tcp, etc.) Windows platforms lack POSIX IPC and must rely on TCP based inter\-process communications. \fBipc_mode\fP is set to \fBtcp\fP by default on Windows. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C ipc_mode: ipc .ft P .fi .UNINDENT .UNINDENT .SS \fBtcp_master_pub_port\fP .sp Default: \fB4512\fP .sp The TCP port on which events for the master should be published if \fBipc_mode\fP is TCP. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C tcp_master_pub_port: 4512 .ft P .fi .UNINDENT .UNINDENT .SS \fBtcp_master_pull_port\fP .sp Default: \fB4513\fP .sp The TCP port on which events for the master should be pulled if \fBipc_mode\fP is TCP. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C tcp_master_pull_port: 4513 .ft P .fi .UNINDENT .UNINDENT .SS \fBtcp_master_publish_pull\fP .sp Default: \fB4514\fP .sp The TCP port on which events for the master should be pulled fom and then republished onto the event bus on the master. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C tcp_master_publish_pull: 4514 .ft P .fi .UNINDENT .UNINDENT .SS \fBtcp_master_workers\fP .sp Default: \fB4515\fP .sp The TCP port for \fBmworkers\fP to connect to on the master. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C tcp_master_workers: 4515 .ft P .fi .UNINDENT .UNINDENT .SS \fBauth_events\fP .sp New in version 2017.7.3. .sp Default: \fBTrue\fP .sp Determines whether the master will fire authentication events. Authentication events are fired when a minion performs an authentication check with the master. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C auth_events: True .ft P .fi .UNINDENT .UNINDENT .SS \fBminion_data_cache_events\fP .sp New in version 2017.7.3. .sp Default: \fBTrue\fP .sp Determines whether the master will fire minion data cache events. Minion data cache events are fired when a minion requests a minion data cache refresh. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C minion_data_cache_events: True .ft P .fi .UNINDENT .UNINDENT .SS \fBhttp_connect_timeout\fP .sp New in version 2019.2.0. .sp Default: \fB20\fP .sp HTTP connection timeout in seconds. Applied when fetching files using tornado back\-end. Should be greater than overall download time. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C http_connect_timeout: 20 .ft P .fi .UNINDENT .UNINDENT .SS \fBhttp_request_timeout\fP .sp New in version 2015.8.0. .sp Default: \fB3600\fP .sp HTTP request timeout in seconds. Applied when fetching files using tornado back\-end. Should be greater than overall download time. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C http_request_timeout: 3600 .ft P .fi .UNINDENT .UNINDENT .SS \fBuse_yamlloader_old\fP .sp New in version 2019.2.1. .sp Default: \fBFalse\fP .sp Use the pre\-2019.2 YAML renderer. Uses legacy YAML rendering to support some legacy inline data structures. See the 2019.2.1 release notes for more details. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C use_yamlloader_old: False .ft P .fi .UNINDENT .UNINDENT .SS \fBreq_server_niceness\fP .sp New in version 3001. .sp Default: \fBNone\fP .sp Process priority level of the ReqServer subprocess of the master. Supported on POSIX platforms only. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C req_server_niceness: 9 .ft P .fi .UNINDENT .UNINDENT .SS \fBpub_server_niceness\fP .sp New in version 3001. .sp Default: \fBNone\fP .sp Process priority level of the PubServer subprocess of the master. Supported on POSIX platforms only. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C pub_server_niceness: 9 .ft P .fi .UNINDENT .UNINDENT .SS \fBfileserver_update_niceness\fP .sp New in version 3001. .sp Default: \fBNone\fP .sp Process priority level of the FileServerUpdate subprocess of the master. Supported on POSIX platforms only. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C fileserver_update_niceness: 9 .ft P .fi .UNINDENT .UNINDENT .SS \fBmaintenance_niceness\fP .sp New in version 3001. .sp Default: \fBNone\fP .sp Process priority level of the Maintenance subprocess of the master. Supported on POSIX platforms only. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C maintenance_niceness: 9 .ft P .fi .UNINDENT .UNINDENT .SS \fBmworker_niceness\fP .sp New in version 3001. .sp Default: \fBNone\fP .sp Process priority level of the MWorker subprocess of the master. Supported on POSIX platforms only. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C mworker_niceness: 9 .ft P .fi .UNINDENT .UNINDENT .SS \fBmworker_queue_niceness\fP .sp New in version 3001. .sp default: \fBNone\fP .sp process priority level of the MWorkerQueue subprocess of the master. supported on POSIX platforms only. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C mworker_queue_niceness: 9 .ft P .fi .UNINDENT .UNINDENT .SS \fBevent_return_niceness\fP .sp New in version 3001. .sp default: \fBNone\fP .sp process priority level of the EventReturn subprocess of the master. supported on POSIX platforms only. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C event_return_niceness: 9 .ft P .fi .UNINDENT .UNINDENT .SS \fBevent_publisher_niceness\fP .sp New in version 3001. .sp default: \fBnone\fP .sp process priority level of the EventPublisher subprocess of the master. supported on POSIX platforms only. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C event_publisher_niceness: 9 .ft P .fi .UNINDENT .UNINDENT .SS \fBreactor_niceness\fP .sp New in version 3001. .sp default: \fBNone\fP .sp process priority level of the Reactor subprocess of the master. supported on POSIX platforms only. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C reactor_niceness: 9 .ft P .fi .UNINDENT .UNINDENT .SS Salt\-SSH Configuration .SS \fBroster\fP .sp Default: \fBflat\fP .sp Define the default salt\-ssh roster module to use .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C roster: cache .ft P .fi .UNINDENT .UNINDENT .SS \fBroster_defaults\fP .sp New in version 2017.7.0. .sp Default settings which will be inherited by all rosters. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C roster_defaults: user: daniel sudo: True priv: /root/.ssh/id_rsa tty: True .ft P .fi .UNINDENT .UNINDENT .SS \fBroster_file\fP .sp Default: \fB/etc/salt/roster\fP .sp Pass in an alternative location for the salt\-ssh \fBflat\fP roster file. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C roster_file: /root/roster .ft P .fi .UNINDENT .UNINDENT .SS \fBrosters\fP .sp Default: \fBNone\fP .sp Define locations for \fBflat\fP 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, the \fI\%roster_file\fP parameter should contain a relative path to these locations. That is, \fBroster_file=/foo/roster\fP will be resolved as \fB/etc/salt/roster.d/foo/roster\fP etc. This feature prevents passing insecure custom rosters through the Salt API. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C rosters: \- /etc/salt/roster.d \- /opt/salt/some/more/rosters .ft P .fi .UNINDENT .UNINDENT .SS \fBssh_passwd\fP .sp Default: \fB\(aq\(aq\fP .sp The ssh password to log in with. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C ssh_passwd: \(aq\(aq .ft P .fi .UNINDENT .UNINDENT .SS \fBssh_priv_passwd\fP .sp Default: \fB\(aq\(aq\fP .sp Passphrase for ssh private key file. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C ssh_priv_passwd: \(aq\(aq .ft P .fi .UNINDENT .UNINDENT .SS \fBssh_port\fP .sp Default: \fB22\fP .sp The target system\(aqs ssh port number. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C ssh_port: 22 .ft P .fi .UNINDENT .UNINDENT .SS \fBssh_scan_ports\fP .sp Default: \fB22\fP .sp Comma\-separated list of ports to scan. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C ssh_scan_ports: 22 .ft P .fi .UNINDENT .UNINDENT .SS \fBssh_scan_timeout\fP .sp Default: \fB0.01\fP .sp Scanning socket timeout for salt\-ssh. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C ssh_scan_timeout: 0.01 .ft P .fi .UNINDENT .UNINDENT .SS \fBssh_sudo\fP .sp Default: \fBFalse\fP .sp Boolean to run command via sudo. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C ssh_sudo: False .ft P .fi .UNINDENT .UNINDENT .SS \fBssh_timeout\fP .sp Default: \fB60\fP .sp Number of seconds to wait for a response when establishing an SSH connection. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C ssh_timeout: 60 .ft P .fi .UNINDENT .UNINDENT .SS \fBssh_user\fP .sp Default: \fBroot\fP .sp The user to log in as. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C ssh_user: root .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 \fBssh_identities_only\fP .sp Default: \fBFalse\fP .sp Set this to \fBTrue\fP to default salt\-ssh to run with \fB\-o IdentitiesOnly=yes\fP\&. This option is intended for situations where the ssh\-agent offers many different identities and allows ssh to ignore those identities and use the only one specified in options. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C ssh_identities_only: False .ft P .fi .UNINDENT .UNINDENT .SS \fBssh_list_nodegroups\fP .sp Default: \fB{}\fP .sp List\-only nodegroups for salt\-ssh. Each group must be formed as either a comma\-separated list, or a YAML list. This option is useful to group minions into easy\-to\-target groups when using salt\-ssh. These groups can then be targeted with the normal \-N argument to salt\-ssh. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C ssh_list_nodegroups: groupA: minion1,minion2 groupB: minion1,minion3 .ft P .fi .UNINDENT .UNINDENT .sp Default: False .sp Run the ssh_pre_flight script defined in the salt\-ssh roster. By default the script will only run when the thin dir does not exist on the targeted minion. This will force the script to run and not check if the thin dir exists first. .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 \fBmin_extra_mods\fP .sp Default: None .sp Identical as \fIthin_extra_mods\fP, only applied to the Salt Minimal. .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 \fBkeysize\fP .sp Default: \fB2048\fP .sp The size of key that should be generated when creating new keys. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C keysize: 2048 .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. .sp Changed in version 2018.3.0: For security reasons the file must be readonly except for its owner. If \fI\%permissive_pki_access\fP is \fBTrue\fP the owning group can also have write access, but if Salt is running as \fBroot\fP it must be a member of that group. A less strict requirement also existed in previous version. .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 \fBautosign_grains_dir\fP .sp New in version 2018.3.0. .sp Default: \fBnot defined\fP .sp If the \fBautosign_grains_dir\fP is specified, incoming keys from minions with grain values that match those defined in files in the autosign_grains_dir will be accepted automatically. Grain values that should be accepted automatically can be defined by creating a file named like the corresponding grain in the autosign_grains_dir and writing the values into that file, one value per line. Lines starting with a \fB#\fP will be ignored. Minion must be configured to send the corresponding grains on authentication. This should still be considered a less than secure option, due to the fact that trust is based on just the requesting minion. .sp Please see the Autoaccept Minions from Grains documentation for more information. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C autosign_grains_dir: /etc/salt/autosign_grains .ft P .fi .UNINDENT .UNINDENT .SS \fBpermissive_pki_access\fP .sp Default: \fBFalse\fP .sp 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. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C permissive_pki_access: False .ft P .fi .UNINDENT .UNINDENT .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. .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. .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.* \- test.echo .ft P .fi .UNINDENT .UNINDENT .SS \fBsudo_acl\fP .sp Default: \fBFalse\fP .sp Enforce \fBpublisher_acl\fP and \fBpublisher_acl_blacklist\fP when users have sudo access to the salt command. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C sudo_acl: False .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 \fBkeep_acl_in_token\fP .sp Default: \fBFalse\fP .sp Set to True to enable keeping the calculated user\(aqs auth list in the token file. This is disabled by default and the auth list is calculated or requested from the eauth driver each time. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C keep_acl_in_token: False .ft P .fi .UNINDENT .UNINDENT .SS \fBeauth_acl_module\fP .sp Default: \fB\(aq\(aq\fP .sp Auth subsystem module to use to get authorized access list for a user. By default it\(aqs the same module used for external authentication. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C eauth_acl_module: django .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 \fBpublish_session\fP .sp Default: \fB86400\fP .sp The number of seconds between AES key rotations on the master. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C publish_session: Default: 86400 .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 \fBpreserve_minion_cache\fP .sp Default: \fBFalse\fP .sp 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 \fBpreserve_minion_cache\fP to True. .sp WARNING: This may have security implications if compromised minions auth with a previous deleted minion ID. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C preserve_minion_cache: False .ft P .fi .UNINDENT .UNINDENT .SS \fBallow_minion_key_revoke\fP .sp Default: \fBTrue\fP .sp Controls whether a minion can request its own key revocation. When True the master will honor the minion\(aqs request and revoke its key. When False, the master will drop the request and the minion\(aqs key will remain accepted. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C allow_minion_key_revoke: False .ft P .fi .UNINDENT .UNINDENT .SS \fBoptimization_order\fP .sp Default: \fB[0, 1, 2]\fP .sp In cases where Salt is distributed without .py files, this option determines the priority of optimization level(s) Salt\(aqs module loader should prefer. .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 This option is only supported on Python 3.5+. .UNINDENT .UNINDENT .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C optimization_order: \- 2 \- 0 \- 1 .ft P .fi .UNINDENT .UNINDENT .SS Master Large Scale Tuning Settings .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 \fBpub_hwm\fP .sp Default: \fB1000\fP .sp The zeromq high water mark on the publisher interface. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C pub_hwm: 1000 .ft P .fi .UNINDENT .UNINDENT .SS \fBzmq_backlog\fP .sp Default: \fB1000\fP .sp The listen queue size of the ZeroMQ backlog. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C zmq_backlog: 1000 .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 \fButils_dirs\fP .sp New in version 2018.3.0. .sp Default: \fB[]\fP .sp Set additional directories to search for util modules. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C utils_dirs: \- /var/lib/salt/utils .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. The value of "state_top" is also used for the pillar top file .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C state_top: top.sls .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\&. Note that, aside from the \fBbase\fP environment\(aqs top file, any sections in top files that do not match that top file\(aqs environment will be ignored. So, for example, a section for the \fBqa\fP environment would be ignored if it appears in the \fBdev\fP environment\(aqs top file. To keep use cases like this from being ignored, use the \fBmerge_all\fP strategy. .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 \fBdefault_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 \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 \fBrenderer\fP .sp Default: \fBjinja|yaml\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: jinja|json .ft P .fi .UNINDENT .UNINDENT .SS \fBuserdata_template\fP .sp New in version 2016.11.4. .sp Default: \fBNone\fP .sp The renderer to use for templating userdata files in salt\-cloud, if the \fBuserdata_template\fP is not set in the cloud profile. If no value is set in the cloud profile or master config file, no templating will be performed. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C userdata_template: jinja .ft P .fi .UNINDENT .UNINDENT .SS \fBjinja_env\fP .sp New in version 2018.3.0. .sp Default: \fB{}\fP .sp jinja_env overrides the default Jinja environment options for \fBall templates except sls templates\fP\&. To set the options for sls templates use \fI\%jinja_sls_env\fP\&. .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 The \fI\%Jinja2 Environment documentation\fP is the official source for the default values. Not all the options listed in the jinja documentation can be overridden using \fI\%jinja_env\fP or \fI\%jinja_sls_env\fP\&. .UNINDENT .UNINDENT .sp The default options are: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C jinja_env: block_start_string: \(aq{%\(aq block_end_string: \(aq%}\(aq variable_start_string: \(aq{{\(aq variable_end_string: \(aq}}\(aq comment_start_string: \(aq{#\(aq comment_end_string: \(aq#}\(aq line_statement_prefix: line_comment_prefix: trim_blocks: False lstrip_blocks: False newline_sequence: \(aq\en\(aq keep_trailing_newline: False .ft P .fi .UNINDENT .UNINDENT .SS \fBjinja_sls_env\fP .sp New in version 2018.3.0. .sp Default: \fB{}\fP .sp jinja_sls_env sets the Jinja environment options for \fBsls templates\fP\&. The defaults and accepted options are exactly the same as they are for \fI\%jinja_env\fP\&. .sp The default options are: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C jinja_sls_env: block_start_string: \(aq{%\(aq block_end_string: \(aq%}\(aq variable_start_string: \(aq{{\(aq variable_end_string: \(aq}}\(aq comment_start_string: \(aq{#\(aq comment_end_string: \(aq#}\(aq line_statement_prefix: line_comment_prefix: trim_blocks: False lstrip_blocks: False newline_sequence: \(aq\en\(aq keep_trailing_newline: False .ft P .fi .UNINDENT .UNINDENT .sp Example using line statements and line comments to increase ease of use: .sp If your configuration options are .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C jinja_sls_env: line_statement_prefix: \(aq%\(aq line_comment_prefix: \(aq##\(aq .ft P .fi .UNINDENT .UNINDENT .sp With these options jinja will interpret anything after a \fB%\fP at the start of a line (ignoreing whitespace) as a jinja statement and will interpret anything after a \fB##\fP as a comment. .sp This allows the following more convenient syntax to be used: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C ## (this comment will not stay once rendered) # (this comment remains in the rendered template) ## ensure all the formula services are running % for service in formula_services: enable_service_{{ service }}: service.running: name: {{ service }} % endfor .ft P .fi .UNINDENT .UNINDENT .sp The following less convenient but equivalent syntax would have to be used if you had not set the line_statement and line_comment options: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C {# (this comment will not stay once rendered) #} # (this comment remains in the rendered template) {# ensure all the formula services are running #} {% for service in formula_services %} enable_service_{{ service }}: service.running: name: {{ service }} {% endfor %} .ft P .fi .UNINDENT .UNINDENT .SS \fBjinja_trim_blocks\fP .sp Deprecated since version 2018.3.0: Replaced by \fI\%jinja_env\fP and \fI\%jinja_sls_env\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 Deprecated since version 2018.3.0: Replaced by \fI\%jinja_env\fP and \fI\%jinja_sls_env\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 controls which results will be output full multi line: .INDENT 0.0 .IP \(bu 2 \fBfull\fP, \fBterse\fP \- each state will be full/terse .IP \(bu 2 \fBmixed\fP \- only states with errors will be full .IP \(bu 2 \fBchanges\fP \- states with changes and errors will be full .UNINDENT .sp \fBfull_id\fP, \fBmixed_id\fP, \fBchanges_id\fP and \fBterse_id\fP are also allowed; when set, the state ID will be used as name in the output. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C state_output: full .ft P .fi .UNINDENT .UNINDENT .SS \fBstate_output_diff\fP .sp Default: \fBFalse\fP .sp 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. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C state_output_diff: False .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 \- gitfs .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 Deprecated since version 2018.3.4: This option is now ignored. Firstly, it only traversed \fI\%file_roots\fP, which means it did not work for the other fileserver backends. Secondly, since this option was added we have added caching to the code that traverses the file_roots (and gitfs, etc.), which greatly reduces the amount of traversal that is done. .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_file_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 \fBfileserver_verify_config\fP .sp New in version 2017.7.0. .sp Default: \fBTrue\fP .sp By default, as the master starts it performs some sanity checks on the configured fileserver backends. If any of these sanity checks fail (such as when an invalid configuration is used), the master daemon will abort. .sp To skip these sanity checks, set this option to \fBFalse\fP\&. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C fileserver_verify_config: 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 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 \fBmaster_roots\fP .sp Default: \fB\(aq\(aq\fP .sp A master\-only copy of the \fI\%file_roots\fP dictionary, used by the state compiler. .sp Example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C master_roots: base: \- /srv/salt\-master .ft P .fi .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 As of 2018.3.5 and 2019.2.1, it is possible to have \fI__env__\fP as a catch\-all environment. .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 __env__: \- /srv/salt/default .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 \fBroots_update_interval\fP .sp New in version 2018.3.0. .sp Default: \fB60\fP .sp This option defines the update interval (in seconds) for \fI\%file_roots\fP\&. .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 Since \fBfile_roots\fP consists of files local to the minion, the update process for this fileserver backend just reaps the cache for this backend. .UNINDENT .UNINDENT .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C roots_update_interval: 120 .ft P .fi .UNINDENT .UNINDENT .SS gitfs: 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 either \fBpygit2\fP or \fBgitpython\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: gitpython .ft P .fi .UNINDENT .UNINDENT .SS \fBgitfs_ssl_verify\fP .sp Default: \fBTrue\fP .sp Specifies whether or not to ignore SSL certificate errors when fetching from the repositories configured in \fI\%gitfs_remotes\fP\&. 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. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C gitfs_ssl_verify: False .ft P .fi .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 pygit2 only supports disabling SSL verification in versions 0.23.2 and newer. .UNINDENT .UNINDENT .sp Changed in version 2015.8.0: This option can now be configured on individual repositories as well. See here for more info. .sp Changed in version 2016.11.0: The default config value changed from \fBFalse\fP to \fBTrue\fP\&. .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 for an individual repository, 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: This option can now be configured on individual repositories as well. 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: This option can now be configured on individual repositories as well. 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_disable_saltenv_mapping\fP .sp New in version 2018.3.0. .sp Default: \fBFalse\fP .sp When set to \fBTrue\fP, all saltenv mapping logic is disregarded (aside from which branch/tag is mapped to the \fBbase\fP saltenv). To use any other environments, they must then be defined using per\-saltenv configuration parameters\&. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C gitfs_disable_saltenv_mapping: True .ft P .fi .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 This is is a global configuration option, see here for examples of configuring it for individual repositories. .UNINDENT .UNINDENT .SS \fBgitfs_ref_types\fP .sp New in version 2018.3.0. .sp Default: \fB[\(aqbranch\(aq, \(aqtag\(aq, \(aqsha\(aq]\fP .sp This option defines what types of refs are mapped to fileserver environments (i.e. saltenvs). It also sets the order of preference when there are ambiguously\-named refs (i.e. when a branch and tag both have the same name). The below example disables mapping of both tags and SHAs, so that only branches are mapped as saltenvs: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C gitfs_ref_types: \- branch .ft P .fi .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 This is is a global configuration option, see here for examples of configuring it for individual repositories. .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 \fBsha\fP is special in that it will not show up when listing saltenvs (e.g. with the \fBfileserver.envs\fP runner), but works within states and with \fBcp.cache_file\fP to retrieve a file from a specific git SHA. .UNINDENT .UNINDENT .SS \fBgitfs_saltenv_whitelist\fP .sp New in version 2014.7.0. .sp Changed in version 2018.3.0: Renamed from \fBgitfs_env_whitelist\fP to \fBgitfs_saltenv_whitelist\fP .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_saltenv_whitelist: \- base \- v1.* \- \(aqmybranch\ed+\(aq .ft P .fi .UNINDENT .UNINDENT .SS \fBgitfs_saltenv_blacklist\fP .sp New in version 2014.7.0. .sp Changed in version 2018.3.0: Renamed from \fBgitfs_env_blacklist\fP to \fBgitfs_saltenv_blacklist\fP .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_saltenv_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 \fBgitfs_update_interval\fP .sp New in version 2018.3.0. .sp Default: \fB60\fP .sp This option defines the default update interval (in seconds) for gitfs remotes. The update interval can also be set for a single repository via a per\-remote config option .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C gitfs_update_interval: 120 .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 .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 This is is a global configuration option, see here for examples of configuring it for individual repositories. .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 .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 This is is a global configuration option, see here for examples of configuring it for individual repositories. .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 .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 This is is a global configuration option, see here for examples of configuring it for individual repositories. .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. 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 .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 This is is a global configuration option, see here for examples of configuring it for individual repositories. .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. Required for SSH remotes. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C gitfs_privkey: /path/to/key .ft P .fi .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 This is is a global configuration option, see here for examples of configuring it for individual repositories. .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 .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 This is is a global configuration option, see here for examples of configuring it for individual repositories. .UNINDENT .UNINDENT .SS \fBgitfs_refspecs\fP .sp New in version 2017.7.0. .sp Default: \fB[\(aq+refs/heads/*:refs/remotes/origin/*\(aq, \(aq+refs/tags/*:refs/tags/*\(aq]\fP .sp When fetching from remote repositories, by default Salt will fetch branches and tags. This parameter can be used to override the default and specify alternate refspecs to be fetched. More information on how this feature works can be found in the GitFS Walkthrough\&. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C gitfs_refspecs: \- \(aq+refs/heads/*:refs/remotes/origin/*\(aq \- \(aq+refs/tags/*:refs/tags/*\(aq \- \(aq+refs/pull/*/head:refs/remotes/origin/pr/*\(aq \- \(aq+refs/pull/*/merge:refs/remotes/origin/merge/*\(aq .ft P .fi .UNINDENT .UNINDENT .SS hgfs: 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_saltenv_whitelist\fP .sp New in version 2014.7.0. .sp Changed in version 2018.3.0: Renamed from \fBhgfs_env_whitelist\fP to \fBhgfs_saltenv_whitelist\fP .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_saltenv_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_saltenv_whitelist: \- base \- v1.* \- \(aqmybranch\ed+\(aq .ft P .fi .UNINDENT .UNINDENT .SS \fBhgfs_saltenv_blacklist\fP .sp New in version 2014.7.0. .sp Changed in version 2018.3.0: Renamed from \fBhgfs_env_blacklist\fP to \fBhgfs_saltenv_blacklist\fP .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_saltenv_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_saltenv_blacklist: \- base \- v1.* \- \(aqmybranch\ed+\(aq .ft P .fi .UNINDENT .UNINDENT .SS \fBhgfs_update_interval\fP .sp New in version 2018.3.0. .sp Default: \fB60\fP .sp This option defines the update interval (in seconds) for \fI\%hgfs_remotes\fP\&. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C hgfs_update_interval: 120 .ft P .fi .UNINDENT .UNINDENT .SS svnfs: 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_saltenv_whitelist\fP .sp New in version 2014.7.0. .sp Changed in version 2018.3.0: Renamed from \fBsvnfs_env_whitelist\fP to \fBsvnfs_saltenv_whitelist\fP .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_saltenv_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_saltenv_whitelist: \- base \- v1.* \- \(aqmybranch\ed+\(aq .ft P .fi .UNINDENT .UNINDENT .SS \fBsvnfs_saltenv_blacklist\fP .sp New in version 2014.7.0. .sp Changed in version 2018.3.0: Renamed from \fBsvnfs_env_blacklist\fP to \fBsvnfs_saltenv_blacklist\fP .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_saltenv_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_saltenv_blacklist: \- base \- v1.* \- \(aqmybranch\ed+\(aq .ft P .fi .UNINDENT .UNINDENT .SS \fBsvnfs_update_interval\fP .sp New in version 2018.3.0. .sp Default: \fB60\fP .sp This option defines the update interval (in seconds) for \fI\%svnfs_remotes\fP\&. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C svnfs_update_interval: 120 .ft P .fi .UNINDENT .UNINDENT .SS minionfs: 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 \fBminionfs_update_interval\fP .sp New in version 2018.3.0. .sp Default: \fB60\fP .sp This option defines the update interval (in seconds) for MinionFS\&. .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 Since MinionFS consists of files local to the master, the update process for this fileserver backend just reaps the cache for this backend. .UNINDENT .UNINDENT .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C minionfs_update_interval: 120 .ft P .fi .UNINDENT .UNINDENT .SS azurefs: Azure File Server Backend .sp New in version 2015.8.0. .sp See the \fBazurefs documentation\fP for usage examples. .SS \fBazurefs_update_interval\fP .sp New in version 2018.3.0. .sp Default: \fB60\fP .sp This option defines the update interval (in seconds) for azurefs. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C azurefs_update_interval: 120 .ft P .fi .UNINDENT .UNINDENT .SS s3fs: S3 File Server Backend .sp New in version 0.16.0. .sp See the \fBs3fs documentation\fP for usage examples. .SS \fBs3fs_update_interval\fP .sp New in version 2018.3.0. .sp Default: \fB60\fP .sp This option defines the update interval (in seconds) for s3fs. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C s3fs_update_interval: 120 .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: .sp As of 2017.7.5 and 2018.3.1, it is possible to have \fI__env__\fP as a catch\-all environment. .sp Example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C pillar_roots: base: \- /srv/pillar dev: \- /srv/pillar/dev prod: \- /srv/pillar/prod __env__: \- /srv/pillar/others .ft P .fi .UNINDENT .UNINDENT .SS \fBon_demand_ext_pillar\fP .sp New in version 2016.3.6,2016.11.3,2017.7.0. .sp Default: \fB[\(aqlibvirt\(aq, \(aqvirtkey\(aq]\fP .sp The external pillars permitted to be used on\-demand using \fBpillar.ext\fP\&. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C on_demand_ext_pillar: \- libvirt \- virtkey \- git .ft P .fi .UNINDENT .UNINDENT .sp \fBWARNING:\fP .INDENT 0.0 .INDENT 3.5 This will allow minions to request specific pillar data via \fBpillar.ext\fP, and may be considered a security risk. However, pillar data generated in this way will not affect the in\-memory pillar data, so this risk is limited to instances in which states/modules/etc. (built\-in or custom) rely upon pillar data generated by \fBpillar.ext\fP\&. .UNINDENT .UNINDENT .SS \fBdecrypt_pillar\fP .sp New in version 2017.7.0. .sp Default: \fB[]\fP .sp A list of paths to be recursively decrypted during pillar compilation. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C decrypt_pillar: \- \(aqfoo:bar\(aq: gpg \- \(aqlorem:ipsum:dolor\(aq .ft P .fi .UNINDENT .UNINDENT .sp Entries in this list can be formatted either as a simple string, or as a key/value pair, with the key being the pillar location, and the value being the renderer to use for pillar decryption. If the former is used, the renderer specified by \fI\%decrypt_pillar_default\fP will be used. .SS \fBdecrypt_pillar_delimiter\fP .sp New in version 2017.7.0. .sp Default: \fB:\fP .sp The delimiter used to distinguish nested data structures in the \fI\%decrypt_pillar\fP option. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C decrypt_pillar_delimiter: \(aq|\(aq decrypt_pillar: \- \(aqfoo|bar\(aq: gpg \- \(aqlorem|ipsum|dolor\(aq .ft P .fi .UNINDENT .UNINDENT .SS \fBdecrypt_pillar_default\fP .sp New in version 2017.7.0. .sp Default: \fBgpg\fP .sp The default renderer used for decryption, if one is not specified for a given pillar key in \fI\%decrypt_pillar\fP\&. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C decrypt_pillar_default: my_custom_renderer .ft P .fi .UNINDENT .UNINDENT .SS \fBdecrypt_pillar_renderers\fP .sp New in version 2017.7.0. .sp Default: \fB[\(aqgpg\(aq]\fP .sp List of renderers which are permitted to be used for pillar decryption. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C decrypt_pillar_renderers: \- gpg \- my_custom_renderer .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 \fBpillar_safe_render_error\fP .sp Default: \fBTrue\fP .sp 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 \fBTrue\fP the error message will only show: .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 .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C pillar_safe_render_error: True .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/master/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 \fBpillarenv_from_saltenv\fP .sp Default: \fBFalse\fP .sp When set to \fBTrue\fP, the \fBpillarenv\fP value will assume the value of the effective saltenv when running states. This essentially makes \fBsalt\-run pillar.show_pillar saltenv=dev\fP equivalent to \fBsalt\-run pillar.show_pillar saltenv=dev pillarenv=dev\fP\&. If \fBpillarenv\fP is set on the CLI, it will override this option. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C pillarenv_from_saltenv: True .ft P .fi .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 For salt remote execution commands this option should be set in the Minion configuration instead. .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 its 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 .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 pygit2 only supports disabling SSL verification in versions 0.23.2 and newer. .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 \fBgit_pillar_includes\fP .sp New in version 2017.7.0. .sp Default: \fBTrue\fP .sp Normally, when processing git_pillar remotes, if more than one repo under the same \fBgit\fP section in the \fBext_pillar\fP configuration refers to the same pillar environment, then each repo in a given environment will have access to the other repos\(aq files to be referenced in their top files. However, it may be desirable to disable this behavior. If so, set this value to \fBFalse\fP\&. .sp For a more detailed examination of how includes work, see this explanation from the git_pillar documentation. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C git_pillar_includes: False .ft P .fi .UNINDENT .UNINDENT .SS \fBgit_pillar_update_interval\fP .sp New in version 3000. .sp Default: \fB60\fP .sp This option defines the default update interval (in seconds) for git_pillar remotes. The update is handled within the global loop, hence \fBgit_pillar_update_interval\fP should be a multiple of \fBloop_interval\fP\&. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C git_pillar_update_interval: 120 .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 \fBgit_pillar_refspecs\fP .sp New in version 2017.7.0. .sp Default: \fB[\(aq+refs/heads/*:refs/remotes/origin/*\(aq, \(aq+refs/tags/*:refs/tags/*\(aq]\fP .sp When fetching from remote repositories, by default Salt will fetch branches and tags. This parameter can be used to override the default and specify alternate refspecs to be fetched. This parameter works similarly to its GitFS counterpart, in that it can be configured both globally and for individual remotes. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C git_pillar_refspecs: \- \(aq+refs/heads/*:refs/remotes/origin/*\(aq \- \(aq+refs/tags/*:refs/tags/*\(aq \- \(aq+refs/pull/*/head:refs/remotes/origin/pr/*\(aq \- \(aq+refs/pull/*/merge:refs/remotes/origin/merge/*\(aq .ft P .fi .UNINDENT .UNINDENT .SS \fBgit_pillar_verify_config\fP .sp New in version 2017.7.0. .sp Default: \fBTrue\fP .sp By default, as the master starts it performs some sanity checks on the configured git_pillar repositories. If any of these sanity checks fail (such as when an invalid configuration is used), the master daemon will abort. .sp To skip these sanity checks, set this option to \fBFalse\fP\&. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C git_pillar_verify_config: False .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: .sp 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. .sp New in version 2016.3.4. .IP \(bu 2 \fBrecurse\fP: .sp It will recursively merge 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 .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 In order for yamlex based features such as \fB!aggregate\fP to work as expected across documents using the default \fBsmart\fP merge strategy, the \fI\%renderer\fP config option must be set to \fBjinja|yamlex\fP or similar. .UNINDENT .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 \fBpillar_includes_override_sls\fP .sp New in version 2017.7.6,2018.3.1. .sp Default: \fBFalse\fP .sp Prior to version 2017.7.3, keys from pillar includes would be merged on top of the pillar SLS. Since 2017.7.3, the includes are merged together and then the pillar SLS is merged on top of that. .sp Set this option to \fBTrue\fP to return to the old behavior. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C pillar_includes_override_sls: True .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 Master Reactor Settings .SS \fBreactor\fP .sp Default: \fB[]\fP .sp Defines a salt reactor. See the Reactor documentation for more information. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C reactor: \- \(aqsalt/minion/*/start\(aq: \- salt://reactor/startup_tasks.sls .ft P .fi .UNINDENT .UNINDENT .SS \fBreactor_refresh_interval\fP .sp Default: \fB60\fP .sp The TTL for the cache of the reactor configuration. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C reactor_refresh_interval: 60 .ft P .fi .UNINDENT .UNINDENT .SS \fBreactor_worker_threads\fP .sp Default: \fB10\fP .sp The number of workers for the runner/wheel in the reactor. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C reactor_worker_threads: 10 .ft P .fi .UNINDENT .UNINDENT .SS \fBreactor_worker_hwm\fP .sp Default: \fB10000\fP .sp The queue size for workers in the reactor. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C reactor_worker_hwm: 10000 .ft P .fi .UNINDENT .UNINDENT .SS Salt\-API Master Settings .sp There are some settings for salt\-api that can be configured on the Salt Master. .SS \fBapi_logfile\fP .sp Default: \fB/var/log/salt/api\fP .sp The logfile location for \fBsalt\-api\fP\&. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C api_logfile: /var/log/salt/api .ft P .fi .UNINDENT .UNINDENT .SS \fBapi_pidfile\fP .sp Default: /var/run/salt\-api.pid .sp If this master will be running \fBsalt\-api\fP, specify the pidfile of the \fBsalt\-api\fP daemon. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C api_pidfile: /var/run/salt\-api.pid .ft P .fi .UNINDENT .UNINDENT .SS \fBrest_timeout\fP .sp Default: \fB300\fP .sp Used by \fBsalt\-api\fP for the master requests timeout. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C rest_timeout: 300 .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 \fBsyndic_forward_all_events\fP .sp New in version 2017.7.0. .sp Default: \fBFalse\fP .sp Option on multi\-syndic or single when connected to multiple masters to be able to send events to all connected masters. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C syndic_forward_all_events: False .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 \fBlog_rotate_max_bytes\fP .sp Default: \fB0\fP .sp The maximum number of bytes a single log file may contain before it is rotated. A value of 0 disables this feature. Currently only supported on Windows. On other platforms, use an external tool such as \(aqlogrotate\(aq to manage log files. \fBlog_rotate_max_bytes\fP .SS \fBlog_rotate_backup_count\fP .sp Default: \fB0\fP .sp The number of backup files to keep when rotating log files. Only used if \fI\%log_rotate_max_bytes\fP is greater than 0. Currently only supported on Windows. On other platforms, use an external tool such as \(aqlogrotate\(aq to manage log files. \fBlog_rotate_backup_count\fP .SS Node Groups .SS \fBnodegroups\fP .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 .sp Configuration can be loaded from multiple files. The order in which this is done is: .INDENT 0.0 .IP 1. 3 The master config file itself .IP 2. 3 The files matching the glob in \fI\%default_include\fP .IP 3. 3 The files matching the glob in \fI\%include\fP (if defined) .UNINDENT .sp Each successive step overrides any values defined in the previous steps. Therefore, any config options defined in one of the \fI\%default_include\fP files would override the same value in the master config file, and any options defined in \fI\%include\fP would override both. .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 Keepalive Settings .SS \fBtcp_keepalive\fP .sp Default: \fBTrue\fP .sp The tcp keepalive interval to set on TCP ports. This setting can be used to tune Salt connectivity issues in messy network environments with misbehaving firewalls. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C tcp_keepalive: True .ft P .fi .UNINDENT .UNINDENT .SS \fBtcp_keepalive_cnt\fP .sp Default: \fB\-1\fP .sp Sets the ZeroMQ TCP keepalive count. May be used to tune issues with minion disconnects. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C tcp_keepalive_cnt: \-1 .ft P .fi .UNINDENT .UNINDENT .SS \fBtcp_keepalive_idle\fP .sp Default: \fB300\fP .sp Sets ZeroMQ TCP keepalive idle. May be used to tune issues with minion disconnects. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C tcp_keepalive_idle: 300 .ft P .fi .UNINDENT .UNINDENT .SS \fBtcp_keepalive_intvl\fP .sp Default: \fB\-1\fP .sp Sets ZeroMQ TCP keepalive interval. May be used to tune issues with minion disconnects. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C tcp_keepalive_intvl\(aq: \-1 .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 generated by 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_ng: \- \(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 winrepo_remotes: \- 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 \fBwinrepo_refspecs\fP .sp New in version 2017.7.0. .sp Default: \fB[\(aq+refs/heads/*:refs/remotes/origin/*\(aq, \(aq+refs/tags/*:refs/tags/*\(aq]\fP .sp When fetching from remote repositories, by default Salt will fetch branches and tags. This parameter can be used to override the default and specify alternate refspecs to be fetched. This parameter works similarly to its GitFS counterpart, in that it can be configured both globally and for individual remotes. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C winrepo_refspecs: \- \(aq+refs/heads/*:refs/remotes/origin/*\(aq \- \(aq+refs/tags/*:refs/tags/*\(aq \- \(aq+refs/pull/*/head:refs/remotes/origin/pr/*\(aq \- \(aq+refs/pull/*/merge:refs/remotes/origin/merge/*\(aq .ft P .fi .UNINDENT .UNINDENT .SS Configure Master on Windows .sp The master on Windows requires no additional configuration. You can modify the master configuration by creating/editing the master config file located at \fBc:\esalt\econf\emaster\fP\&. The same configuration options available on Linux are available in Windows, as long as they apply. For example, SSH options wouldn\(aqt apply in Windows. The main differences are the file paths. If you are familiar with common salt paths, the following table may be useful: .TS center; |l|l|l|. _ T{ linux Paths T} T{ T} T{ Windows Paths T} _ T{ \fB/etc/salt\fP T} T{ \fB<\-\-\->\fP T} T{ \fBc:\esalt\econf\fP T} _ T{ \fB/\fP T} T{ \fB<\-\-\->\fP T} T{ \fBc:\esalt\fP T} _ .TE .sp So, for example, the master config file in Linux is \fB/etc/salt/master\fP\&. In Windows the master config file is \fBc:\esalt\econf\emaster\fP\&. The Linux path \fB/etc/salt\fP becomes \fBc:\esalt\econf\fP in Windows. .SS Common File Locations .TS center; |l|l|. _ T{ Linux Paths T} T{ Windows Paths T} _ T{ \fBconf_file: /etc/salt/master\fP T} T{ \fBconf_file: c:\esalt\econf\emaster\fP T} _ T{ \fBlog_file: /var/log/salt/master\fP T} T{ \fBlog_file: c:\esalt\evar\elog\esalt\emaster\fP T} _ T{ \fBpidfile: /var/run/salt\-master.pid\fP T} T{ \fBpidfile: c:\esalt\evar\erun\esalt\-master.pid\fP T} _ .TE .SS Common Directories .TS center; |l|l|. _ T{ Linux Paths T} T{ Windows Paths T} _ T{ \fBcachedir: /var/cache/salt/master\fP T} T{ \fBcachedir: c:\esalt\evar\ecache\esalt\emaster\fP T} _ T{ \fBextension_modules: /var/cache/salt/master/extmods\fP T} T{ \fBc:\esalt\evar\ecache\esalt\emaster\eextmods\fP T} _ T{ \fBpki_dir: /etc/salt/pki/master\fP T} T{ \fBpki_dir: c:\esalt\econf\epki\emaster\fP T} _ T{ \fBroot_dir: /\fP T} T{ \fBroot_dir: c:\esalt\fP T} _ T{ \fBsock_dir: /var/run/salt/master\fP T} T{ \fBsock_dir: c:\esalt\evar\erun\esalt\emaster\fP T} _ .TE .SS Roots .sp \fBfile_roots\fP .TS center; |l|l|. _ T{ Linux Paths T} T{ Windows Paths T} _ T{ \fB/srv/salt\fP T} T{ \fBc:\esalt\esrv\esalt\fP T} _ T{ \fB/srv/spm/salt\fP T} T{ \fBc:\esalt\esrv\espm\esalt\fP T} _ .TE .sp \fBpillar_roots\fP .TS center; |l|l|. _ T{ Linux Paths T} T{ Windows Paths T} _ T{ \fB/srv/pillar\fP T} T{ \fBc:\esalt\esrv\epillar\fP T} _ T{ \fB/srv/spm/pillar\fP T} T{ \fBc:\esalt\esrv\espm\epillar\fP T} _ .TE .SS Win Repo Settings .TS center; |l|l|. _ T{ Linux Paths T} T{ Windows Paths T} _ T{ \fBwinrepo_dir: /srv/salt/win/repo\fP T} T{ \fBwinrepo_dir: c:\esalt\esrv\esalt\ewin\erepo\fP T} _ T{ \fBwinrepo_dir_ng: /srv/salt/win/repo\-ng\fP T} T{ \fBwinrepo_dir_ng: c:\esalt\esrv\esalt\ewin\erepo\-ng\fP T} _ .TE .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 IP address of the master. See \fI\%ipv6\fP for IPv6 connections to the master. .sp Default: \fBsalt\fP .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C master: salt .ft P .fi .UNINDENT .UNINDENT .SS master:port Syntax .sp New in version 2015.8.0. .sp The \fBmaster\fP config option can also be set to use the master\(aqs IP in conjunction with a port number by default. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C master: localhost:1234 .ft P .fi .UNINDENT .UNINDENT .sp For IPv6 formatting with a port, remember to add brackets around the IP address before adding the port and enclose the line in single quotes to make it a string: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C master: \(aq[2001:db8:85a3:8d3:1319:8a2e:370:7348]:1234\(aq .ft P .fi .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 If a port is specified in the \fBmaster\fP as well as \fI\%master_port\fP, the \fBmaster_port\fP setting will be overridden by the \fBmaster\fP configuration. .UNINDENT .UNINDENT .SS List of Masters Syntax .sp The option 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 \fBcolor\fP .sp Default: \fBTrue\fP .sp By default output is colored. To disable colored output, set the color value to \fBFalse\fP\&. .SS \fBipv6\fP .sp Default: \fBNone\fP .sp Whether the master should be connected over IPv6. By default salt minion will try to automatically detect IPv6 connectivity to master. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C ipv6: True .ft P .fi .UNINDENT .UNINDENT .SS \fBmaster_uri_format\fP .sp New in version 2015.8.0. .sp Specify the format in which the master address will be evaluated. Valid options are \fBdefault\fP or \fBip_only\fP\&. If \fBip_only\fP is specified, then the master address will not be split into IP and PORT, so be sure that only an IP (or domain name) is set in the \fI\%master\fP configuration setting. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C master_uri_format: ip_only .ft P .fi .UNINDENT .UNINDENT .SS \fBmaster_tops_first\fP .sp New in version 2018.3.0. .sp Default: \fBFalse\fP .sp SLS targets defined using the Master Tops system are normally executed \fIafter\fP any matches defined in the Top File\&. Set this option to \fBTrue\fP to have the minion execute the Master Tops states first. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C master_tops_first: True .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 \fBenable_legacy_startup_events\fP .sp New in version 2019.2.0. .sp Default: \fBTrue\fP .sp When a minion starts up it sends a notification on the event bus with a tag that looks like this: \fBsalt/minion//start\fP\&. For historical reasons the minion also sends a similar event with an event tag like this: \fBminion_start\fP\&. This duplication can cause a lot of clutter on the event bus when there are many minions. Set \fBenable_legacy_startup_events: False\fP in the minion config to ensure only the \fBsalt/minion//start\fP events are sent. Beginning with the \fB3001\fP Salt release this option will default to \fBFalse\fP\&. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C enable_legacy_startup_events: True .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 Deprecated since version 2019.2.0. .sp Default: \fBFalse\fP .sp \fBWARNING:\fP .INDENT 0.0 .INDENT 3.5 This option has been deprecated in Salt \fB2019.2.0\fP\&. Please use \fI\%random_master\fP instead. .UNINDENT .UNINDENT .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C master_shuffle: True .ft P .fi .UNINDENT .UNINDENT .SS \fBrandom_master\fP .sp New in version 2014.7.0. .sp Changed in version 2019.2.0: The \fI\%master_failback\fP option can be used in conjunction with \fBrandom_master\fP to force the minion to fail back to the first master in the list if the first master is back online. Note that \fI\%master_type\fP must be set to \fBfailover\fP in order for the \fBmaster_failback\fP setting to work. .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 \fBrandom.shuffle\fP method. .sp If multiple masters are specified in the \(aqmaster\(aq setting as a list, the default behavior is to always try to connect to them in the order they are listed. If \fBrandom_master\fP is set to True, the order will be randomized instead upon Minion startup. This can be helpful in distributing the load of many minions executing \fBsalt\-call\fP requests, for example, from a cron job. If only one master is listed, this setting is ignored and a warning is logged. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C random_master: True .ft P .fi .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 When the \fBfailover\fP, \fBmaster_failback\fP, and \fBrandom_master\fP options are used together, only the "secondary masters" will be shuffled. The first master in the list is ignored in the \fBrandom.shuffle\fP call. See \fI\%master_failback\fP for more information. .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 \fBretry_dns_count\fP .sp New in version 2018.3.4. .sp Default: \fBNone\fP .sp Set the number of attempts to perform when resolving the master hostname if name resolution fails. By default the minion will retry indefinitely. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C retry_dns_count: 3 .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 \fBpublish_port\fP .sp Default: \fB4505\fP .sp The port of the master publish server, this needs to coincide with the publish_port option on the Salt master. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C publish_port: 4505 .ft P .fi .UNINDENT .UNINDENT .SS \fBsource_interface_name\fP .sp New in version 2018.3.0. .sp The name of the interface to use when establishing the connection to the Master. .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 If multiple IP addresses are configured on the named interface, the first one will be selected. In that case, for a better selection, consider using the \fI\%source_address\fP option. .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 To use an IPv6 address from the named interface, make sure the option \fI\%ipv6\fP is enabled, i.e., \fBipv6: true\fP\&. .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 If the interface is down, it will avoid using it, and the Minion will bind to \fB0.0.0.0\fP (all interfaces). .UNINDENT .UNINDENT .sp \fBWARNING:\fP .INDENT 0.0 .INDENT 3.5 This option requires modern version of the underlying libraries used by the selected transport: .INDENT 0.0 .IP \(bu 2 \fBzeromq\fP requires \fBpyzmq\fP >= 16.0.1 and \fBlibzmq\fP >= 4.1.6 .IP \(bu 2 \fBtcp\fP requires \fBtornado\fP >= 4.5 .UNINDENT .UNINDENT .UNINDENT .sp Configuration example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C source_interface_name: bond0.1234 .ft P .fi .UNINDENT .UNINDENT .SS \fBsource_address\fP .sp New in version 2018.3.0. .sp The source IP address or the domain name to be used when connecting the Minion to the Master. See \fI\%ipv6\fP for IPv6 connections to the Master. .sp \fBWARNING:\fP .INDENT 0.0 .INDENT 3.5 This option requires modern version of the underlying libraries used by the selected transport: .INDENT 0.0 .IP \(bu 2 \fBzeromq\fP requires \fBpyzmq\fP >= 16.0.1 and \fBlibzmq\fP >= 4.1.6 .IP \(bu 2 \fBtcp\fP requires \fBtornado\fP >= 4.5 .UNINDENT .UNINDENT .UNINDENT .sp Configuration example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C source_address: if\-bond0\-1234.sjc.us\-west.internal .ft P .fi .UNINDENT .UNINDENT .SS \fBsource_ret_port\fP .sp New in version 2018.3.0. .sp The source port to be used when connecting the Minion to the Master ret server. .sp \fBWARNING:\fP .INDENT 0.0 .INDENT 3.5 This option requires modern version of the underlying libraries used by the selected transport: .INDENT 0.0 .IP \(bu 2 \fBzeromq\fP requires \fBpyzmq\fP >= 16.0.1 and \fBlibzmq\fP >= 4.1.6 .IP \(bu 2 \fBtcp\fP requires \fBtornado\fP >= 4.5 .UNINDENT .UNINDENT .UNINDENT .sp Configuration example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C source_ret_port: 49017 .ft P .fi .UNINDENT .UNINDENT .SS \fBsource_publish_port\fP .sp New in version 2018.3.0. .sp The source port to be used when connecting the Minion to the Master publish server. .sp \fBWARNING:\fP .INDENT 0.0 .INDENT 3.5 This option requires modern version of the underlying libraries used by the selected transport: .INDENT 0.0 .IP \(bu 2 \fBzeromq\fP requires \fBpyzmq\fP >= 16.0.1 and \fBlibzmq\fP >= 4.1.6 .IP \(bu 2 \fBtcp\fP requires \fBtornado\fP >= 4.5 .UNINDENT .UNINDENT .UNINDENT .sp Configuration example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C source_publish_port: 49018 .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 \fI\%id\fP 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 \fBminion_id_remove_domain\fP .sp New in version 3000. .sp Default: \fBFalse\fP .sp Remove a domain when the minion id is generated as a fully qualified domain name (either by the user provided \fBid_function\fP, or by Salt). This is useful when the minions shall be named like hostnames. Can be a single domain (to prevent name clashes), or True, to remove all domains. .INDENT 0.0 .TP .B Examples: .INDENT 7.0 .IP \(bu 2 minion_id_remove_domain = foo.org \- FQDN = king_bob.foo.org \-\-> minion_id = king_bob \- FQDN = king_bob.bar.org \-\-> minion_id = king_bob.bar.org .IP \(bu 2 minion_id_remove_domain = True \- FQDN = king_bob.foo.org \-\-> minion_id = king_bob \- FQDN = king_bob.bar.org \-\-> minion_id = king_bob .UNINDENT .UNINDENT .sp For more information, please see \fI\%issue #49212\fP and \fI\%PR #49378\fP\&. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C minion_id_remove_domain: foo.org .ft P .fi .UNINDENT .UNINDENT .SS \fBminion_id_lowercase\fP .sp Default: \fBFalse\fP .sp Convert minion id to lowercase when it is being generated. Helpful when some hosts get the minion id in uppercase. Cached ids will remain the same and not converted. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C minion_id_lowercase: True .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 \fBcolor_theme\fP .sp Default: \fB""\fP .sp Specifies a path to the color theme to use for colored command line output. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C color_theme: /etc/salt/color_theme .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_blacklist\fP .sp Default: \fB[]\fP .sp Each grains key will be compared against each of the expressions in this list. Any keys which match will be filtered from the grains. Exact matches, glob matches, and regular expressions are supported. .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 Some states and execution modules depend on grains. Filtering may cause them to be unavailable or run unreliably. .UNINDENT .UNINDENT .sp New in version 3000. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C grains_blacklist: \- cpu_flags \- zmq* \- ipv[46] .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 \fBgrains_cache\fP to \fBTrue\fP\&. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C grains_cache: False .ft P .fi .UNINDENT .UNINDENT .SS \fBgrains_cache_expiration\fP .sp Default: \fB300\fP .sp 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 \fI\%grains_cache\fP is not enabled. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C grains_cache_expiration: 300 .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 {"custom1": {"k1": "v1"}} def custom1_k2(): return {"custom1": {"k2": "v2"}} .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 \fBgrains_refresh_every\fP .sp Default: \fB0\fP .sp The \fBgrains_refresh_every\fP 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. .sp Note: This value is expressed in minutes. .sp A value of 10 minutes is a reasonable default. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C grains_refresh_every: 0 .ft P .fi .UNINDENT .UNINDENT .SS \fBmetadata_server_grains\fP .sp New in version 2017.7.0. .sp Default: \fBFalse\fP .sp Set this option to enable gathering of cloud metadata from \fBhttp://169.254.169.254/latest\fP for use in grains (see \fBhere\fP for more information). .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C metadata_server_grains: True .ft P .fi .UNINDENT .UNINDENT .SS \fBfibre_channel_grains\fP .sp Default: \fBFalse\fP .sp The \fBfibre_channel_grains\fP setting will enable the \fBfc_wwn\fP grain for Fibre Channel WWN\(aqs on the minion. Since this grain is expensive, it is disabled by default. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C fibre_channel_grains: True .ft P .fi .UNINDENT .UNINDENT .SS \fBiscsi_grains\fP .sp Default: \fBFalse\fP .sp The \fBiscsi_grains\fP setting will enable the \fBiscsi_iqn\fP grain on the minion. Since this grain is expensive, it is disabled by default. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C iscsi_grains: True .ft P .fi .UNINDENT .UNINDENT .SS \fBnvme_grains\fP .sp Default: \fBFalse\fP .sp The \fBnvme_grains\fP setting will enable the \fBnvme_nqn\fP grain on the minion. Since this grain is expensive, it is disabled by default. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C nvme_grains: True .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 \fBmine_interval\fP .sp Default: \fB60\fP .sp The number of minutes between mine updates. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C mine_interval: 60 .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 \fBenable_fqdns_grains\fP .sp Default: \fBTrue\fP .sp In order to calculate the fqdns grain, all the IP addresses from the minion are processed with underlying calls to \fBsocket.gethostbyaddr\fP which can take 5 seconds to be released (after reaching \fBsocket.timeout\fP) when there is no fqdn for that IP. These calls to \fBsocket.gethostbyaddr\fP are processed asynchronously, however, it still adds 5 seconds every time grains are generated if an IP does not resolve. In Windows grains are regenerated each time a new process is spawned. Therefore, the default for Windows is \fBFalse\fP\&. In many cases this value does not make sense to include for proxy minions as it will be FQDN for the host running the proxy minion process, so the default for proxy minions is \fBFalse\(ga\fP\&. All other OSes default to \fBTrue\fP\&. This options was added \fI\%here\fP\&. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C enable_fqdns_grains: False .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 minion can take a while to start up when lspci and/or dmidecode is used to populate the grains for the minion, so this can be set to \fBFalse\fP if you do not need these grains. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C enable_gpu_grains: False .ft P .fi .UNINDENT .UNINDENT .SS \fBoutputter_dirs\fP .sp Default: \fB[]\fP .sp A list of additional directories to search for salt outputters in. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C outputter_dirs: [] .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 \fBrejected_retry\fP .sp Default: \fBFalse\fP .sp If the master rejects the minion\(aqs public key, retry instead of exiting. Rejected keys will be handled the same as waiting on acceptance. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C rejected_retry: False .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 \fI\%auth_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 \fBping_interval\fP .sp Default: \fB0\fP .sp Instructs the minion to ping its master(s) every n number of minutes. Used primarily as a mitigation technique against minion disconnects. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C ping_interval: 0 .ft P .fi .UNINDENT .UNINDENT .SS \fBrandom_startup_delay\fP .sp Default: \fB0\fP .sp The maximum bound for an interval in which a minion will randomly sleep upon starting up prior to attempting to connect to a master. This can be used to splay connection attempts for cases where many minions starting up at once may place undue load on a master. .sp For example, setting this to \fB5\fP will tell a minion to sleep for a value between \fB0\fP and \fB5\fP seconds. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C random_startup_delay: 5 .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. \fBipc_mode\fP is set 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 and \fBtcp\fP (experimental). This setting has a significant impact on performance and should not be changed unless you know what you are doing! .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 \fBhttp_connect_timeout\fP .sp New in version 2019.2.0. .sp Default: \fB20\fP .sp HTTP connection timeout in seconds. Applied when fetching files using tornado back\-end. Should be greater than overall download time. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C http_connect_timeout: 20 .ft P .fi .UNINDENT .UNINDENT .SS \fBhttp_request_timeout\fP .sp New in version 2015.8.0. .sp Default: \fB3600\fP .sp HTTP request timeout in seconds. Applied when fetching files using tornado back\-end. Should be greater than overall download time. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C http_request_timeout: 3600 .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 \fBno_proxy\fP .sp New in version 2019.2.0. .sp Default: \fB[]\fP .sp List of hosts to bypass HTTP proxy .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 This key does nothing unless proxy_host etc is configured, it does not support any kind of wildcards. .UNINDENT .UNINDENT .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C no_proxy: [ \(aq127.0.0.1\(aq, \(aqfoo.tld\(aq ] .ft P .fi .UNINDENT .UNINDENT .SS \fBuse_yamlloader_old\fP .sp New in version 2019.2.1. .sp Default: \fBFalse\fP .sp Use the pre\-2019.2 YAML renderer. Uses legacy YAML rendering to support some legacy inline data structures. See the 2019.2.1 release notes for more details. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C use_yamlloader_old: False .ft P .fi .UNINDENT .UNINDENT .SS Docker Configuration .SS \fBdocker.update_mine\fP .sp New in version 2017.7.8,2018.3.3. .sp Changed in version 2019.2.0: The default value is now \fBFalse\fP .sp Default: \fBTrue\fP .sp If enabled, when containers are added, removed, stopped, started, etc., the mine will be updated with the results of \fBdocker.ps verbose=True all=True host=True\fP\&. This mine data is used by \fBmine.get_docker\fP\&. Set this option to \fBFalse\fP to keep Salt from updating the mine with this information. .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 This option can also be set in Grains or Pillar data, with Grains overriding Pillar and the minion config file overriding Grains. .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 Disabling this will of course keep \fBmine.get_docker\fP from returning any information for a given minion. .UNINDENT .UNINDENT .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C docker.update_mine: False .ft P .fi .UNINDENT .UNINDENT .SS \fBdocker.compare_container_networks\fP .sp New in version 2018.3.0. .sp Default: \fB{\(aqstatic\(aq: [\(aqAliases\(aq, \(aqLinks\(aq, \(aqIPAMConfig\(aq], \(aqautomatic\(aq: [\(aqIPAddress\(aq, \(aqGateway\(aq, \(aqGlobalIPv6Address\(aq, \(aqIPv6Gateway\(aq]}\fP .sp Specifies which keys are examined by \fBdocker.compare_container_networks\fP\&. .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 This should not need to be modified unless new features added to Docker result in new keys added to the network configuration which must be compared to determine if two containers have different network configs. This config option exists solely as a way to allow users to continue using Salt to manage their containers after an API change, without waiting for a new Salt release to catch up to the changes in the Docker API. .UNINDENT .UNINDENT .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C docker.compare_container_networks: static: \- Aliases \- Links \- IPAMConfig automatic: \- IPAddress \- Gateway \- GlobalIPv6Address \- IPv6Gateway .ft P .fi .UNINDENT .UNINDENT .SS \fBoptimization_order\fP .sp Default: \fB[0, 1, 2]\fP .sp In cases where Salt is distributed without .py files, this option determines the priority of optimization level(s) Salt\(aqs module loader should prefer. .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 This option is only supported on Python 3.5+. .UNINDENT .UNINDENT .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C optimization_order: \- 2 \- 0 \- 1 .ft P .fi .UNINDENT .UNINDENT .SS Minion Execution Module Management .SS \fBdisable_modules\fP .sp Default: \fB[]\fP (all execution 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. .sp However, 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 lower 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. If enabled, only execution modules in this list will be loaded and executed on the minion. .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 \fButils_dirs\fP .sp Default: \fB[]\fP .sp A list of extra directories to search for Salt utilities .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C utils_dirs: \- /var/lib/salt/utils .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 \fBmodules_max_memory\fP .sp Default: \fB\-1\fP .sp Specify a max size (in bytes) for modules on import. This feature is currently only supported on *NIX operating systems and requires psutil. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C modules_max_memory: \-1 .ft P .fi .UNINDENT .UNINDENT .SS \fBextmod_whitelist/extmod_blacklist\fP .sp New in version 2017.7.0. .sp By using this dictionary, the modules that are synced to the minion\(aqs extmod cache using \fIsaltutil.sync_*\fP can be limited. If nothing is set to a specific type, then all modules are accepted. To block all modules of a specific type, whitelist an empty list. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C extmod_whitelist: modules: \- custom_module engines: \- custom_engine pillars: [] extmod_blacklist: modules: \- specific_module .ft P .fi .UNINDENT .UNINDENT .sp Valid options: .INDENT 0.0 .INDENT 3.5 .INDENT 0.0 .IP \(bu 2 beacons .IP \(bu 2 clouds .IP \(bu 2 sdb .IP \(bu 2 modules .IP \(bu 2 states .IP \(bu 2 grains .IP \(bu 2 renderers .IP \(bu 2 returners .IP \(bu 2 proxy .IP \(bu 2 engines .IP \(bu 2 output .IP \(bu 2 utils .IP \(bu 2 pillar .UNINDENT .UNINDENT .UNINDENT .SS Top File Settings .sp These parameters only have an effect if running a masterless minion. .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 \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\&. Note that, aside from the \fBbase\fP environment\(aqs top file, any sections in top files that do not match that top file\(aqs environment will be ignored. So, for example, a section for the \fBqa\fP environment would be ignored if it appears in the \fBdev\fP environment\(aqs top file. To keep use cases like this from being ignored, use the \fBmerge_all\fP strategy. .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 \fBstartup_states\fP .sp Default: \fB\(aq\(aq\fP .sp States to run when the minion daemon starts. To enable, set \fBstartup_states\fP to: .INDENT 0.0 .IP \(bu 2 \fBhighstate\fP: Execute state.highstate .IP \(bu 2 \fBsls\fP: Read in the sls_list option and execute the named sls files .IP \(bu 2 \fBtop\fP: Read top_file option and execute based on that file on the Master .UNINDENT .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C startup_states: \(aq\(aq .ft P .fi .UNINDENT .UNINDENT .SS \fBsls_list\fP .sp Default: \fB[]\fP .sp List of states to run when the minion starts up if \fBstartup_states\fP is set to \fBsls\fP\&. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C sls_list: \- edit.vim \- hyper .ft P .fi .UNINDENT .UNINDENT .SS \fBstart_event_grains\fP .sp Default: \fB[]\fP .sp List of grains to pass in start event when minion starts up. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C start_event_grains: \- machine_id \- uuid .ft P .fi .UNINDENT .UNINDENT .SS \fBtop_file\fP .sp Default: \fB\(aq\(aq\fP .sp Top file to execute if \fBstartup_states\fP is set to \fBtop\fP\&. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C top_file: \(aq\(aq .ft P .fi .UNINDENT .UNINDENT .SS State Management Settings .SS \fBrenderer\fP .sp Default: \fBjinja|yaml\fP .sp The default renderer used for local state executions .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C renderer: jinja|json .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 controls which results will be output full multi line: .INDENT 0.0 .IP \(bu 2 \fBfull\fP, \fBterse\fP \- each state will be full/terse .IP \(bu 2 \fBmixed\fP \- only states with errors will be full .IP \(bu 2 \fBchanges\fP \- states with changes and errors will be full .UNINDENT .sp \fBfull_id\fP, \fBmixed_id\fP, \fBchanges_id\fP and \fBterse_id\fP are also allowed; when set, the state ID will be used as name in the output. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C state_output: full .ft P .fi .UNINDENT .UNINDENT .SS \fBstate_output_diff\fP .sp Default: \fBFalse\fP .sp 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. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C state_output_diff: False .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 .SS \fBclean_dynamic_modules\fP .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 .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 If \fBextmod_whitelist\fP is specified, modules which are not whitelisted will also be cleaned here. .UNINDENT .UNINDENT .SS \fBsaltenv\fP .sp Changed in version 2018.3.0: Renamed from \fBenvironment\fP to \fBsaltenv\fP\&. If \fBenvironment\fP is used, \fBsaltenv\fP will take its value. If both are used, \fBenvironment\fP will be ignored and \fBsaltenv\fP will be used. .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 saltenv: dev .ft P .fi .UNINDENT .UNINDENT .SS \fBlock_saltenv\fP .sp New in version 2018.3.0. .sp Default: \fBFalse\fP .sp For purposes of running states, this option prevents using the \fBsaltenv\fP argument to manually set the environment. This is useful to keep a minion which has the \fI\%saltenv\fP option set to \fBdev\fP from running states from an environment other than \fBdev\fP\&. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C lock_saltenv: True .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 \fBon_demand_ext_pillar\fP .sp New in version 2016.3.6,2016.11.3,2017.7.0. .sp Default: \fB[\(aqlibvirt\(aq, \(aqvirtkey\(aq]\fP .sp When using a local \fI\%file_client\fP, this option controls which external pillars are permitted to be used on\-demand using \fBpillar.ext\fP\&. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C on_demand_ext_pillar: \- libvirt \- virtkey \- git .ft P .fi .UNINDENT .UNINDENT .sp \fBWARNING:\fP .INDENT 0.0 .INDENT 3.5 This will allow a masterless minion to request specific pillar data via \fBpillar.ext\fP, and may be considered a security risk. However, pillar data generated in this way will not affect the in\-memory pillar data, so this risk is limited to instances in which states/modules/etc. (built\-in or custom) rely upon pillar data generated by \fBpillar.ext\fP\&. .UNINDENT .UNINDENT .SS \fBdecrypt_pillar\fP .sp New in version 2017.7.0. .sp Default: \fB[]\fP .sp A list of paths to be recursively decrypted during pillar compilation. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C decrypt_pillar: \- \(aqfoo:bar\(aq: gpg \- \(aqlorem:ipsum:dolor\(aq .ft P .fi .UNINDENT .UNINDENT .sp Entries in this list can be formatted either as a simple string, or as a key/value pair, with the key being the pillar location, and the value being the renderer to use for pillar decryption. If the former is used, the renderer specified by \fI\%decrypt_pillar_default\fP will be used. .SS \fBdecrypt_pillar_delimiter\fP .sp New in version 2017.7.0. .sp Default: \fB:\fP .sp The delimiter used to distinguish nested data structures in the \fI\%decrypt_pillar\fP option. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C decrypt_pillar_delimiter: \(aq|\(aq decrypt_pillar: \- \(aqfoo|bar\(aq: gpg \- \(aqlorem|ipsum|dolor\(aq .ft P .fi .UNINDENT .UNINDENT .SS \fBdecrypt_pillar_default\fP .sp New in version 2017.7.0. .sp Default: \fBgpg\fP .sp The default renderer used for decryption, if one is not specified for a given pillar key in \fI\%decrypt_pillar\fP\&. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C decrypt_pillar_default: my_custom_renderer .ft P .fi .UNINDENT .UNINDENT .SS \fBdecrypt_pillar_renderers\fP .sp New in version 2017.7.0. .sp Default: \fB[\(aqgpg\(aq]\fP .sp List of renderers which are permitted to be used for pillar decryption. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C decrypt_pillar_renderers: \- gpg \- my_custom_renderer .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: dev .ft P .fi .UNINDENT .UNINDENT .SS \fBpillarenv_from_saltenv\fP .sp New in version 2017.7.0. .sp Default: \fBFalse\fP .sp When set to \fBTrue\fP, the \fI\%pillarenv\fP value will assume the value of the effective saltenv when running states. This essentially makes \fBsalt \(aq*\(aq state.sls mysls saltenv=dev\fP equivalent to \fBsalt \(aq*\(aq state.sls mysls saltenv=dev pillarenv=dev\fP\&. If \fI\%pillarenv\fP is set, either in the minion config file or via the CLI, it will override this option. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C pillarenv_from_saltenv: True .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 \fBpass_to_ext_pillars\fP .sp Specify a list of configuration keys whose values are to be passed to external pillar functions. .sp Suboptions can be specified using the \(aq:\(aq notation (i.e. \fBoption:suboption\fP) .sp The values are merged and included in the \fBextra_minion_data\fP optional parameter of the external pillar function. The \fBextra_minion_data\fP parameter is passed only to the external pillar functions that have it explicitly specified in their definition. .sp If the config contains .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C opt1: value1 opt2: subopt1: value2 subopt2: value3 pass_to_ext_pillars: \- opt1 \- opt2: subopt1 .ft P .fi .UNINDENT .UNINDENT .sp the \fBextra_minion_data\fP parameter will be .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C {"opt1": "value1", "opt2": {"subopt1": "value2"}} .ft P .fi .UNINDENT .UNINDENT .SS \fBssh_merge_pillar\fP .sp New in version 2018.3.2. .sp Default: \fBTrue\fP .sp Merges the compiled pillar data with the pillar data already available globally. This is useful when using \fBsalt\-ssh\fP or \fBsalt\-call \-\-local\fP and overriding the pillar data in a state file: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C apply_showpillar: module.run: \- name: state.apply \- mods: \- showpillar \- kwargs: pillar: test: "foo bar" .ft P .fi .UNINDENT .UNINDENT .sp If set to \fBTrue\fP, the \fBshowpillar\fP state will have access to the global pillar data. .sp If set to \fBFalse\fP, only the overriding pillar data will be available to the \fBshowpillar\fP state. .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 as \fBmaster.pub\fP 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 \fBkeysize\fP .sp Default: \fB2048\fP .sp The size of key that should be generated when creating new keys. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C keysize: 2048 .ft P .fi .UNINDENT .UNINDENT .SS \fBpermissive_pki_access\fP .sp Default: \fBFalse\fP .sp 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. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C permissive_pki_access: False .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 \fBautosign_grains\fP .sp New in version 2018.3.0. .sp Default: \fBnot defined\fP .sp The grains that should be sent to the master on authentication to decide if the minion\(aqs key should be accepted automatically. .sp Please see the Autoaccept Minions from Grains documentation for more information. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C autosign_grains: \- uuid \- server_id .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 Reactor Settings .SS \fBreactor\fP .sp Default: \fB[]\fP .sp Defines a salt reactor. See the Reactor documentation for more information. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C reactor: [] .ft P .fi .UNINDENT .UNINDENT .SS \fBreactor_refresh_interval\fP .sp Default: \fB60\fP .sp The TTL for the cache of the reactor configuration. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C reactor_refresh_interval: 60 .ft P .fi .UNINDENT .UNINDENT .SS \fBreactor_worker_threads\fP .sp Default: \fB10\fP .sp The number of workers for the runner/wheel in the reactor. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C reactor_worker_threads: 10 .ft P .fi .UNINDENT .UNINDENT .SS \fBreactor_worker_hwm\fP .sp Default: \fB10000\fP .sp The queue size for workers in the reactor. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C reactor_worker_hwm: 10000 .ft P .fi .UNINDENT .UNINDENT .SS Thread Settings .SS \fBmultiprocessing\fP .sp Default: \fBTrue\fP .sp If \fBmultiprocessing\fP is enabled when a minion receives a publication a new process is spawned and the command is executed therein. Conversely, if \fBmultiprocessing\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 \fBprocess_count_max\fP .sp New in version 2018.3.0. .sp Default: \fB\-1\fP .sp Limit the maximum amount of processes or threads created by \fBsalt\-minion\fP\&. This is useful to avoid resource exhaustion in case the minion receives more publications than it is able to handle, as it limits the number of spawned processes or threads. \fB\-1\fP is the default and disables the limit. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C process_count_max: \-1 .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: \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 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 \fBlog_rotate_max_bytes\fP .sp Default: \fB0\fP .sp The maximum number of bytes a single log file may contain before it is rotated. A value of 0 disables this feature. Currently only supported on Windows. On other platforms, use an external tool such as \(aqlogrotate\(aq to manage log files. \fBlog_rotate_max_bytes\fP .SS \fBlog_rotate_backup_count\fP .sp Default: \fB0\fP .sp The number of backup files to keep when rotating log files. Only used if \fI\%log_rotate_max_bytes\fP is greater than 0. Currently only supported on Windows. On other platforms, use an external tool such as \(aqlogrotate\(aq to manage log files. \fBlog_rotate_backup_count\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 \fBtcp_authentication_retries\fP .sp Default: \fB5\fP .sp The number of times to retry authenticating with the salt master when it comes back online. .sp Zeromq does a lot to make sure when connections come back online that they reauthenticate. The tcp transport should try to connect with a new connection if the old one times out on reauthenticating. .sp \fI\-1\fP for infinite tries. .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 .sp Configuration can be loaded from multiple files. The order in which this is done is: .INDENT 0.0 .IP 1. 3 The minion config file itself .IP 2. 3 The files matching the glob in \fI\%default_include\fP .IP 3. 3 The files matching the glob in \fI\%include\fP (if defined) .UNINDENT .sp Each successive step overrides any values defined in the previous steps. Therefore, any config options defined in one of the \fI\%default_include\fP files would override the same value in the minion config file, and any options defined in \fI\%include\fP would override both. .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 Keepalive Settings .SS \fBtcp_keepalive\fP .sp Default: \fBTrue\fP .sp The tcp keepalive interval to set on TCP ports. This setting can be used to tune Salt connectivity issues in messy network environments with misbehaving firewalls. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C tcp_keepalive: True .ft P .fi .UNINDENT .UNINDENT .SS \fBtcp_keepalive_cnt\fP .sp Default: \fB\-1\fP .sp Sets the ZeroMQ TCP keepalive count. May be used to tune issues with minion disconnects. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C tcp_keepalive_cnt: \-1 .ft P .fi .UNINDENT .UNINDENT .SS \fBtcp_keepalive_idle\fP .sp Default: \fB300\fP .sp Sets ZeroMQ TCP keepalive idle. May be used to tune issues with minion disconnects. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C tcp_keepalive_idle: 300 .ft P .fi .UNINDENT .UNINDENT .SS \fBtcp_keepalive_intvl\fP .sp Default: \fB\-1\fP .sp Sets ZeroMQ TCP keepalive interval. May be used to tune issues with minion disconnects. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C tcp_keepalive_intvl\(aq: \-1 .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 Windows Software Repo Settings .sp These settings apply to all minions, whether running in masterless or master\-minion mode. .SS \fBwinrepo_cache_expire_min\fP .sp New in version 2016.11.0. .sp Default: \fB1800\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 \fBwinrepo_source_dir\fP .sp Default: \fBsalt://win/repo\-ng/\fP .sp The source location for the winrepo sls files. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C winrepo_source_dir: salt://win/repo\-ng/ .ft P .fi .UNINDENT .UNINDENT .SS Standalone Minion Windows Software Repo Settings .sp The following settings are for configuring the Windows Software Repository (winrepo) on a masterless minion. To run in masterless minion mode, set the \fI\%file_client\fP to \fBlocal\fP or run \fBsalt\-call\fP with the \fB\-\-local\fP option .sp \fBIMPORTANT:\fP .INDENT 0.0 .INDENT 3.5 These config options are only valid for minions running in masterless mode .UNINDENT .UNINDENT .SS \fBwinrepo_dir\fP .sp Changed in version 2015.8.0: Renamed from \fBwin_repo\fP to \fBwinrepo_dir\fP\&. 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 \fI\%file_roots\fP where winrepo files are kept. This is also where the \fI\%winrepo_remotes\fP are cloned to by \fBwinrepo.update_git_repos\fP\&. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C winrepo_dir: \(aqD:\ewinrepo\(aq .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: \fBC:\esalt\esrv\esalt\ewin\erepo\-ng\fP .sp Location on the minion \fI\%file_roots\fP where winrepo files are kept for 2018.8.0 and later minions. This is also where the \fI\%winrepo_remotes\fP are cloned to by \fBwinrepo.update_git_repos\fP\&. .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_cachefile\fP to \fBwinrepo_cachefile\fP\&. Also, this option did not have a default value until this version. .sp Default: \fBwinrepo.p\fP .sp The name of the winrepo cache file. The file will be created at root of the directory specified by \fI\%winrepo_dir_ng\fP\&. .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 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_ng: \- \(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 Configuring the Salt Proxy 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\-proxy\fP is configured via the proxy configuration file. .sp \fBSEE ALSO:\fP .INDENT 0.0 .INDENT 3.5 example proxy 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 proxy knows where to locate its master. .sp By default, the salt\-proxy configuration will be in \fB/etc/salt/proxy\fP\&. A notable exception is FreeBSD, where the configuration will be in \fB/usr/local/etc/salt/proxy\fP\&. .SS Proxy\-specific Configuration Options .SS \fBadd_proxymodule_to_opts\fP .sp New in version 2015.8.2. .sp Changed in version 2016.3.0. .sp Default: \fBFalse\fP .sp Add the proxymodule LazyLoader object to opts. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C add_proxymodule_to_opts: True .ft P .fi .UNINDENT .UNINDENT .SS \fBproxy_merge_grains_in_module\fP .sp New in version 2016.3.0. .sp Changed in version 2017.7.0. .sp Default: \fBTrue\fP .sp If a proxymodule has a function called \fBgrains\fP, then call it during regular grains loading and merge the results with the proxy\(aqs grains dictionary. Otherwise it is assumed that the module calls the grains function in a custom way and returns the data elsewhere. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C proxy_merge_grains_in_module: False .ft P .fi .UNINDENT .UNINDENT .SS \fBproxy_keep_alive\fP .sp New in version 2017.7.0. .sp Default: \fBTrue\fP .sp Whether the connection with the remote device should be restarted when dead. The proxy module must implement the \fBalive\fP function, otherwise the connection is considered alive. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C proxy_keep_alive: False .ft P .fi .UNINDENT .UNINDENT .SS \fBproxy_keep_alive_interval\fP .sp New in version 2017.7.0. .sp Default: \fB1\fP .sp The frequency of keepalive checks, in minutes. It requires the \fI\%proxy_keep_alive\fP option to be enabled (and the proxy module to implement the \fBalive\fP function). .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C proxy_keep_alive_interval: 5 .ft P .fi .UNINDENT .UNINDENT .SS \fBproxy_always_alive\fP .sp New in version 2017.7.0. .sp Default: \fBTrue\fP .sp Whether the proxy should maintain the connection with the remote device. Similarly to \fI\%proxy_keep_alive\fP, this option is very specific to the design of the proxy module. When \fI\%proxy_always_alive\fP is set to \fBFalse\fP, the connection with the remote device is not maintained and has to be closed after every command. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C proxy_always_alive: False .ft P .fi .UNINDENT .UNINDENT .SS \fBproxy_merge_pillar_in_opts\fP .sp New in version 2017.7.3. .sp Default: \fBFalse\fP\&. .sp Whether the pillar data to be merged into the proxy configuration options. As multiple proxies can run on the same server, we may need different configuration options for each, while there\(aqs one single configuration file. The solution is merging the pillar data of each proxy minion into the opts. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C proxy_merge_pillar_in_opts: True .ft P .fi .UNINDENT .UNINDENT .SS \fBproxy_deep_merge_pillar_in_opts\fP .sp New in version 2017.7.3. .sp Default: \fBFalse\fP\&. .sp Deep merge of pillar data into configuration opts. This option is evaluated only when \fBproxy_merge_pillar_in_opts\fP is enabled. .SS \fBproxy_merge_pillar_in_opts_strategy\fP .sp New in version 2017.7.3. .sp Default: \fBsmart\fP\&. .sp The strategy used when merging pillar configuration into opts. This option is evaluated only when \fBproxy_merge_pillar_in_opts\fP is enabled. .SS \fBproxy_mines_pillar\fP .sp New in version 2017.7.3. .sp Default: \fBTrue\fP\&. .sp Allow enabling mine details using pillar data. This evaluates the mine configuration under the pillar, for the following regular minion options that are also equally available on the proxy minion: \fBmine_interval\fP, and \fBmine_functions\fP\&. .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 .IP \(bu 2 \fI\%Example proxy 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 # Tell the master to also use salt\-ssh when running commands against minions. #enable_ssh_minions: False # 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, autosign_grains_dir: #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", "engines", "utils", etc. #extension_modules: /var/cache/salt/master/extmods # 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", "utils", etc. # Like \(aqextension_modules\(aq but can take an array of paths #module_dirs: [] # 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 # To set a list of additional directories to search for salt outputters, set the # outputter_dirs option. #outputter_dirs: [] # 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 # Tell the client to display the jid when a job is published. #show_jid: False # 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 # Enables a fast in\-memory cache booster and sets the expiration time. #memcache_expire_seconds: 0 # Set a memcache limit in items (bank + key) per cache storage (driver + driver_opts). #memcache_max_items: 1024 # Each time a cache storage got full cleanup all the expired items not just the oldest one. #memcache_full_cleanup: False # Enable collecting the memcache stats and log it on \(gadebug\(ga log level. #memcache_debug: False # 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, and event_return_queue_max_seconds 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 # In some cases enabling event return queueing can be very helpful, but the bus # may not busy enough to flush the queue consistently. Setting this to a reasonable # value (1\-30 seconds) will cause the queue to be flushed when the oldest event is older # than \(gaevent_return_queue_max_seconds\(ga regardless of how many events are in the queue. #event_return_queue_max_seconds: 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 # 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 ipc_mode is set to \(aqtcp\(aq #tcp_master_pub_port: 4510 #tcp_master_pull_port: 4511 # 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 # Allow or deny minions from requesting their own key revocation #allow_minion_key_revoke: True # 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 # 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 # These two batch settings, batch_safe_limit and batch_safe_size, are used to # automatically switch to a batch mode execution. If a command would have been # sent to more than minions, then run the command in # batches of . If no batch_safe_size is specified, a default # of 8 will be used. If no batch_safe_limit is specified, then no automatic # batching will occur. #batch_safe_limit: 100 #batch_safe_size: 8 # Master stats enables stats events to be fired from the master at close # to the defined interval #master_stats: False #master_stats_event_iter: 60 ##### Security settings ##### ########################################## # Enable passphrase protection of Master private key. Although a string value # is acceptable; passwords should be stored in an external vaulting mechanism # and retrieved via sdb. See https://docs.saltstack.com/en/latest/topics/sdb/. # Passphrase protection is off by default but an example of an sdb profile and # query is as follows. # masterkeyring: # driver: keyring # service: system # # key_pass: sdb://masterkeyring/key_pass # Enable passphrase protection of the Master signing_key. This only applies if # master_sign_pubkey is set to True. This is disabled by default. # master_sign_pubkey: True # signing_key_pass: sdb://masterkeyring/signing_pass # 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 # The size of key that should be generated when creating new keys. #keysize: 2048 # 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. The file must be readonly # except for the owner. Use permissive_pki_access to allow the group write access. #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 # If the autosign_grains_dir is specified, incoming keys from minions with grain # values matching those defined in files in this directory will be accepted # automatically. This is insecure. Minions need to be configured to send the grains. #autosign_grains_dir: /etc/salt/autosign_grains # 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 # 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 # Set to True to enable keeping the calculated user\(aqs auth list in the token # file. This is disabled by default and the auth list is calculated or requested # from the eauth driver each time. #keep_acl_in_token: False # Auth subsystem module to use to get authorized access list for a user. By default it\(aqs # the same module used for external authentication. #eauth_acl_module: django # 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 # Signature verification on messages published from minions # This requires that minions cryptographically sign the messages they # publish to the master. If minions are not signing, then log this information # at loglevel \(aqINFO\(aq and drop the message without acting on it. # require_minion_sign_messages: False # The below will drop messages when their signatures do not validate. # Note that when this option is False but \(garequire_minion_sign_messages\(ga is True # minions MUST sign their messages but the validity of their signatures # is ignored. # These two config options exist so a Salt infrastructure can be moved # to signing minion messages gradually. # drop_messages_signature_fail: 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 ##### ########################################## # Define the default salt\-ssh roster module to use #roster: flat # Pass in an alternative location for the salt\-ssh \(gaflat\(ga roster file #roster_file: /etc/salt/roster # Define locations for \(gaflat\(ga 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 ssh password to log in with. #ssh_passwd: \(aq\(aq #The target system\(aqs ssh port number. #ssh_port: 22 # Comma\-separated list of ports to scan. #ssh_scan_ports: 22 # Scanning socket timeout for salt\-ssh. #ssh_scan_timeout: 0.01 # Boolean to run command via sudo. #ssh_sudo: False # Boolean to run ssh_pre_flight script defined in roster. By default # the script will only run if the thin_dir does not exist on the targeted # minion. This forces the script to run regardless of the thin dir existing # or not. #ssh_run_pre_flight: True # Number of seconds to wait for a response when establishing an SSH connection. #ssh_timeout: 60 # The user to log in as. #ssh_user: root # 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 # Set this to True to default salt\-ssh to run with \(ga\(ga\-o IdentitiesOnly=yes\(ga\(ga. # This option is intended for situations where the ssh\-agent offers many # different identities and allows ssh to ignore those identities and use the # only one specified in options. #ssh_identities_only: False # List\-only nodegroups for salt\-ssh. Each group must be formed as either a # comma\-separated list, or a YAML list. This option is useful to group minions # into easy\-to\-target groups when using salt\-ssh. These groups can then be # targeted with the normal \-N argument to salt\-ssh. #ssh_list_nodegroups: {} # salt\-ssh has the ability to update the flat roster file if a minion is not # found in the roster. Set this to True to enable it. #ssh_update_roster: False ##### Master Module Management ##### ########################################## # Manage how master side modules are loaded. # Add any additional locations to look for master runners: #runner_dirs: [] # Add any additional locations to look for master utils: #utils_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 renderer to use on the minions to render the state data #renderer: jinja|yaml # Default Jinja environment options for all templates except sls templates #jinja_env: # block_start_string: \(aq{%\(aq # block_end_string: \(aq%}\(aq # variable_start_string: \(aq{{\(aq # variable_end_string: \(aq}}\(aq # comment_start_string: \(aq{#\(aq # comment_end_string: \(aq#}\(aq # line_statement_prefix: # line_comment_prefix: # trim_blocks: False # lstrip_blocks: False # newline_sequence: \(aq\en\(aq # keep_trailing_newline: False # Jinja environment options for sls templates #jinja_sls_env: # block_start_string: \(aq{%\(aq # block_end_string: \(aq%}\(aq # variable_start_string: \(aq{{\(aq # variable_end_string: \(aq}}\(aq # comment_start_string: \(aq{#\(aq # comment_end_string: \(aq#}\(aq # line_statement_prefix: # line_comment_prefix: # trim_blocks: False # lstrip_blocks: False # newline_sequence: \(aq\en\(aq # keep_trailing_newline: 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 controls which results will be output full multi line # full, terse \- each state will be full/terse # mixed \- only states with errors will be full # changes \- states with changes and errors will be full # full_id, mixed_id, changes_id and terse_id are also allowed; # when set, the state ID will be used as name in the output #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 # 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 # # The master_roots setting configures a master\-only copy of the file_roots dictionary, # used by the state compiler. #master_roots: # base: # \- /srv/salt\-master # 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 sha256, but md5, sha1, sha224, sha384 and # sha512 are also supported. # # WARNING: While md5 and sha1 are also supported, do not use them 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 # either pygit2 or gitpython. If unset, then both will be tried (in that # 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 # # The refspecs fetched by gitfs remotes #gitfs_refspecs: # \- \(aq+refs/heads/*:refs/remotes/origin/*\(aq # \- \(aq+refs/tags/*:refs/tags/*\(aq # # ##### 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 # A list of paths to be recursively decrypted during pillar compilation. # Entries in this list can be formatted either as a simple string, or as a # key/value pair, with the key being the pillar location, and the value being # the renderer to use for pillar decryption. If the former is used, the # renderer specified by decrypt_pillar_default will be used. #decrypt_pillar: # \- \(aqfoo:bar\(aq: gpg # \- \(aqlorem:ipsum:dolor\(aq # The delimiter used to distinguish nested data structures in the # decrypt_pillar option. #decrypt_pillar_delimiter: \(aq:\(aq # The default renderer used for decryption, if one is not specified for a given # pillar key in decrypt_pillar. #decrypt_pillar_default: gpg # List of renderers which are permitted to be used for pillar decryption. #decrypt_pillar_renderers: # \- gpg # 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 external pillars permitted to be used on\-demand using pillar.ext #on_demand_ext_pillar: # \- libvirt # \- virtkey # 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 True to force the pillarenv to be the same as the effective # saltenv when running states. If pillarenv is specified this option will be # ignored. #pillarenv_from_saltenv: 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 # The refspecs fetched by git_pillar remotes #git_pillar_refspecs: # \- \(aq+refs/heads/*:refs/remotes/origin/*\(aq # \- \(aq+refs/tags/*:refs/tags/*\(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 utilized. # # \(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 # A master can also cache GPG data 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 decrypted GPG data in a master cache have been addressed. # # When enabling this feature, be certain to read through the additional \(ga\(gagpg_cache_*\(ga\(ga # configuration options to fully understand the tunable parameters and their implications. #gpg_cache: False # If and only if a master has set \(ga\(gagpg_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. #gpg_cache_ttl: 86400 # If and only if a master has set \(gagpg_cache: True\(ga, one of several storage providers # can be utilized. Available options are the same as \(ga\(gapillar_cache_backend\(ga\(ga. #gpg_cache_backend: disk ###### Reactor Settings ##### ########################################### # Define a salt reactor. See https://docs.saltstack.com/en/latest/topics/reactor/ #reactor: [] #Set the TTL for the cache of the reactor configuration. #reactor_refresh_interval: 60 #Configure the number of workers for the runner/wheel in the reactor. #reactor_worker_threads: 10 #Define the queue size for workers in the reactor. #reactor_worker_hwm: 10000 ##### 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, \(aqinfo\(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 # The refspecs fetched by winrepo remotes #winrepo_refspecs: # \- \(aq+refs/heads/*:refs/remotes/origin/*\(aq # \- \(aq+refs/tags/*:refs/tags/*\(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 thin and minimal Salt # 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 #min_extra_mods: foo,bar,baz ###### Keepalive settings ###### ############################################ # Warning: Failure to set TCP keepalives on the salt\-master can result in # not detecting the loss of a minion when the connection is lost or when # its host has been terminated without first closing the socket. # Salt\(aqs Presence System depends on this connection status to know if a minion # is "present". # 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 ##### NetAPI settings ##### ############################################ # Allow the raw_shell parameter to be used when calling Salt SSH client via API #netapi_allow_raw_shell: True .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: # List of hosts to bypass HTTP proxy. This key does nothing unless proxy_host etc is # configured, it does not support any kind of wildcards. #no_proxy: [] # 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 upon Minion startup 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. #random_master: False # NOTE: Deprecated in Salt 2019.2.0. Use \(aqrandom_master\(aq instead. #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 lets 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 number of times to attempt to resolve # the master hostname if name resolution fails. Defaults to None, # which will attempt the resolution indefinitely. # retry_dns_count: 3 # 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 # Convert minion id to lowercase when it is being generated. Helpful when some # hosts get the minion id in uppercase. Cached ids will remain the same and # not converted. For example, Windows minions often have uppercase minion # names when they are set up but not always. To turn on, set this config to # \(ga\(gaTrue\(ga\(ga. #minion_id_lowercase: False # 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 # In order to calculate the fqdns grain, all the IP addresses from the minion # are processed with underlying calls to \(gasocket.gethostbyaddr\(ga which can take # 5 seconds to be released (after reaching \(gasocket.timeout\(ga) when there is no # fqdn for that IP. These calls to \(gasocket.gethostbyaddr\(ga are processed # asynchronously, however, it still adds 5 seconds every time grains are # generated if an IP does not resolve. In Windows grains are regenerated each # time a new process is spawned. Therefore, the default for Windows is \(gaFalse\(ga. # All other OSes default to \(gaTrue\(ga # enable_fqdns_grains: True # The minion can take a while to start up when lspci and/or dmidecode is used # to populate the grains for the minion. Set this to False if you do not need # GPU hardware grains for your minion. # enable_gpu_grains: True # Set the default outputter used by the salt\-call command. The default is # "nested". #output: nested # To set a list of additional directories to search for salt outputters, set the # outputter_dirs option. #outputter_dirs: [] # 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_backup 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 # To avoid overloading a master when many minions startup at once, a randomized # delay may be set to tell the minions to wait before connecting to the master. # This value is the number of seconds to choose from for a random number. For # example, setting this value to 60 will choose a random number of seconds to delay # on startup between zero seconds and sixty seconds. Setting to \(aq0\(aq will disable # this feature. #random_startup_delay: 0 # 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: 2 # # 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 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 # The number of minutes between mine updates. #mine_interval: 60 # Windows platforms lack posix IPC and must rely on slower TCP based inter\- # process communications. ipc_mode is set to \(aqtcp\(aq on such systems. #ipc_mode: ipc # Overwrite the default tcp ports used by the minion when ipc_mode is set to \(aqtcp\(aq #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 # When a minion starts up it sends a notification on the event bus with a tag # that looks like this: \(gasalt/minion//start\(ga. For historical reasons # the minion also sends a similar event with an event tag like this: # \(gaminion_start\(ga. This duplication can cause a lot of clutter on the event bus # when there are many minions. Set \(gaenable_legacy_startup_events: False\(ga in the # minion config to ensure only the \(gasalt/minion//start\(ga events are # sent. Beginning with the \(gaSodium\(ga Salt release this option will default to # \(gaFalse\(ga #enable_legacy_startup_events: True # 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 default renderer to use in SLS files. This is configured as a # pipe\-delimited expression. For example, jinja|yaml will first run jinja # templating on the SLS file, and then load the result as YAML. This syntax is # documented in further depth at the following URL: # # https://docs.saltstack.com/en/latest/ref/renderers/#composing\-renderers # # NOTE: The "shebang" prefix (e.g. "#!jinja|yaml") described in the # documentation linked above is for use in an SLS file to override the default # renderer, it should not be used when configuring the renderer here. # #renderer: jinja|yaml # # 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 # # Renamed from \(ga\(gaenvironment\(ga\(ga to \(ga\(gasaltenv\(ga\(ga. If \(ga\(gaenvironment\(ga\(ga is used, # \(ga\(gasaltenv\(ga\(ga will take its value. If both are used, \(ga\(gaenvironment\(ga\(ga will be # ignored and \(ga\(gasaltenv\(ga\(ga will be used. # 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. #saltenv: 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 True to force the pillarenv to be the same as the # effective saltenv when running states. Note that if pillarenv is specified, # this option will be ignored. #pillarenv_from_saltenv: 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 # # 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 # # List of grains to pass in start event when minion starts up: #start_event_grains: # \- machine_id # \- uuid # # 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 # Disable requisites during state runs by specifying a single requisite # or a list of requisites to disable. # # disabled_requisites: require_in # # disabled_requisites: # \- require # \- require_in ##### 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 sha256, but md5, sha1, sha224, sha384 # and sha512 are also supported. # # WARNING: While md5 and sha1 are also supported, do not use them 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 # The size of key that should be generated when creating new keys. #keysize: 2048 # 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 controls which results will be output full multi line # full, terse \- each state will be full/terse # mixed \- only states with errors will be full # changes \- states with changes and errors will be full # full_id, mixed_id, changes_id and terse_id are also allowed; # when set, the state ID will be used as name in the output #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 # Grains to be sent to the master on authentication to check if the minion\(aqs key # will be accepted automatically. Needs to be configured on the master. #autosign_grains: # \- uuid # \- server_id ###### Reactor Settings ##### ########################################### # Define a salt reactor. See https://docs.saltstack.com/en/latest/topics/reactor/ #reactor: [] #Set the TTL for the cache of the reactor configuration. #reactor_refresh_interval: 60 #Configure the number of workers for the runner/wheel in the reactor. #reactor_worker_threads: 10 #Define the queue size for workers in the reactor. #reactor_worker_hwm: 10000 ###### Thread settings ##### ########################################### # Disable multiprocessing support, by default when a minion receives a # publication a new process is spawned and the command is executed therein. # # WARNING: Disabling multiprocessing may result in substantial slowdowns # when processing large pillars. See https://github.com/saltstack/salt/issues/38758 # for a full explanation. #multiprocessing: True # Limit the maximum amount of processes or threads created by salt\-minion. # This is useful to avoid resource exhaustion in case the minion receives more # publications than it is able to handle, as it limits the number of spawned # processes or threads. \-1 is the default and disables the limit. #process_count_max: \-1 ##### 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, \(aqinfo\(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 # Number of times to try to authenticate with the salt master when reconnecting # to the master #tcp_authentication_retries: 5 ###### 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 Example proxy 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 all Salt Proxy # Minions on this host. # 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 # Backwards compatibility option for proxymodules created before 2015.8.2 # This setting will default to \(aqFalse\(aq in the 2016.3.0 release # Setting this to True adds proxymodules to the __opts__ dictionary. # This breaks several Salt features (basically anything that serializes # __opts__ over the wire) but retains backwards compatibility. #add_proxymodule_to_opts: True # Set the location of the salt master server. If the master server cannot be # resolved, then the minion will fail to start. #master: salt # If a proxymodule has a function called \(aqgrains\(aq, then call it during # regular grains loading and merge the results with the proxy\(aqs grains # dictionary. Otherwise it is assumed that the module calls the grains # function in a custom way and returns the data elsewhere # # Default to False for 2016.3 and 2016.11. Switch to True for 2017.7.0. # proxy_merge_grains_in_module: True # If a proxymodule has a function called \(aqalive\(aq returning a boolean # flag reflecting the state of the connection with the remove device, # when this option is set as True, a scheduled job on the proxy will # try restarting the connection. The polling frequency depends on the # next option, \(aqproxy_keep_alive_interval\(aq. Added in 2017.7.0. # proxy_keep_alive: True # The polling interval (in minutes) to check if the underlying connection # with the remote device is still alive. This option requires # \(aqproxy_keep_alive\(aq to be configured as True and the proxymodule to # implement the \(aqalive\(aq function. Added in 2017.7.0. # proxy_keep_alive_interval: 1 # By default, any proxy opens the connection with the remote device when # initialized. Some proxymodules allow through this option to open/close # the session per command. This requires the proxymodule to have this # capability. Please consult the documentation to see if the proxy type # used can be that flexible. Added in 2017.7.0. # proxy_always_alive: True # 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. #random_master: 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. # master_type: str # Poll interval in seconds for checking if the master is still there. Only # respected if master_type above is "failover". # master_alive_interval: 30 # 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 # Setting sudo_user will cause salt to run all execution modules under an sudo # to the user given in sudo_user. The user under which the salt minion process # itself runs will still be that provided in the user config above, but all # execution modules run by the minion will be rerouted through sudo. #sudo_user: saltdev # 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 directory to store the pki information in #pki_dir: /etc/salt/pki/minion # 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: # \- cachedir # 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_backup 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 # 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 a # sane 60 seconds, but if the minion scheduler needs to be evaluated more # often lower this value #loop_interval: 60 # 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 # 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 # 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 # # # ##### Minion module management ##### ########################################## # Disable specific modules. This allows the admin to limit the level of # access the master has to the minion. #disable_modules: [cmd,test] #disable_returners: [] # # 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 default renderer to use in SLS files. This is configured as a # pipe\-delimited expression. For example, jinja|yaml will first run jinja # templating on the SLS file, and then load the result as YAML. This syntax is # documented in further depth at the following URL: # # https://docs.saltstack.com/en/latest/ref/renderers/#composing\-renderers # # NOTE: The "shebang" prefix (e.g. "#!jinja|yaml") described in the # documentation linked above is for use in an SLS file to override the default # renderer, it should not be used when configuring the renderer here. # #renderer: jinja|yaml # # 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 # # 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 # 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 in # the local fileserver. The default is sha256 but sha224, 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 # # ###### 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 controls which results will be output full multi line # full, terse \- each state will be full/terse # mixed \- only states with errors will be full # changes \- states with changes and errors will be full # full_id, mixed_id, changes_id and terse_id are also allowed; # when set, the state ID will be used as name in the output #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" on the Salt master. #master_finger: \(aq\(aq ###### 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, \(aqinfo\(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 on the 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 ###### ############################################ # Which returner(s) will be used for minion\(aqs result: #return: mysql .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.version \- 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 \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 \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. .sp For more information and examples, see this Access Control System section. .UNINDENT .UNINDENT .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 the minion functions which will be made available to specified user. Both users and functions could be specified by exact match, shell glob or regular expression. This configuration is much like the external_auth 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.* # Allow admin and managers to use saltutil module functions admin|manager_.*: \- saltutil.* # Allow users to use only my_mod functions on "web*" minions with specific arguments. user_.*: \- web*: \- \(aqmy_mod.*\(aq: args: \- \(aqa.*\(aq \- \(aqb.*\(aq kwargs: \(aqkwa\(aq: \(aqkwa.*\(aq \(aqkwb\(aq: \(aqkwb\(aq .ft P .fi .UNINDENT .UNINDENT .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 .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 \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. .sp For more information and examples, see this Access Control System section. .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|admin.*: \- .* .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 and the users whose logins start with \fBadmin\fP, are granted 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. User and function matches are exact matches, shell glob patterns or 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 .sp By user, by runner/wheel: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C external_auth: : : <@runner or @wheel>: \- .ft P .fi .UNINDENT .UNINDENT .sp By user, by runner+wheel module: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C external_auth: : : <@module_name>: \- .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 \- \(aq@runner\(aq: \- \(aqrunner_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.version .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.version .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 # Use STARTTLS when connecting auth.ldap.starttls: 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 # In addition, if auth.ldap.anonymous is True, empty bind passwords are not permitted. 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: [] # Redhat Identity Policy Audit auth.ldap.freeipa: False .ft P .fi .UNINDENT .UNINDENT .SS Authenticating to the LDAP Server .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. Note this is not the same thing as using an anonymous bind. Most LDAP servers will not permit anonymous bind, and as mentioned above, if \fIauth.ldap.anonymous\fP is False you cannot use an empty password. .sp 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 .SS Determining Group Memberships (OpenLDAP / non\-Active Directory) .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 Note that as of 2017.7, auth.ldap.groupclass can refer to either a groupclass or an objectClass. For some LDAP servers (notably OpenLDAP without the \fBmemberOf\fP overlay enabled) to determine group membership we need to know both the \fBobjectClass\fP and the \fBmemberUid\fP attributes. Usually for these servers you will want a \fBauth.ldap.groupclass\fP of \fBposixGroup\fP and an \fBauth.ldap.groupattribute\fP of \fBmemberUid\fP\&. .sp LDAP servers with the \fBmemberOf\fP overlay will have entries similar to \fBauth.ldap.groupclass: person\fP and \fBauth.ldap.groupattribute: memberOf\fP\&. .sp When using the \fBldap(\(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 Determining Group Memberships (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 \fBldap()\fP above is any valid LDAP/AD tree limiter. \fBOU=\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.version on all minions: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C # salt\-call publish.publish \e* test.version .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 \fBtgt_type\fP: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C # salt\-call publish.publish \(aqwebserv* and not G@os:Ubuntu\(aq test.version tgt_type=\(aqcompound\(aq .ft P .fi .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 In pre\-2017.7.0 releases, use \fBexpr_form\fP instead of \fBtgt_type\fP\&. .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.version \- 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.version 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/{master|minion}/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 args: \- httpd kwargs: test: True when: \- \(aqtea time\(aq .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C whens: tea time: 1:40pm deployment time: Friday 5:00pm .ft P .fi .UNINDENT .UNINDENT .sp The Salt scheduler also allows custom phrases to be used for the \fIwhen\fP parameter. These \fIwhens\fP can be stored as either pillar values or grain values. .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 \fBkeep_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\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). Configuring either of these options will also make the \fBJobs Runner functions\fP to automatically query the remote stores for information. .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 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, the configuration requirements must be declared. .SS External Job Cache .sp The returner configuration settings can be declared in the Salt Minion configuration file, the Minion\(aqs pillar data, or the Minion\(aqs grains. .sp If \fBexternal_job_cache\fP configuration settings are specified in more than one place, the options are retrieved in the following order. The first configuration location that is found is the one that will be used. .INDENT 0.0 .IP \(bu 2 Minion configuration file .IP \(bu 2 Minion\(aqs grains .IP \(bu 2 Minion\(aqs pillar data .UNINDENT .SS Master Job Cache .sp The returner configuration settings for the Master Job Cache should be declared in the Salt Master\(aqs configuration file. .SS Configuration File Examples .sp 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: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C ://:/ .ft P .fi .UNINDENT .UNINDENT .sp Where \fBlog\-facility\fP is the symbolic name of a syslog facility as defined in the \fI\%SysLogHandler documentation\fP\&. 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 matches those used in \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 matches those used in \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\fP attributes 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 "%(colorlevel)s" # log level name colorized by level "%(colorname)s" # colorized module name "%(colorprocess)s" # colorized process number "%(colormsg)s" # 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\fP attributes 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 "%(bracketlevel)s" # equivalent to [%(levelname)\-8s] "%(bracketname)s" # equivalent to [%(name)\-17s] "%(bracketprocess)s" # 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, based on log call name. The example sets the main salt library at the \(aqwarning\(aq level, sets \fBsalt.modules\fP to log at the \fBdebug\fP level, and sets a custom module to the \fBall\fP level: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C log_granular_levels: \(aqsalt\(aq: \(aqwarning\(aq \(aqsalt.modules\(aq: \(aqdebug\(aq \(aqsalt.loader.saltmaster.ext.module.custom_module\(aq: \(aqall\(aq .ft P .fi .UNINDENT .UNINDENT .SS \fBlog_fmt_jid\fP .sp Default: \fB[JID: %(jid)s]\fP .sp The format of the JID when added to logging messages. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C log_fmt_jid: \(aq[JID: %(jid)s]\(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 External Logging Handlers .TS center; |l|l|. _ T{ \fBfluent_mod\fP T} T{ Fluent Logging Handler T} _ T{ \fBlog4mongo_mod\fP T} T{ Log4Mongo Logging Handler T} _ T{ \fBlogstash_mod\fP T} T{ Logstash Logging Handler T} _ T{ \fBsentry_mod\fP T} T{ Sentry Logging Handler T} _ .TE .SS salt.log.handlers.fluent_mod .SS Fluent Logging Handler .sp New in version 2015.8.0. .sp This module provides some \fI\%fluentd\fP logging handlers. .SS Fluent Logging Handler .sp In the \fIfluent\fP configuration file: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C type forward bind localhost port 24224 .ft P .fi .UNINDENT .UNINDENT .sp Then, to send logs via fluent in Logstash format, add the following to the salt (master and/or minion) configuration file: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C fluent_handler: host: localhost port: 24224 .ft P .fi .UNINDENT .UNINDENT .sp To send logs via fluent in the Graylog raw json format, add the following to the salt (master and/or minion) configuration file: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C fluent_handler: host: localhost port: 24224 payload_type: graylog tags: \- salt_master.SALT .ft P .fi .UNINDENT .UNINDENT .sp The above also illustrates the \fItags\fP option, which allows one to set descriptive (or useful) tags on records being sent. If not provided, this defaults to the single tag: \(aqsalt\(aq. Also note that, via Graylog "magic", the \(aqfacility\(aq of the logged message is set to \(aqSALT\(aq (the portion of the tag after the first period), while the tag itself will be set to simply \(aqsalt_master\(aq. This is a feature, not a bug :) .sp Note: There is a third emitter, for the GELF format, but it is largely untested, and I don\(aqt currently have a setup supporting this config, so while it runs cleanly and outputs what LOOKS to be valid GELF, any real\-world feedback on its usefulness, and correctness, will be appreciated. .SS Log Level .sp The \fBfluent_handler\fP configuration section accepts an additional setting \fBlog_level\fP\&. If not set, the logging level used will be the one defined for \fBlog_level\fP in the global configuration file section. .INDENT 0.0 .INDENT 3.5 .IP "Inspiration" .sp This work was inspired in \fI\%fluent\-logger\-python\fP .UNINDENT .UNINDENT .SS salt.log.handlers.log4mongo_mod .SS Log4Mongo Logging Handler .sp This module provides a logging handler for sending salt logs to MongoDB .SS Configuration .sp In the salt configuration file (e.g. /etc/salt/{master,minion}): .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C log4mongo_handler: host: mongodb_host port: 27017 database_name: logs collection: salt_logs username: logging password: reindeerflotilla write_concern: 0 log_level: warning .ft P .fi .UNINDENT .UNINDENT .SS Log Level .sp If not set, the log_level will be set to the level defined in the global configuration file setting. .INDENT 0.0 .INDENT 3.5 .IP "Inspiration" .sp This work was inspired by the Salt logging handlers for LogStash and Sentry and by the log4mongo Python implementation. .UNINDENT .UNINDENT .SS salt.log.handlers.logstash_mod .SS Logstash Logging Handler .sp New in version 0.17.0. .sp This module provides some \fI\%Logstash\fP logging handlers. .SS UDP Logging Handler .sp For versions of \fI\%Logstash\fP before 1.2.0: .sp In the salt configuration file: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C logstash_udp_handler: host: 127.0.0.1 port: 9999 version: 0 msg_type: logstash .ft P .fi .UNINDENT .UNINDENT .sp In the \fI\%Logstash\fP configuration file: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C input { udp { type => "udp\-type" format => "json_event" } } .ft P .fi .UNINDENT .UNINDENT .sp For version 1.2.0 of \fI\%Logstash\fP and newer: .sp In the salt configuration file: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C logstash_udp_handler: host: 127.0.0.1 port: 9999 version: 1 msg_type: logstash .ft P .fi .UNINDENT .UNINDENT .sp In the \fI\%Logstash\fP configuration file: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C input { udp { port => 9999 codec => json } } .ft P .fi .UNINDENT .UNINDENT .sp Please read the \fI\%UDP input\fP configuration page for additional information. .SS ZeroMQ Logging Handler .sp For versions of \fI\%Logstash\fP before 1.2.0: .sp In the salt configuration file: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C logstash_zmq_handler: address: tcp://127.0.0.1:2021 version: 0 .ft P .fi .UNINDENT .UNINDENT .sp In the \fI\%Logstash\fP configuration file: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C input { zeromq { type => "zeromq\-type" mode => "server" topology => "pubsub" address => "tcp://0.0.0.0:2021" charset => "UTF\-8" format => "json_event" } } .ft P .fi .UNINDENT .UNINDENT .sp For version 1.2.0 of \fI\%Logstash\fP and newer: .sp In the salt configuration file: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C logstash_zmq_handler: address: tcp://127.0.0.1:2021 version: 1 .ft P .fi .UNINDENT .UNINDENT .sp In the \fI\%Logstash\fP configuration file: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C input { zeromq { topology => "pubsub" address => "tcp://0.0.0.0:2021" codec => json } } .ft P .fi .UNINDENT .UNINDENT .sp Please read the \fI\%ZeroMQ input\fP configuration page for additional information. .INDENT 0.0 .INDENT 3.5 .IP "Important Logstash Setting" .sp One of the most important settings that you should not forget on your \fI\%Logstash\fP configuration file regarding these logging handlers is \fBformat\fP\&. Both the \fIUDP\fP and \fIZeroMQ\fP inputs need to have \fBformat\fP as \fBjson_event\fP which is what we send over the wire. .UNINDENT .UNINDENT .SS Log Level .sp Both the \fBlogstash_udp_handler\fP and the \fBlogstash_zmq_handler\fP configuration sections accept an additional setting \fBlog_level\fP\&. If not set, the logging level used will be the one defined for \fBlog_level\fP in the global configuration file section. .SS HWM .sp The \fI\%high water mark\fP for the ZMQ socket setting. Only applicable for the \fBlogstash_zmq_handler\fP\&. .INDENT 0.0 .INDENT 3.5 .IP "Inspiration" .sp This work was inspired in \fI\%pylogstash\fP, \fI\%python\-logstash\fP, \fI\%canary\fP and the \fI\%PyZMQ logging handler\fP\&. .UNINDENT .UNINDENT .SS salt.log.handlers.sentry_mod .SS Sentry Logging Handler .sp New in version 0.17.0. .sp This module provides a \fI\%Sentry\fP logging handler. Sentry is an open source error tracking platform that provides deep context about exceptions that happen in production. Details about stack traces along with the context variables available at the time of the exception are easily browsable and filterable from the online interface. For more details please see \fI\%Sentry\fP\&. .INDENT 0.0 .INDENT 3.5 .IP "Note" .sp The \fI\%Raven\fP library needs to be installed on the system for this logging handler to be available. .UNINDENT .UNINDENT .sp Configuring the python \fI\%Sentry\fP client, \fI\%Raven\fP, should be done under the \fBsentry_handler\fP configuration key. Additional \fIcontext\fP may be provided for corresponding grain item(s). At the bare minimum, you need to define the \fI\%DSN\fP\&. As an example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C sentry_handler: dsn: https://pub\-key:secret\-key@app.getsentry.com/app\-id .ft P .fi .UNINDENT .UNINDENT .sp More complex configurations can be achieved, for example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C sentry_handler: servers: \- https://sentry.example.com \- http://192.168.1.1 project: app\-id public_key: deadbeefdeadbeefdeadbeefdeadbeef secret_key: beefdeadbeefdeadbeefdeadbeefdead context: \- os \- master \- saltversion \- cpuarch \- ec2.tags.environment .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .INDENT 3.5 .IP "Note" .sp The \fBpublic_key\fP and \fBsecret_key\fP variables are not supported with Sentry > 3.0. The \fI\%DSN\fP key should be used instead. .UNINDENT .UNINDENT .sp All the client configuration keys are supported, please see the \fI\%Raven client documentation\fP\&. .sp The default logging level for the sentry handler is \fBERROR\fP\&. If you wish to define a different one, define \fBlog_level\fP under the \fBsentry_handler\fP configuration key: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C sentry_handler: dsn: https://pub\-key:secret\-key@app.getsentry.com/app\-id log_level: warning .ft P .fi .UNINDENT .UNINDENT .sp The available log levels are those also available for the salt \fBcli\fP tools and configuration; \fBsalt \-\-help\fP should give you the required information. .SS Threaded Transports .sp Raven\(aqs documents rightly suggest using its threaded transport for critical applications. However, don\(aqt forget that if you start having troubles with Salt after enabling the threaded transport, please try switching to a non\-threaded transport to see if that fixes your problem. .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 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="base"): """ Used to get a single file from the Salt master CLI Example: salt \(aq*\(aq cp.get_file salt://vimrc /etc/vimrc """ # 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="base"): """ Used to get a single file from the Salt master """ # Get the configuration data opts = salt.config.minion_config("/etc/salt/minion") # 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 Both \fI\%pygit2\fP and \fI\%GitPython\fP are supported Python interfaces to git. If compatible versions of both are installed, \fI\%pygit2\fP will be preferred. In these cases, \fI\%GitPython\fP can be forced using the \fBgitfs_provider\fP parameter in the master config file. .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 \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 If you are receiving the error "Unsupported URL Protocol" in the Salt Master log when making a connection using SSH, review the libssh2 details listed above. .UNINDENT .UNINDENT .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. .sp \fBWARNING:\fP .INDENT 0.0 .INDENT 3.5 \fI\%pygit2\fP is actively developed and \fI\%frequently makes non\-backwards\-compatible API changes\fP, 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 \fI\%SaltStack issue tracker\fP\&. .UNINDENT .UNINDENT .SS RedHat Pygit2 Issues .sp The release of RedHat/CentOS 7.3 upgraded both \fBpython\-cffi\fP and \fBhttp\-parser\fP, both of which are dependencies for \fI\%pygit2\fP/\fI\%libgit2\fP\&. Both \fBpygit2\fP and \fBlibgit2\fP packages (which are from the EPEL repository) should be upgraded to the most recent versions, at least to \fB0.24.2\fP\&. .sp The below errors will show up in the master log if an incompatible \fBpython\-pygit2\fP package is installed: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C 2017\-02\-10 09:07:34,892 [salt.utils.gitfs ][ERROR ][11211] Import pygit2 failed: CompileError: command \(aqgcc\(aq failed with exit status 1 2017\-02\-10 09:07:34,907 [salt.utils.gitfs ][ERROR ][11211] gitfs is configured but could not be loaded, are pygit2 and libgit2 installed? 2017\-02\-10 09:07:34,907 [salt.utils.gitfs ][CRITICAL][11211] No suitable gitfs provider module is installed. 2017\-02\-10 09:07:34,912 [salt.master ][CRITICAL][11211] Master failed pre flight checks, exiting .ft P .fi .UNINDENT .UNINDENT .sp The below errors will show up in the master log if an incompatible \fBlibgit2\fP package is installed: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C 2017\-02\-15 18:04:45,211 [salt.utils.gitfs ][ERROR ][6211] Error occurred fetching gitfs remote \(aqhttps://foo.com/bar.git\(aq: No Content\-Type header in response .ft P .fi .UNINDENT .UNINDENT .sp A restart of the \fBsalt\-master\fP daemon and gitfs cache directory clean up may be required to allow http(s) repositories to continue to be fetched. .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 \fI\%GitPython\fP requires the \fBgit\fP CLI utility to work. If installed from a system package, then git should already be installed, but if installed via \fI\%pip\fP then it may still be necessary to install git separately. For MacOS users, \fI\%GitPython\fP comes bundled in with the Salt installer, but git must still be installed for it to work properly. Git can be installed in several ways, including by installing \fI\%XCode\fP\&. .sp \fBWARNING:\fP .INDENT 0.0 .INDENT 3.5 GitPython advises against the use of its library for long\-running processes (such as a salt\-master or salt\-minion). Please see their warning on potential leaks of system resources: \fI\%https://github.com/gitpython\-developers/GitPython#leakage\-of\-system\-resources\fP\&. .UNINDENT .UNINDENT .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 Simple Configuration .sp To use the gitfs backend, only two configuration changes are required on the master: .INDENT 0.0 .IP 1. 3 Include \fBgitfs\fP in the \fBfileserver_backend\fP list in the master config file: .INDENT 3.0 .INDENT 3.5 .sp .nf .ft C fileserver_backend: \- gitfs .ft P .fi .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 3.0 .INDENT 3.5 \fBgit\fP also works here. Prior to the 2018.3.0 release, \fIonly\fP \fBgit\fP would work. .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\&. .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_ssl_verify\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) .IP \(bu 2 \fBgitfs_refspecs\fP (new in 2017.7.0) .IP \(bu 2 \fBgitfs_disable_saltenv_mapping\fP (new in 2018.3.0) .IP \(bu 2 \fBgitfs_ref_types\fP (new in 2018.3.0) .IP \(bu 2 \fBgitfs_update_interval\fP (new in 2018.3.0) .UNINDENT .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 pygit2 only supports disabling SSL verification in versions 0.23.2 and newer. .UNINDENT .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 \- ssl_verify: False \- update_interval: 120 \- https://foo.com/bar.git: \- name: second_bar_repo \- root: other/salt \- mountpoint: salt://other/bar \- base: salt\-base \- ref_types: \- branch \- http://foo.com/baz.git: \- root: salt/states \- user: joe \- password: mysupersecretpassword \- insecure_auth: True \- disable_saltenv_mapping: True \- saltenv: \- foo: \- ref: foo \- http://foo.com/quux.git: \- all_saltenvs: master .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, \fBsaltenv\fP, and \fBall_saltenvs\fP parameters, which are only available to per\-remote configurations. .UNINDENT .sp The \fBall_saltenvs\fP parameter is new in the 2018.3.0 release. .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 third remote will only serve files from branches, and not from tags or SHAs. .IP 4. 3 The fourth remote will only have two saltenvs available: \fBbase\fP (pointed at \fBdevelop\fP), and \fBfoo\fP (pointed at \fBfoo\fP). .IP 5. 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 6. 3 The second and third remotes reference the same repository and unique names need to be declared for duplicate gitfs remotes. .IP 7. 3 The fourth remote overrides the default behavior of \fI\%not authenticating to insecure (non\-HTTPS) remotes\fP\&. .IP 8. 3 Because \fBall_saltenvs\fP is configured for the fifth remote, files from the branch/tag \fBmaster\fP will appear in every fileserver environment. .sp \fBNOTE:\fP .INDENT 3.0 .INDENT 3.5 The use of \fBhttp://\fP (instead of \fBhttps://\fP) is permitted here \fIonly\fP because authentication is not being used. Otherwise, the \fBinsecure_auth\fP parameter must be used (as in the fourth remote) to force Salt to authenticate to an \fBhttp://\fP remote. .UNINDENT .UNINDENT .IP 9. 3 The first remote will wait 120 seconds between updates instead of 60. .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 Custom Refspecs .sp New in version 2017.7.0. .sp GitFS will by default fetch remote branches and tags. However, sometimes it can be useful to fetch custom refs (such as those created for \fI\%GitHub pull requests\fP). To change the refspecs GitFS fetches, use the \fBgitfs_refspecs\fP config option: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C gitfs_refspecs: \- \(aq+refs/heads/*:refs/remotes/origin/*\(aq \- \(aq+refs/tags/*:refs/tags/*\(aq \- \(aq+refs/pull/*/head:refs/remotes/origin/pr/*\(aq \- \(aq+refs/pull/*/merge:refs/remotes/origin/merge/*\(aq .ft P .fi .UNINDENT .UNINDENT .sp In the above example, in addition to fetching remote branches and tags, GitHub\(aqs custom refs for pull requests and merged pull requests will also be fetched. These special \fBhead\fP refs represent the head of the branch which is requesting to be merged, and the \fBmerge\fP refs represent the result of the base branch after the merge. .sp \fBIMPORTANT:\fP .INDENT 0.0 .INDENT 3.5 When using custom refspecs, the destination of the fetched refs \fImust\fP be under \fBrefs/remotes/origin/\fP, preferably in a subdirectory like in the example above. These custom refspecs will map as environment names using their relative path underneath \fBrefs/remotes/origin/\fP\&. For example, assuming the configuration above, the head branch for pull request 12345 would map to fileserver environment \fBpr/12345\fP (slash included). .UNINDENT .UNINDENT .sp Refspecs can be configured on a \fI\%per\-remote basis\fP\&. For example, the below configuration would only alter the default refspecs for the \fIsecond\fP GitFS remote. The first remote would only fetch branches and tags (the default). .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C gitfs_remotes: \- https://domain.tld/foo.git \- https://domain.tld/bar.git: \- refspecs: \- \(aq+refs/heads/*:refs/remotes/origin/*\(aq \- \(aq+refs/tags/*:refs/tags/*\(aq \- \(aq+refs/pull/*/head:refs/remotes/origin/pr/*\(aq \- \(aq+refs/pull/*/merge:refs/remotes/origin/merge/*\(aq .ft P .fi .UNINDENT .UNINDENT .SS Global Remotes .sp New in version 2018.3.0: for all_saltenvs, 3001 for fallback .sp The \fBall_saltenvs\fP per\-remote configuration parameter overrides the logic Salt uses to map branches/tags to fileserver environments (i.e. saltenvs). This allows a single branch/tag to appear in \fIall\fP GitFS saltenvs. .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 \fBall_saltenvs\fP only works \fIwithin\fP GitFS. That is, files in a branch configured using \fBall_saltenvs\fP will \fInot\fP show up in a fileserver environment defined via some other fileserver backend (e.g. \fBfile_roots\fP). .UNINDENT .UNINDENT .sp The \fBfallback\fP global or per\-remote configuration can also be used. .sp This is very useful in particular when working with salt formulas\&. Prior to the addition of this feature, it was necessary to push a branch/tag to the remote repo for each saltenv in which that formula was to be used. If the formula needed to be updated, this update would need to be reflected in all of the other branches/tags. This is both inconvenient and not scalable. .sp With \fBall_saltenvs\fP, it is now possible to define your formula once, in a single branch. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C gitfs_remotes: \- http://foo.com/quux.git: \- all_saltenvs: anything .ft P .fi .UNINDENT .UNINDENT .sp If you want to also test working branches of the formula repository, use \fBfallback\fP: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C gitfs_remotes: \- http://foo.com/quux.git: \- fallback: anything .ft P .fi .UNINDENT .UNINDENT .SS Update Intervals .sp Prior to the 2018.3.0 release, GitFS would update its fileserver backends as part of a dedicated "maintenance" process, in which various routine maintenance tasks were performed. This tied the update interval to the \fBloop_interval\fP config option, and also forced all fileservers to update at the same interval. .sp Now it is possible to make GitFS update at its own interval, using \fBgitfs_update_interval\fP: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C gitfs_update_interval: 180 gitfs_remotes: \- https://foo.com/foo.git \- https://foo.com/bar.git: \- update_interval: 120 .ft P .fi .UNINDENT .UNINDENT .sp Using the above configuration, the first remote would update every three minutes, while the second remote would update every two minutes. .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: \- 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 .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 The one exception to the above is when \fI\%all_saltenvs\fP is used. This value overrides all logic for mapping branches/tags to fileserver environments. So, even if \fBgitfs_saltenv\fP is used to globally override the mapping for a given saltenv, \fI\%all_saltenvs\fP would take precedence for any remote which uses it. .sp It\(aqs important to note however that any \fBroot\fP and \fBmountpoint\fP values configured in \fBgitfs_saltenv\fP (or \fI\%per\-saltenv configuration\fP) would be unaffected by this. .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 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 in Masterless Mode .sp Since 2014.7.0, gitfs can be used in masterless mode. To do so, simply add the gitfs configuration parameters (and set \fBfileserver_backend\fP) in the _minion_ config file instead of the master config file. .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. .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 This can be used together with \fIfile_roots\fP accepting \fI__env__\fP as a catch\-all environment, since 2018.3.5 and 2019.2.1: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C file_roots: base: \- /srv/salt __env__: \- /srv/salt .ft P .fi .UNINDENT .UNINDENT .UNINDENT .UNINDENT .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_saltenv_whitelist\fP and \fBgitfs_saltenv_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_saltenv_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_saltenv_whitelist\fP is used, then \fBonly\fP branches/tags which match the whitelist will be available as environments .IP \(bu 2 If only \fBgitfs_saltenv_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\&. .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 There is a known issue with public\-key SSH authentication to Microsoft Visual Studio (VSTS) with pygit2. This is due to a bug or lack of support for VSTS in older libssh2 releases. Known working releases include libssh2 1.7.0 and later, and known incompatible releases include 1.5.0 and older. At the time of this writing, 1.6.0 has not been tested. .sp Since upgrading libssh2 would require rebuilding many other packages (curl, etc.), followed by a rebuild of libgit2 and a reinstall of pygit2, an easier workaround for systems with older libssh2 is to use GitPython with a passphraseless key for authentication. .UNINDENT .UNINDENT .SS GitPython .SS HTTPS .sp For HTTPS repositories which require authentication, the username and password can be configured in one of two ways. The first way is to include them in the URL using the format \fBhttps://:@\fP, like so: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C gitfs_remotes: \- https://git:mypassword@domain.tld/myrepo.git .ft P .fi .UNINDENT .UNINDENT .sp The other way would be to configure the authentication in \fB~/.netrc\fP: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C machine domain.tld login 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://git:mypassword@domain.tld/insecure_repo.git: \- insecure_auth: True .ft P .fi .UNINDENT .UNINDENT .SS SSH .sp Only passphrase\-less SSH public key authentication is supported using GitPython. \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. This configuration schema is detailed here\&. .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 \fBminionfs\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 \- minionfs .ft P .fi .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 \fBminion\fP also works here. Prior to the 2018.3.0 release, \fIonly\fP \fBminion\fP would work. .sp Also, as described earlier, \fBfile_recv: True\fP is 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 \- minionfs minionfs_mountpoint: salt://minionfs minionfs_whitelist: \- host04 \- web* \- \(aqmail\ed+\e.domain\e.tld\(aq minionfs_blacklist: \- 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 For HTTP/HTTPS Basic authorization you can define credentials: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C my_repo: url: https://spm.example.com/ username: user password: pass .ft P .fi .UNINDENT .UNINDENT .sp Beware of unauthorized access to this file, please set at least 0640 permissions for this configuration file: .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 files .sp A files section can be added, to specify a list of files to add to the SPM. Such a section might look like: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C files: \- _pillar \- FORMULA \- _runners \- d|mymodule/index.rst \- r|README.rst .ft P .fi .UNINDENT .UNINDENT .sp When \fBfiles\fP are specified, then only those files will be added to the SPM, regardless of what other files exist in the directory. They will also be added in the order specified, which is useful if you have a need to lay down files in a specific order. .sp As can be seen in the example above, you may also tag files as being a specific type. This is done by pre\-pending a filename with its type, followed by a pipe (\fB|\fP) character. The above example contains a document file and a readme. The available file types are: .INDENT 0.0 .IP \(bu 2 \fBc\fP: config file .IP \(bu 2 \fBd\fP: documentation file .IP \(bu 2 \fBg\fP: ghost file (i.e. the file contents are not included in the package payload) .IP \(bu 2 \fBl\fP: license file .IP \(bu 2 \fBr\fP: readme file .IP \(bu 2 \fBs\fP: SLS file .IP \(bu 2 \fBm\fP: Salt module .UNINDENT .sp The first 5 of these types (\fBc\fP, \fBd\fP, \fBg\fP, \fBl\fP, \fBr\fP) will be placed in \fB/usr/share/salt/spm/\fP by default. This can be changed by setting an \fBspm_share_dir\fP value in your \fB/etc/salt/spm\fP configuration file. .sp The last two types (\fBs\fP and \fBm\fP) are currently ignored, but they are reserved for future use. .SS Pre and Post States .sp It is possible to run Salt states before and after installing a package by using pre and post states. The following sections may be declared in a \fBFORMULA\fP: .INDENT 0.0 .IP \(bu 2 \fBpre_local_state\fP .IP \(bu 2 \fBpre_tgt_state\fP .IP \(bu 2 \fBpost_local_state\fP .IP \(bu 2 \fBpost_tgt_state\fP .UNINDENT .sp Sections with \fBpre\fP in their name are evaluated before a package is installed and sections with \fBpost\fP are evaluated after a package is installed. \fBlocal\fP states are evaluated before \fBtgt\fP states. .sp Each of these sections needs to be evaluated as text, rather than as YAML. Consider the following block: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C pre_local_state: > echo test > /tmp/spmtest: cmd: \- run .ft P .fi .UNINDENT .UNINDENT .sp Note that this declaration uses \fB>\fP after \fBpre_local_state\fP\&. This is a YAML marker that marks the next multi\-line block as text, including newlines. It is important to use this marker whenever declaring \fBpre\fP or \fBpost\fP states, so that the text following it can be evaluated properly. .SS local States .sp \fBlocal\fP states are evaluated locally; this is analogous to issuing a state run using a \fBsalt\-call \-\-local\fP command. These commands will be issued on the local machine running the \fBspm\fP command, whether that machine is a master or a minion. .sp \fBlocal\fP states do not require any special arguments, but they must still use the \fB>\fP marker to denote that the state is evaluated as text, not a data structure. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C pre_local_state: > echo test > /tmp/spmtest: cmd: \- run .ft P .fi .UNINDENT .UNINDENT .SS tgt States .sp \fBtgt\fP states are issued against a remote target. This is analogous to issuing a state using the \fBsalt\fP command. As such it requires that the machine that the \fBspm\fP command is running on is a master. .sp Because \fBtgt\fP states require that a target be specified, their code blocks are a little different. Consider the following state: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C pre_tgt_state: tgt: \(aq*\(aq data: > echo test > /tmp/spmtest: cmd: \- run .ft P .fi .UNINDENT .UNINDENT .sp With \fBtgt\fP states, the state data is placed under a \fBdata\fP section, inside the \fB*_tgt_state\fP code block. The target is of course specified as a \fBtgt\fP and you may also optionally specify a \fBtgt_type\fP (the default is \fBglob\fP). .sp You still need to use the \fB>\fP marker, but this time it follows the \fBdata\fP line, rather than the \fB*_tgt_state\fP line. .SS Templating States .sp The reason that state data must be evaluated as text rather than a data structure is because that state data is first processed through the rendering engine, as it would be with a standard state run. .sp This means that you can use Jinja or any other supported renderer inside of Salt. All formula variables are available to the renderer, so you can reference \fBFORMULA\fP data inside your state if you need to: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C pre_tgt_state: tgt: \(aq*\(aq data: > echo {{ name }} > /tmp/spmtest: cmd: \- run .ft P .fi .UNINDENT .UNINDENT .sp You may also declare your own variables inside the \fBFORMULA\fP\&. If SPM doesn\(aqt recognize them then it will ignore them, so there are no restrictions on variable names, outside of avoiding reserved words. .sp By default the renderer is set to \fBjinja|yaml\fP\&. You may change this by changing the \fBrenderer\fP setting in the \fBFORMULA\fP itself. .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 def myfunc(): conn = sqlite3.connect(__opts__["spm_db"], 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.files.fopen(path, "r") 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. To be available for master commands, such as runners, it needs to be configured in the master configuration. For modules executed on a minion, it can be set either in the minion configuration file, or as a pillar. 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 \fBWARNING:\fP .INDENT 0.0 .INDENT 3.5 The \fBvault\fP driver previously only supported splitting the path and key with a question mark. This has since been deprecated in favor of using the standard / to split the path and key. The use of the questions mark will still be supported to ensure backwards compatibility, but please use the preferred method using /. The deprecated approach required 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 Instead of the above please use the preferred URI using / instead: .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 .UNINDENT .UNINDENT .sp Setting a value uses the same URI as would be used to retrieve it, followed by the value as another argument. .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 below: .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__["config.get"]("mykey") .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__ = { "set_": "set", } .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 its 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. .sp \fBIMPORTANT:\fP .INDENT 0.0 .INDENT 3.5 Refer to the saltstack_security_announcements documentation in order to stay updated and secure. .UNINDENT .UNINDENT .sp \fBWARNING:\fP .INDENT 0.0 .INDENT 3.5 For historical reasons, Salt requires PyCrypto as a "lowest common denominator". However, \fI\%PyCrypto is unmaintained\fP and best practice is to manually upgrade to use a more maintained library such as \fI\%PyCryptodome\fP\&. See \fI\%Issue #52674\fP and \fI\%Issue #54115\fP for more info .UNINDENT .UNINDENT .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. Pay particular attention to TCP/4505 and TCP/4506 on the salt master and avoid exposing these ports unnecessarily. .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. .IP \(bu 2 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. .IP \(bu 2 Monitor specific security related log messages. Salt \fBsalt\-master\fP logs attempts to access methods which are not exposed to network clients. These log messages are logged at the \fBerror\fP log level and start with \fBRequested method not exposed\fP\&. .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\-\-\-\-\- 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 mZRqiQJVBBMBCAA/AhsDBgsJCAcDAgYVCAIJCgsEFgIDAQIeAQIXgBYhBIq+Tvzw 9LJL/yqvkNVw8tNOoHk9BQJe1uRXBQkPoTz0AAoJENVw8tNOoHk9akAQANKIDIBY J3DmWH3g6rWURdREQcBVfMkw6j5MHlIEwlGrN3whSaPv2KR3tatRccBCQ0olQeYb ZeFtPuf0Du+LqGaAePo5DkPNU7GHoba2+ZE/sJ4wZ4CzAQM6+LvH2iLHeLZ1VLlu ZEftxD1RFKTqpnav8KiyYGkeFuEn4eMSIhbudp/8wkN40sCWL22D141EhVSRvLlO BMUpTWdtSYTg0F2pgQL5U2A56syuiwUwPXzQb45JEJILmG8zkeJB9s8kGtErypIH P+qxJXq24woGUFeJjiLdiOhI6/YoVBACUkKmig36CGf/DH5NAeQECeZq3YBNp7XK tsF1dPitxuTM/UkOHoHUnGhDlBcQMWe9WuBK4rA+7GH9NT8o7M6+2OKhk181tJ+s Y2kP7RSXOV162thRsNvVImXajAIFTR3ksEDFGVq/4jh85jFoIbNH3x27NxOu6e2p OIkXNXmSFXLUmwbfEfIk06gqP3xzkaj+eWHcLDkn9bUKblBJhHdhf9Vsy/N2NRW2 23c64qDutw1NX7msDuN3KXisim+isBzPVVzymkkhkXK+UpjrRR0ePvph3fnGf1bc NipVtn1KKM7kurSrSjFVLwLi52SGnEHKJnbbhh+AKV09SNYi6IaKL8yw8c1d0K80 PlBaJEvkC6myzaaRtYcna4pbiIysBaZtwDOOuQINBFO15mMBEAC5UuLii9ZLz6qH fIJp35IOW9U8SOf7QFhzXR7NZ3DmJsd3f6Nb/habQFIHjm3K9wbpj+FvaW2oWRlF VvYdzjUq6c82GUUjW1dnqgUvFwdmM8351n0YQ2TonmyaF882RvsRZrbJ65uvy7SQ xlouXaAYOdqwLsPxBEOyOnMPSktW5V2UIWyxsNP3sADchWIGq9p5D3Y/loyIMsS1 dj+TjoQZOKSj7CuRT98+8yhGAY8YBEXu9r3I9o6mDkuPpAljuMc8r09Im6az2egt K/szKt4Hy1bpSSBZU4W/XR7XwQNywmb3wxjmYT6Od3Mwj0jtzc3gQiH8hcEy3+BO +NNmyzFVyIwOLziwjmEcw62S57wYKUVnHD2nglMsQa8Ve0e6ABBMEY7zGEGStva5 9rfgeh0jUMJiccGiUDTMs0tdkC6knYKbu/fdRqNYFoNuDcSeLEw4DdCuP01l2W4y Y+fiK6hAcL25amjzc+yYo9eaaqTn6RATbzdhHQZdpAMxY+vNT0+NhP1Zo5gYBMR6 5Zp/VhFsf67ijb03FUtdw9N8dHwiR2m8vVA8kO/gCD6wS2p9RdXqrJ9JhnHYWjiV uXR+f755ZAndyQfRtowMdQIoiXuJEXYw6XN+/BX81gJaynJYc0uw0MnxWQX+A5m8 HqEsbIFUXBYXPgbwXTm7c4IHGgXXdwARAQABiQI8BBgBCAAmAhsMFiEEir5O/PD0 skv/Kq+Q1XDy006geT0FAl7W5K0FCQ+hPUoACgkQ1XDy006geT1Q0Q//atnw1D4J 13nL8Mygk+ANY4Xljub/TeZqKtzmnWGso843XysErLH1adCu1KDX1Dj4/o3WoPOt 0O78uSS81N428ocOPKx+fA63n7q1mRqHHy6pLLVKoT66tmvE1ZN0ObaiPK9IxZkB ThGlHJk9VaUg0vzAaRznogWeBh1dyZktVrtbUO5u4xDX9iql/unVmCWm+U1R7t4q fqPEbk8ZnWc7x4bAZf8/vSQ93mAbpnRRuJdDK9tsiuhl8pRz7OyzvMS81rVF75ja 7CcShPofrW4yZ7FqAUMwTbfrvsAraWmDjW17Ao7C2dUA9ViwSKJ6u6Pd5no/hwbm jVoxtO2RvjGOBxKneD36uENAUMBExjDTkSHmOxUYSknrEKUy7P1OL2ZHLG8/rouN 5ZvIxHiMkz12ukSt29IHvCngn1UB4/7+tvDHqug4ZAZPuwH7TC5Hk6WO0OoK8Eb2 sQa2QoehQjwK0IakGd5kFEqKgbrwYPPa3my7l58nOZmPHdMcTOzgKvUEYAITjsT4 oOtocs9Nj+cfCfp6YUn6JeYfiHs+Xhze5igdWIl0ZO5rTmbqcD8A1URKBds0WA+G FLP9shPC0rS/L3Y1fKhqAc0h+znWBU6xjipTkmzh3FdM8gGT6g9YwGQNbi/x47k5 vtBIWO4LPeGEvb2Gs65PL2eouOqU6yvBr5Y= =F/97 \-\-\-\-\-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 following mailing lists, per the previous tasks identified in our response procedure, will receive security\-relevant notifications: .INDENT 0.0 .IP \(bu 2 \fI\%salt\-packagers\fP .IP \(bu 2 \fI\%salt\-users\fP .IP \(bu 2 \fI\%salt\-announce\fP .UNINDENT .sp In addition to the mailing lists, SaltStack also provides the following resources: .INDENT 0.0 .IP \(bu 2 \fI\%SaltStack Security Announcements\fP landing page .IP \(bu 2 \fI\%SaltStack Security RSS Feed\fP .IP \(bu 2 \fI\%SaltStack Community Slack Workspace\fP .UNINDENT .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 .sp \fBWARNING:\fP .INDENT 0.0 .INDENT 3.5 We currently recommend that when using Syndics that all Masters and Minions use the same transport. We\(aqre investigating a report of an error when using mixed transport types at very heavy loads. .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 TLS Support .sp New in version 2016.11.1. .sp The TCP transport allows for the master/minion communication to be optionally wrapped in a TLS connection. Enabling this is simple, the master and minion need to be using the tcp connection, then the \fIssl\fP option is enabled. The \fIssl\fP option is passed as a dict and corresponds to the options passed to the Python \fIssl.wrap_socket \fP function. .sp A simple setup looks like this, on the Salt Master add the \fIssl\fP option to the master configuration file: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C ssl: keyfile: certfile: ssl_version: PROTOCOL_TLSv1_2 .ft P .fi .UNINDENT .UNINDENT .sp The minimal \fIssl\fP option in the minion configuration file looks like this: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C ssl: True # Versions below 2016.11.4: ssl: {} .ft P .fi .UNINDENT .UNINDENT .sp Specific options can be sent to the minion also, as defined in the Python \fIssl.wrap_socket\fP function. .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 While setting the ssl_version is not required, we recommend it. Some older versions of python do not support the latest TLS protocol and if this is the case for your version of python we strongly recommend upgrading your version of Python. .UNINDENT .UNINDENT .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 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 provides a pluggable and extendable replacement for it, allowing for multiple different subsystems to provide top file data. .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. Simply place them into \fBsalt://_tops\fP in the Salt fileserver and use the \fBsaltutil.sync_tops\fP runner to sync them. If this runner function is not available, they can manually be placed into \fBextmods/tops\fP, relative to the master cachedir (in most cases the full path will be \fB/var/cache/salt/master/extmods/tops\fP). .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 bare\-bones example: .sp \fB/etc/salt/master:\fP .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C master_tops: customtop: True .ft P .fi .UNINDENT .UNINDENT .sp \fBcustomtop.py:\fP (custom master_tops module) .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C import logging import sys # Define the module\(aqs virtual name __virtualname__ = "customtop" log = logging.getLogger(__name__) def __virtual__(): return __virtualname__ def top(**kwargs): log.debug("Calling top in customtop") return {"base": ["test"]} .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 .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 If a master_tops module returns top file data for a given minion, it will be added to the states configured in the top file. It will \fInot\fP replace it altogether. The 2018.3.0 release adds additional functionality allowing a minion to treat master_tops as the single source of truth, irrespective of the top file. .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.version \-\-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.version \-\-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.version command will be sent out to the three named returners. .SS Writing a Returner .sp Returners are Salt modules that allow the redirection of results data to targets other than the Salt Master. .SS Returners Are Easy To Write! .sp Writing a Salt returner is straightforward. .sp A returner is a Python module containing at minimum a \fBreturner\fP function. Other optional functions can be included to add support for \fBmaster_job_cache\fP, 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.version\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.version \-\-out=pprint .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C import redis import salt.utils.json def returner(ret): """ Return information to a redis server """ # Get a redis connection serv = redis.Redis(host="redis\-serv.example.com", port=6379, db="0") serv.sadd("%(id)s:jobs" % ret, ret["jid"]) serv.set("%(jid)s:%(id)s" % ret, salt.utils.json.dumps(ret["return"])) serv.sadd("jobs", ret["jid"]) serv.sadd(ret["jid"], ret["id"]) .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 Using Custom Returner Modules .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__ = "redis" def __virtual__(): if not HAS_REDIS: return False return __virtualname__ .ft P .fi .UNINDENT .UNINDENT .SS Master Job Cache Support .sp \fBmaster_job_cache\fP, external\-job\-cache, and \fI\%Event Returners\fP\&. Salt\(aqs \fBmaster_job_cache\fP 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 \fBnocache\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 """ Do any work necessary to prepare a JID, including sending a custom id """ 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. \fBminions\fP is a list of minions that the job was run against. 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 import salt.utils.json def save_load(jid, load, minions=None): """ Save the load to the specified jid id """ query = """INSERT INTO salt.jids ( jid, load ) VALUES ( \(aq{0}\(aq, \(aq{1}\(aq );""".format( jid, salt.utils.json.dumps(load) ) # cassandra_cql.cql_query may raise a CommandExecutionError try: __salt__["cassandra_cql.cql_query"](query) except CommandExecutionError: log.critical("Could not save load in jids table.") raise except Exception as e: log.critical("Unexpected error while inserting into jids: {0}".format(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): """ Return the load data that marks a specified jid """ query = """SELECT load FROM salt.jids WHERE jid = \(aq{0}\(aq;""".format(jid) ret = {} # cassandra_cql.cql_query may raise a CommandExecutionError try: data = __salt__["cassandra_cql.cql_query"](query) if data: load = data[0].get("load") if load: ret = json.loads(load) except CommandExecutionError: log.critical("Could not get load from jids table.") raise except Exception as e: log.critical( """Unexpected error while getting load from jids: {0}""".format( str(e) ) ) raise return ret .ft P .fi .UNINDENT .UNINDENT .SS External Job Cache Support .sp Salt\(aqs external\-job\-cache extends the \fBmaster_job_cache\fP\&. 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": "2018.3.4", "retcode": 0, "success": true, "cmd": "_return", "_stamp": "2015\-03\-30T12:10:12.708663", "fun": "test.version", "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.version", "minion3": "test.version", "minion2": "test.version" } } .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 import salt.utils.json def event_return(events): """ Return event to mysql server Requires that configuration be enabled via \(aqevent_return\(aq option in master config. """ with _get_serv(events, commit=True) as cur: for event in events: tag = event.get("tag", "") data = event.get("data", "") sql = """INSERT INTO \(gasalt_events\(ga (\(gatag\(ga, \(gadata\(ga, \(gamaster_id\(ga ) VALUES (%s, %s, %s)""" cur.execute(sql, (tag, salt.utils.json.dumps(data), __opts__["id"])) .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 \fBmaster_job_cache\fP and \fI\%Event Returners\fP in the master config file and submitting a job to \fBtest.version\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.version \-\-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{ \fBappoptics_return\fP T} T{ Salt returner to return highstate stats to AppOptics Metrics T} _ 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 inform 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{ \fBhighstate_return\fP T} T{ Return the results of a highstate (or any other state function that returns data in a compatible format) via an HTML email or HTML file. 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{ \fBlibrato_return\fP T} T{ Salt returner to return highstate stats to Librato T} _ T{ \fBlocal\fP T} T{ 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 T} _ T{ \fBlocal_cache\fP T} T{ Return data to local job cache T} _ T{ \fBmattermost_returner\fP T} T{ Return salt data via mattermost 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_nrdp_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{ \fBslack_webhook_return\fP T} T{ Return salt data via Slack using Incoming Webhooks 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 Requires the following config values to be specified in config or pillar: 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{ \fBtelegram_return\fP T} T{ Return salt data via Telegram. T} _ T{ \fBxmpp_return\fP T} T{ Return salt data via xmpp T} _ T{ \fBzabbix_return\fP T} T{ Return salt data to Zabbix T} _ .TE .SS salt.returners.appoptics_return module .sp Salt returner to return highstate stats to AppOptics Metrics .sp To enable this returner the minion will need the AppOptics Metrics client importable on the Python path and the following values configured in the minion or master config. .sp The AppOptics python client can be found at: .sp \fI\%https://github.com/appoptics/python\-appoptics\-metrics\fP .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C appoptics.api_token: abc12345def .ft P .fi .UNINDENT .UNINDENT .sp An example configuration that returns the total number of successes and failures for your salt highstate runs (the default) would look like this: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C return: appoptics appoptics.api_token: .ft P .fi .UNINDENT .UNINDENT .sp The returner publishes the following metrics to AppOptics: .INDENT 0.0 .IP \(bu 2 saltstack.failed .IP \(bu 2 saltstack.passed .IP \(bu 2 saltstack.retcode .IP \(bu 2 saltstack.runtime .IP \(bu 2 saltstack.total .UNINDENT .sp You can add a tags section to specify which tags should be attached to all metrics created by the returner. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C appoptics.tags: host_hostname_alias: tier: cluster: .ft P .fi .UNINDENT .UNINDENT .sp If no tags are explicitly configured, then the tag key \fBhost_hostname_alias\fP will be set, with the minion\(aqs \fBid\fP grain being the value. .sp In addition to the requested tags, for a highstate run each of these will be tagged with the \fBkey:value\fP of \fBstate_type: highstate\fP\&. .sp In order to return metrics for \fBstate.sls\fP runs (distinct from highstates), you can specify a list of state names to the key \fBappoptics.sls_states\fP like so: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C appoptics.sls_states: \- role_salt_master.netapi \- role_redis.config \- role_smarty.dummy .ft P .fi .UNINDENT .UNINDENT .sp This will report success and failure counts on runs of the \fBrole_salt_master.netapi\fP, \fBrole_redis.config\fP, and \fBrole_smarty.dummy\fP states in addition to highstates. .sp This will report the same metrics as above, but for these runs the metrics will be tagged with \fBstate_type: sls\fP and \fBstate_name\fP set to the name of the state that was invoked, e.g. \fBrole_salt_master.netapi\fP\&. .INDENT 0.0 .TP .B salt.returners.appoptics_return.returner(ret) Parse the return data and return metrics to AppOptics. .sp For each state that\(aqs provided in the configuration, return tagged metrics for the result of that state if it\(aqs present. .UNINDENT .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 .INDENT 0.0 .TP .B salt.returners.cassandra_cql_return.save_minions(jid, minions, syndic_id=None) Included for API consistency .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.save_minions(jid, minions, syndic_id=None) Included for API consistency .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 inform 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 .INDENT 0.0 .TP .B Minion configuration: .INDENT 7.0 .TP .B debug_returner_payload\(aq: False Output the payload being posted to the log file in debug mode .TP .B doc_type: \(aqdefault\(aq Document type to use for normal return messages .TP .B functions_blacklist Optional list of functions that should not be returned to elasticsearch .TP .B index_date: False Use a dated index (e.g. \-2016.11.29) .TP .B master_event_index: \(aqsalt\-master\-event\-cache\(aq Index to use when returning master events .TP .B master_event_doc_type: \(aqefault\(aq Document type to use got master events .TP .B master_job_cache_index: \(aqsalt\-master\-job\-cache\(aq Index to use for master job cache .TP .B master_job_cache_doc_type: \(aqdefault\(aq Document type to use for master job cache .TP .B number_of_shards: 1 Number of shards to use for the indexes .TP .B number_of_replicas: 0 Number of replicas to use for the indexes .UNINDENT .sp NOTE: The following options are valid for \(aqstate.apply\(aq, \(aqstate.sls\(aq and \(aqstate.highstate\(aq functions only. .INDENT 7.0 .TP .B states_count: False Count the number of states which succeeded or failed and return it in top\-level item called \(aqcounts\(aq. States reporting None (i.e. changes would be made but it ran in test mode) are counted as successes. .TP .B states_order_output: False Prefix the state UID (e.g. file_|\-yum_configured_|\-/etc/yum.conf_|\-managed) with a zero\-padded version of the \(aq__run_num__\(aq value to allow for easier sorting. Also store the state function (i.e. file.managed) into a new key \(aq_func\(aq. Change the index to be \(aq\-ordered\(aq (e.g. salt\-state_apply\-ordered). .TP .B states_single_index: False Store results for state.apply, state.sls and state.highstate in the salt\-state_apply index (or \-ordered/\-) indexes if enabled .UNINDENT .UNINDENT .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 debug_returner_payload: True states_count: True states_order_output: True states_single_index: True functions_blacklist: \- test.ping \- saltutil.find_job .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: 2379 .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: 2379 .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.clean_old_jobs() Included for API consistency .UNINDENT .INDENT 0.0 .TP .B salt.returners.etcd_return.get_fun(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 .INDENT 0.0 .TP .B salt.returners.etcd_return.save_minions(jid, minions, syndic_id=None) Included for API consistency .UNINDENT .SS salt.returners.highstate_return module .sp Return the results of a highstate (or any other state function that returns data in a compatible format) via an HTML email or HTML file. .sp New in version 2017.7.0. .sp Similar results can be achieved by using the smtp returner with a custom template, except an attempt at writing such a template for the complex data structure returned by highstate function had proven to be a challenge, not to mention that the smtp module doesn\(aqt support sending HTML mail at the moment. .sp The main goal of this returner was to produce an easy to read email similar to the output of highstate outputter used by the CLI. .sp This returner could be very useful during scheduled executions, but could also be useful for communicating the results of a manual execution. .sp Returner configuration is controlled in a standard fashion either via highstate group or an alternatively named group. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq state.highstate \-\-return highstate .ft P .fi .UNINDENT .UNINDENT .sp To use the alternative configuration, append \(aq\-\-return_config config\-name\(aq .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq state.highstate \-\-return highstate \-\-return_config simple .ft P .fi .UNINDENT .UNINDENT .sp Here is an example of what the configuration might look like: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C simple.highstate: report_failures: True report_changes: True report_everything: False failure_function: pillar.items success_function: pillar.items report_format: html report_delivery: smtp smtp_success_subject: \(aqsuccess minion {id} on host {host}\(aq smtp_failure_subject: \(aqfailure minion {id} on host {host}\(aq smtp_server: smtp.example.com smtp_recipients: saltusers@example.com, devops@example.com smtp_sender: salt@example.com .ft P .fi .UNINDENT .UNINDENT .sp The \fIreport_failures\fP, \fIreport_changes\fP, and \fIreport_everything\fP flags provide filtering of the results. If you want an email to be sent every time, then \fIreport_everything\fP is your choice. If you want to be notified only when changes were successfully made use \fIreport_changes\fP\&. And \fIreport_failures\fP will generate an email if there were failures. .sp The configuration allows you to run a salt module function in case of success (\fIsuccess_function\fP) or failure (\fIfailure_function\fP). .sp Any salt function, including ones defined in the _module folder of your salt repo, could be used here and its output will be displayed under the \(aqextra\(aq heading of the email. .sp Supported values for \fIreport_format\fP are html, json, and yaml. The latter two are typically used for debugging purposes, but could be used for applying a template at some later stage. .sp The values for \fIreport_delivery\fP are smtp or file. In case of file delivery the only other applicable option is \fIfile_output\fP\&. .sp In case of smtp delivery, smtp_* options demonstrated by the example above could be used to customize the email. .sp As you might have noticed, the success and failure subjects contain {id} and {host} values. Any other grain name could be used. As opposed to using {{grains[\(aqid\(aq]}}, which will be rendered by the master and contain master\(aqs values at the time of pillar generation, these will contain minion values at the time of execution. .INDENT 0.0 .TP .B salt.returners.highstate_return.returner(ret) Check highstate return information and possibly fire off an email or save a file. .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 .INDENT 0.0 .TP .B salt.returners.influxdb_return.save_minions(jid, minions, syndic_id=None) Included for API consistency .UNINDENT .SS salt.returners.kafka_return .sp Return data to a Kafka topic .INDENT 0.0 .TP .B maintainer Justin Desilets (\fI\%justin.desilets@gmail.com\fP) .TP .B maturity 20181119 .TP .B depends confluent\-kafka .TP .B platform all .UNINDENT .sp To enable this returner install confluent\-kafka and enable the following settings in the minion config: .INDENT 0.0 .INDENT 3.5 .INDENT 0.0 .TP .B returner.kafka.bootstrap: .INDENT 7.0 .IP \(bu 2 "server1:9092" .IP \(bu 2 "server2:9092" .IP \(bu 2 "server3:9092" .UNINDENT .UNINDENT .sp returner.kafka.topic: \(aqtopic\(aq .UNINDENT .UNINDENT .sp To use the kafka returner, append \fI\-\-return kafka\fP 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.librato_return .sp Salt returner to return highstate stats to Librato .sp To enable this returner the minion will need the Librato client importable on the Python path and the following values configured in the minion or master config. .sp The Librato python client can be found at: \fI\%https://github.com/librato/python\-librato\fP .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C librato.email: example@librato.com librato.api_token: abc12345def .ft P .fi .UNINDENT .UNINDENT .sp This return supports multi\-dimension metrics for Librato. To enable support for more metrics, the tags JSON object can be modified to include other tags. .sp Adding EC2 Tags example: If ec2_tags:region were desired within the tags for multi\-dimension. The tags could be modified to include the ec2 tags. Multiple dimensions are added simply by adding more tags to the submission. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C pillar_data = __salt__[\(aqpillar.raw\(aq]() q.add(metric.name, value, tags={\(aqName\(aq: ret[\(aqid\(aq],\(aqRegion\(aq: pillar_data[\(aqec2_tags\(aq][\(aqName\(aq]}) .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.returners.librato_return.returner(ret) Parse the return data and return metrics to Librato. .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 .sp To use the local returner, append \(aq\-\-return local\(aq to the salt command. ex: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq test.ping \-\-return local .ft P .fi .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.mattermost_returner module .sp Return salt data via mattermost .sp New in version 2017.7.0. .sp The following fields can be set in the minion conf file: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C mattermost.hook (required) mattermost.username (optional) mattermost.channel (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 mattermost.channel mattermost.hook mattermost.username .ft P .fi .UNINDENT .UNINDENT .sp mattermost settings may also be configured as: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C mattermost: channel: RoomName hook: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx username: user .ft P .fi .UNINDENT .UNINDENT .sp To use the mattermost returner, append \(aq\-\-return mattermost\(aq to the salt command. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq test.ping \-\-return mattermost .ft P .fi .UNINDENT .UNINDENT .sp To override individual configuration items, append \-\-return_kwargs \(aq{\(aqkey:\(aq: \(aqvalue\(aq}\(aq to the salt command. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq test.ping \-\-return mattermost \-\-return_kwargs \(aq{\(aqchannel\(aq: \(aq#random\(aq}\(aq .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.returners.mattermost_returner.event_return(events) Send the events to a mattermost room. .INDENT 7.0 .TP .B Parameters \fBevents\fP \-\- List of events .TP .B Returns Boolean if messages were sent successfully. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.returners.mattermost_returner.post_message(channel, message, username, api_url, hook) Send a message to a mattermost room. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBchannel\fP \-\- The room name. .IP \(bu 2 \fBmessage\fP \-\- The message to send to the mattermost room. .IP \(bu 2 \fBusername\fP \-\- Specify who the message is from. .IP \(bu 2 \fBhook\fP \-\- The mattermost hook, if not specified in the configuration. .UNINDENT .TP .B Returns Boolean if message was sent successfully. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.returners.mattermost_returner.returner(ret) Send an mattermost message with the data .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 .INDENT 0.0 .TP .B salt.returners.memcache_return.save_minions(jid, minions, syndic_id=None) Included for API consistency .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. MongoDB server can be configured by using host, port, db, user and password settings or by connection string URI (for pymongo > 2.3). 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 Or single URI: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C mongo.uri: URI .ft P .fi .UNINDENT .UNINDENT .sp where uri is in the format: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C mongodb://[username:password@]host1[:port1][,host2[:port2],...[,hostN[:portN]]][/[database][?options]] .ft P .fi .UNINDENT .UNINDENT .sp Example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C mongodb://db1.example.net:27017/mydatabase mongodb://db1.example.net:27017,db2.example.net:2500/?replicaSet=test mongodb://db1.example.net:27017,db2.example.net:2500/?replicaSet=test&connectTimeoutMS=300000 .ft P .fi .UNINDENT .UNINDENT .sp More information on URI format can be found in \fI\%https://docs.mongodb.com/manual/reference/connection\-string/\fP .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 Or single URI: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C alternative.mongo.uri: URI .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 .INDENT 0.0 .TP .B salt.returners.mongo_future_return.save_minions(jid, minions, syndic_id=None) Included for API consistency .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 .INDENT 0.0 .TP .B salt.returners.mongo_return.save_minions(jid, minions, syndic_id=None) Included for API consistency .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 .INDENT 0.0 .TP .B salt.returners.multi_returner.save_minions(jid, minions, syndic_id=None) Included for API consistency .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 will cause the data to stay in the tables. The default setting for \fIkeep_jobs\fP is set to \fI24\fP\&. .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; \-\- \-\- 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 .INDENT 0.0 .TP .B salt.returners.mysql.save_minions(jid, minions, syndic_id=None) Included for API consistency .UNINDENT .SS salt.returners.nagios_nrdp_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_nrdp_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 .INDENT 0.0 .TP .B salt.returners.odbc.save_minions(jid, minions, syndic_id=None) Included for API consistency .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 Stable .TP .B depends python\-psycopg2 .TP .B platform all .UNINDENT .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 There are three PostgreSQL returners. Any can function as an external master job cache\&. but each has different features. SaltStack recommends \fI\%returners.pgjsonb\fP if you are working with a version of PostgreSQL that has the appropriate native binary JSON types. Otherwise, review \fBreturners.postgres\fP and \fBreturners.postgres_local_cache\fP to see which module best suits your particular needs. .UNINDENT .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.sslmode: None returner.pgjsonb.sslcert: None returner.pgjsonb.sslkey: None returner.pgjsonb.sslrootcert: None returner.pgjsonb.sslcrl: None .ft P .fi .UNINDENT .UNINDENT .sp New in version 2017.5.0. .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 Should you wish the returner data to be cleaned out every so often, set \fBkeep_jobs\fP to the number of hours for the jobs to live in the tables. Setting it to \fB0\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 \fBarchive_jobs\fP to True. Salt will create 3 archive tables; .INDENT 0.0 .IP \(bu 2 \fBjids_archive\fP .IP \(bu 2 \fBsalt_returns_archive\fP .IP \(bu 2 \fBsalt_events_archive\fP .UNINDENT .sp and move the contents of \fBjids\fP, \fBsalt_returns\fP, and \fBsalt_events\fP that are more than \fBkeep_jobs\fP hours old to these tables. .sp New in version 2019.2.0. .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.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.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 .INDENT 0.0 .TP .B salt.returners.pgjsonb.save_minions(jid, minions, syndic_id=None) Included for API consistency .UNINDENT .SS salt.returners.postgres .sp Return data to a postgresql server .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 There are three PostgreSQL returners. Any can function as an external master job cache\&. but each has different features. SaltStack recommends \fBreturners.pgjsonb\fP if you are working with a version of PostgreSQL that has the appropriate native binary JSON types. Otherwise, review \fI\%returners.postgres\fP and \fBreturners.postgres_local_cache\fP 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 .INDENT 0.0 .TP .B salt.returners.postgres.save_minions(jid, minions, syndic_id=None) Included for API consistency .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 There are three PostgreSQL returners. Any can function as an external master job cache\&. but each has different features. SaltStack recommends \fBreturners.pgjsonb\fP if you are working with a version of PostgreSQL that has the appropriate native binary JSON types. Otherwise, review \fBreturners.postgres\fP and \fI\%returners.postgres_local_cache\fP 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 Stable .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 .INDENT 0.0 .TP .B salt.returners.postgres_local_cache.save_minions(jid, minions, syndic_id=None) Included for API consistency .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 \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 The \fBuser\fP here is your \fBuser key\fP, \fInot\fP the email address you use to login to pushover.net. .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(events) Write event data (return data and non\-return data) to 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 New in version 2018.3.1: Alternatively a UNIX socket can be specified by \fIunix_socket_path\fP: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C redis.db: \(aq0\(aq redis.unix_socket_path: /var/run/redis/redis.sock .ft P .fi .UNINDENT .UNINDENT .sp Cluster Mode Example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C redis.db: \(aq0\(aq redis.cluster_mode: true redis.cluster.skip_full_coverage_check: true redis.cluster.startup_nodes: \- host: redis\-member\-1 port: 6379 \- host: redis\-member\-2 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 .sp Redis Cluster Mode Options: .INDENT 0.0 .TP .B cluster_mode: \fBFalse\fP Whether cluster_mode is enabled or not .TP .B cluster.startup_nodes: A list of host, port dictionaries pointing to cluster members. At least one is required but multiple nodes are better .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C cache.redis.cluster.startup_nodes \- host: redis\-member\-1 port: 6379 \- host: redis\-member\-2 port: 6379 .ft P .fi .UNINDENT .UNINDENT .TP .B cluster.skip_full_coverage_check: \fBFalse\fP Some cluster providers restrict certain redis commands such as CONFIG for enhanced security. Set this option to true to skip checks that required advanced privileges. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 Most cloud hosted redis clusters will require this to be set to \fBTrue\fP .UNINDENT .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 .INDENT 0.0 .TP .B salt.returners.redis_return.save_minions(jid, minions, syndic_id=None) Included for API consistency .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 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.only_show_failed(optional, only show failed states) slack.yaml_format(optional, format the json in yaml format) .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 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.slack_webhook_return .sp Return salt data via Slack using Incoming Webhooks .INDENT 0.0 .TP .B codeauthor \fICarlos D. Álvaro \fP .UNINDENT .sp The following fields can be set in the minion conf file: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C slack_webhook.webhook (required, the webhook id. Just the part after: \(aqhttps://hooks.slack.com/services/\(aq) slack_webhook.success_title (optional, short title for succeeded states. By default: \(aq{id} | Succeeded\(aq) slack_webhook.failure_title (optional, short title for failed states. By default: \(aq{id} | Failed\(aq) slack_webhook.author_icon (optional, a URL that with a small 16x16px image. Must be of type: GIF, JPEG, PNG, and BMP) slack_webhook.show_tasks (optional, show identifiers for changed and failed tasks. By default: False) .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 slack_webhook.webhook slack_webhook.success_title slack_webhook.failure_title slack_webhook.author_icon slack_webhook.show_tasks .ft P .fi .UNINDENT .UNINDENT .sp Slack settings may also be configured as: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C slack_webhook: webhook: T00000000/B00000000/XXXXXXXXXXXXXXXXXXXXXXXX success_title: \(aq[{id}] | Success\(aq failure_title: \(aq[{id}] | Failure\(aq author_icon: https://platform.slack\-edge.com/img/default_application_icon.png show_tasks: true alternative.slack_webhook: webhook: T00000000/C00000000/YYYYYYYYYYYYYYYYYYYYYYYY show_tasks: false .ft P .fi .UNINDENT .UNINDENT .sp To use the Slack returner, append \(aq\-\-return slack_webhook\(aq to the salt command. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq test.ping \-\-return slack_webhook .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_webhook \-\-return_config alternative .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.returners.slack_webhook_return.returner(ret) Send a slack message with the data through a webhook :param ret: The Salt return :return: The result of the post .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: verify_ssl: true .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 class salt.returners.splunk.http_event_collector(token, http_event_server, host=\(aq\(aq, http_event_port=\(aq8088\(aq, http_event_server_ssl=True, max_bytes=100000, verify_ssl=True) .INDENT 7.0 .TP .B batchEvent(payload, eventtime=\(aq\(aq) .UNINDENT .INDENT 7.0 .TP .B flushBatch() .UNINDENT .INDENT 7.0 .TP .B sendEvent(payload, eventtime=\(aq\(aq) .UNINDENT .UNINDENT .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 .INDENT 0.0 .TP .B salt.returners.sqlite3_return.save_minions(jid, minions, syndic_id=None) Included for API consistency .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.telegram_return .sp Return salt data via Telegram. .sp The following fields can be set in the minion conf file: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C telegram.chat_id (required) telegram.token (required) .ft P .fi .UNINDENT .UNINDENT .sp Telegram settings may also be configured as: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C telegram: chat_id: 000000000 token: 000000000:xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx .ft P .fi .UNINDENT .UNINDENT .sp To use the Telegram return, append \(aq\-\-return telegram\(aq to the salt command. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq test.ping \-\-return telegram .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.returners.telegram_return.returner(ret) Send a Telegram message with the data. .INDENT 7.0 .TP .B Parameters \fBret\fP \-\- The data to be sent. .TP .B Returns Boolean if message was sent successfully. .UNINDENT .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 class salt.returners.xmpp_return.SendMsgBot(jid, password, recipient, msg) .INDENT 7.0 .TP .B start(event) .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.returners.xmpp_return.returner(ret) Send an xmpp message with the data .UNINDENT .SS salt.returners.zabbix_return module .sp Return salt data to Zabbix .sp The following Type: "Zabbix trapper" with "Type of information" Text items are required: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C Key: salt.trap.info Key: salt.trap.warning Key: salt.trap.high .ft P .fi .UNINDENT .UNINDENT .sp To use the Zabbix returner, append \(aq\-\-return zabbix\(aq to the salt command. ex: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq test.ping \-\-return zabbix .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.returners.zabbix_return.returner(ret) .UNINDENT .INDENT 0.0 .TP .B salt.returners.zabbix_return.save_load(jid, load, minions=None) Included for API consistency .UNINDENT .INDENT 0.0 .TP .B salt.returners.zabbix_return.zabbix_send(key, output) .UNINDENT .INDENT 0.0 .TP .B salt.returners.zabbix_return.zbx() .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 Salt Renderers translate input from the format in which it is written into Python data structures. .sp The default renderer is set in the master/minion configuration file using the \fBrenderer\fP config option, which defaults to \fBjinja|yaml\fP\&. .SS Two Kinds of Renderers .sp Renderers fall into one of two categories, based on what they output: text or data. The one exception to this would be the \fBpure python\fP renderer, which can be used in either capacity. .SS Text Renderers .sp A text renderer returns text. These include templating engines such as \fBjinja\fP, \fBmako\fP, and \fBgenshi\fP, as well as the \fBgpg\fP renderer. The following are all text renderers: .INDENT 0.0 .IP \(bu 2 \fBaws_kms\fP .IP \(bu 2 \fBcheetah\fP .IP \(bu 2 \fBgenshi\fP .IP \(bu 2 \fBgpg\fP .IP \(bu 2 \fBjinja\fP .IP \(bu 2 \fBmako\fP .IP \(bu 2 \fBnacl\fP .IP \(bu 2 \fBpass\fP .IP \(bu 2 \fBpy\fP .IP \(bu 2 \fBwempy\fP .UNINDENT .SS Data Renderers .sp A data renderer returns a Python data structure (typically a dictionary). The following are all data renderers: .INDENT 0.0 .IP \(bu 2 \fBdson\fP .IP \(bu 2 \fBhjson\fP .IP \(bu 2 \fBjson5\fP .IP \(bu 2 \fBjson\fP .IP \(bu 2 \fBpydsl\fP .IP \(bu 2 \fBpyobjects\fP .IP \(bu 2 \fBpy\fP .IP \(bu 2 \fBstateconf\fP .IP \(bu 2 \fByamlex\fP .IP \(bu 2 \fByaml\fP .UNINDENT .SS Overriding the Default Renderer .sp It can sometimes be beneficial to write an SLS file using a renderer other than the default one. This can be done by using a "shebang"\-like syntax on the first line of the SLS file: .sp Here is an example of using the \fBpure python\fP renderer to install a package: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C #!py def run(): """ Install version 1.5\-1.el7 of package "python\-foo" """ return { "include": ["python"], "python\-foo": {"pkg.installed": [{"version": "1.5\-1.el7"},]}, } .ft P .fi .UNINDENT .UNINDENT .sp This would be equivalent to the following: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C include: \- python python\-foo: pkg.installed: \- version: \(aq1.5\-1.el7\(aq .ft P .fi .UNINDENT .UNINDENT .SS Composing Renderers (a.k.a. The "Render Pipeline") .sp A render pipeline can be composed from other renderers by connecting them in a series of "pipes" (i.e. \fB|\fP). The renderers will be evaluated from left to right, with each renderer receiving the result of the previous renderer\(aqs execution. .sp Take for example the default renderer (\fBjinja|yaml\fP). The file is evaluated first a jinja template, and the result of that template is evaluated as a YAML document. .sp Other render pipeline combinations include: .INDENT 0.0 .INDENT 3.5 .INDENT 0.0 .TP .B \fByaml\fP Just YAML, no templating. .TP .B \fBmako|yaml\fP This passes the input to the \fBmako\fP renderer, with its output 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 render pipeline: .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 \fBIMPORTANT:\fP .INDENT 0.0 .INDENT 3.5 Keep in mind that not all renderers can be used alone or with any other renderers. For example, text 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 Python data structures. .sp For example, it would not make sense to use \fByaml|jinja\fP because the output of the \fByaml\fP renderer is a Python data structure, and the \fBjinja\fP renderer only accepts text as input. .sp Therefore, when combining renderers, you should know what each renderer accepts as input and what it returns as output. One way of thinking about it is that you can chain together multiple text renderers, but the pipeline \fImust\fP end in a data renderer. Similarly, since the text renderers in Salt don\(aqt accept data structures as input, a text renderer should usually not come after a data renderer. It\(aqs technically \fIpossible\fP to write a renderer that takes a data structure as input and returns a string, but no such renderer is distributed with Salt. .UNINDENT .UNINDENT .SS Writing Renderers .sp A custom renderer must be a Python module which implements a \fBrender\fP function. This function must implement three positional arguments: .INDENT 0.0 .IP 1. 3 \fBdata\fP \- Can be called whatever you like. This is the input to be rendered. .IP 2. 3 \fBsaltenv\fP .IP 3. 3 \fBsls\fP .UNINDENT .sp The first is the important one, and the 2nd and 3rd must be included since Salt needs to pass this info to each render, even though it is only used by template renderers. .sp Renderers should be written so that the \fBdata\fP argument can accept either strings or file\-like objects as input. For example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C import mycoolmodule from salt.ext import six def render(data, saltenv="base", sls="", **kwargs): if not isinstance(data, six.string_types): # Read from file\-like object data = data.read() return mycoolmodule.do_something(data) .ft P .fi .UNINDENT .UNINDENT .sp Custom renderers should be placed within \fBsalt://_renderers/\fP, so that they can be synced to minions. They are synced 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. .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 Renderers can also be synced from \fBsalt://_renderers/\fP to the Master using either the \fBsaltutil.sync_renderers\fP or \fBsaltutil.sync_all\fP runner function. .UNINDENT .UNINDENT .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/master/salt/renderers\fP .sp Here is a simple YAML renderer example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C import salt.utils.yaml from salt.utils.yamlloader import SaltYamlSafeLoader from salt.ext import six def render(yaml_data, saltenv="", sls="", **kws): if not isinstance(yaml_data, six.string_types): yaml_data = yaml_data.read() data = salt.utils.yaml.safe_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{ \fBaws_kms\fP T} T{ T} _ 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{ \fBnacl\fP T} T{ Renderer that will decrypt NACL ciphers T} _ T{ \fBpass\fP T} T{ Pass Renderer for Salt 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{ \fBtoml\fP T} T{ 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.aws_kms .sp Renderer that will decrypt ciphers encrypted using \fI\%AWS KMS Envelope Encryption\fP\&. .sp Any key in the data to be rendered can be a urlsafe_b64encoded string, and this renderer will attempt to 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 the encrypted data key on your master. This way developers with appropriate AWS IAM privileges can add new secrets quickly and easily. .sp This renderer requires the \fI\%boto3\fP Python library. .SS Setup .sp First, set up your AWS client. For complete instructions on configuration the AWS client, please read the \fI\%boto3 configuration documentation\fP\&. By default, this renderer will use the default AWS profile. You can override the profile name in salt configuration. For example, if you have a profile in your aws client configuration named "salt", you can add the following salt configuration: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C aws_kms: profile_name: salt .ft P .fi .UNINDENT .UNINDENT .sp The rest of these instructions assume that you will use the default profile for key generation and setup. If not, export AWS_PROFILE and set it to the desired value. .sp Once the aws client is configured, generate a KMS customer master key and use that to generate a local data key. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C # data_key=$(aws kms generate\-data\-key \-\-key\-id your\-key\-id \-\-key\-spec AES_256 \-\-query \(aqCiphertextBlob\(aq \-\-output text) # echo \(aqaws_kms:\(aq # echo \(aq data_key: !!binary "%s"\en\(aq "$data_key" >> config/master .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|aws_kms .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|aws_kms a\-secret: gAAAAABaj5uzShPI3PEz6nL5Vhk2eEHxGXSZj8g71B84CZsVjAAtDFY1mfjNRl\-1Su9YVvkUzNjI4lHCJJfXqdcTvwczBYtKy0Pa7Ri02s10Wn1tF0tbRwk= .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.renderers.aws_kms.render(data, saltenv=\(aqbase\(aq, sls=\(aq\(aq, argline=\(aq\(aq, **kwargs) Decrypt the data to be rendered that was encrypted using AWS KMS envelope encryption. .UNINDENT .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 GPG Homedir .sp When running gpg commands, it is important to run commands as the user that owns the keys directory. If salt\-master runs as user salt, then \fBsu salt\fP before running any gpg commands. .sp To avoid compatibility and upgrade problems and to provide a standardized location for keys, salt uses \fB/etc/salt/gpgkeys\fP\&. In order to make the gpg command use this directory, use \fBgpg \-\-homedir /etc/salt/gpgkeys\fP with gpg commands or set the homedir for that user using \fBecho \(aqhomedir /etc/salt/gpgkeys\(aq >> ~/.gnupg\fP\&. .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 Import keys to a master .sp If the keys already exist and need to be imported to the salt master, run the following to import them. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C gpg \-\-homedir /etc/salt/gpgkeys \-\-import /path/to/private.key gpg \-\-homedir /etc/salt/gpgkeys \-\-import /path/to/pubkey.gpg .ft P .fi .UNINDENT .UNINDENT .sp Note: The default \fIGPG Homedir \fP is \fB~/.gnupg\fP and needs to be set using \fB\-\-homedir\fP\&. .SS Adjust trust level of imported keys .sp In some cases, importing existing keys may not be enough and the trust level of the key needs to be adjusted. This can be done by editing the key. The \fBkey_id\fP and the actual trust level of the key can be seen by listing the already imported keys. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C gpg \-\-homedir /etc/salt/gpgkeys \-\-list\-keys gpg \-\-homedir /etc/salt/gpgkeys \-\-list\-secret\-keys .ft P .fi .UNINDENT .UNINDENT .sp If the trust\-level is not \fBultimate\fP it needs to be changed by running .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C gpg \-\-homedir /etc/salt/gpgkeys \-\-edit\-key .ft P .fi .UNINDENT .UNINDENT .sp This will open an interactive shell for the management of the GPG encryption key. Type \fBtrust\fP to be able to set the trust level for the key and then select \fB5 (I trust ultimately)\fP\&. Then quit the shell by typing \fBsave\fP\&. .SS Different GPG Location .sp In some cases, it\(aqs preferable to have gpg keys stored on removable media or other non\-standard locations. This can be done using the \fBgpg_keydir\fP option on the salt master. This will also require using a different path to \fB\-\-homedir\fP, as mentioned in the \fIGPG Homedir \fP section. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C gpg_keydir: .ft P .fi .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 .sp See the \fI\%hjson\fP documentation for more information .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 }} xml = {{ {\(aqroot_node\(aq: data}|xml }} .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} xml = """< 1 2 3 """ .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 .sp ** Escape Filters ** .sp New in version 2017.7.0. .sp Allows escaping of strings so they can be interpreted literally by another function. .sp For example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C regex_escape = {{ \(aqhttps://example.com?foo=bar%20baz\(aq | regex_escape }} .ft P .fi .UNINDENT .UNINDENT .sp will be rendered as: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C regex_escape = https\e:\e/\e/example\e.com\e?foo\e=bar\e%20baz .ft P .fi .UNINDENT .UNINDENT .sp ** Set Theory Filters ** .sp New in version 2017.7.0. .sp Performs set math using Jinja filters. .sp For example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C unique = {{ [\(aqfoo\(aq, \(aqfoo\(aq, \(aqbar\(aq] | unique }} .ft P .fi .UNINDENT .UNINDENT .sp will be rendered as: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C unique = [\(aqfoo\(aq, \(aqbar\(aq] .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.nacl .sp Renderer that will decrypt NACL ciphers .sp Any key in the SLS file can be an NACL 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 libsodium library binary and libnacl >= 1.5.1 python package (support for sealed boxes came in 1.5.1 version). .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 # salt\-call \-\-local nacl.keygen sk_file=/root/.nacl .ft P .fi .UNINDENT .UNINDENT .SS Using encrypted pillar .sp To encrypt secrets, copy the public key to your local machine and run: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C $ salt\-call \-\-local nacl.enc datatoenc pk_file=/root/.nacl.pub .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 nacl encrypted data in it: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C #!yaml|nacl .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|nacl a\-secret: "NACL[MRN3cc+fmdxyQbz6WMF+jq1hKdU5X5BBI7OjK+atvHo1ll+w1gZ7XyWtZVfq9gK9rQaMfkDxmidJKwE0Mw==]" .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.renderers.nacl.render(nacl_data, saltenv=\(aqbase\(aq, sls=\(aq\(aq, argline=\(aq\(aq, **kwargs) Decrypt the data to be rendered using the given nacl key or the one given in config .UNINDENT .SS salt.renderers.pass module .SS Pass Renderer for Salt .sp \fI\%pass\fP is an encrypted on\-disk password store. .sp New in version 2017.7.0. .SS Setup .sp \fINote\fP: \fB\fP needs to be replaced with the user salt\-master will be running as. .sp Have private gpg loaded into \fBuser\fP\(aqs gpg keyring .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C load_private_gpg_key: cmd.run: \- name: gpg \-\-import \- unless: gpg \-\-list\-keys \(aq\(aq .ft P .fi .UNINDENT .UNINDENT .sp Said private key\(aqs public key should have been used when encrypting pass entries that are of interest for pillar data. .sp Fetch and keep local pass git repo up\-to\-date .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C update_pass: git.latest: \- force_reset: True \- name: \- target: //.password\-store \- identity: \- require: \- cmd: load_private_gpg_key .ft P .fi .UNINDENT .UNINDENT .sp Install pass binary .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C pass: pkg.installed .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.renderers.pass.render(pass_info, saltenv=\(aqbase\(aq, sls=\(aq\(aq, argline=\(aq\(aq, **kwargs) Fetch secret from pass based on pass_path .UNINDENT .SS salt.renderers.py .SS Pure python state renderer .sp To use this renderer, the SLS file should contain a function called \fBrun\fP which returns highstate data. .sp The highstate data is a dictionary containing identifiers as keys, and execution dictionaries as values. For example the following state declaration in YAML: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C common_packages: pkg.installed: \- pkgs: \- curl \- vim .ft P .fi .UNINDENT .UNINDENT .sp translates to: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C {\(aqcommon_packages\(aq: {\(aqpkg.installed\(aq: [{\(aqpkgs\(aq: [\(aqcurl\(aq, \(aqvim\(aq]}]}} .ft P .fi .UNINDENT .UNINDENT .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 .sp When writing a reactor SLS file the global context \fBdata\fP (same as context \fB{{ data }}\fP for states written with Jinja + YAML) is available. The following YAML + Jinja state declaration: .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 translates to: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C if data[\(aqid\(aq] == \(aqmysql1\(aq: return {\(aqhighstate_run\(aq: {\(aqlocal.state.apply\(aq: [{\(aqtgt\(aq: \(aqmysql1\(aq}]}} .ft P .fi .UNINDENT .UNINDENT .SS Full Example .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 = six.text_type(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 .INDENT 0.0 .TP .B exception salt.renderers.pydsl.PyDslError .UNINDENT .INDENT 0.0 .TP .B exception salt.renderers.pydsl.SaltRenderError(message, line_num=None, buf=\(aq\(aq, marker=\(aq <======================\(aq, trace=None) Used when a renderer needs to raise an explicit error. If a line number and buffer string are passed, get_context will be invoked to get the location of the error. .UNINDENT .INDENT 0.0 .TP .B salt.renderers.pydsl.exec_(source, globals=None, locals=None, /) Execute the given source in the context of globals and locals. .sp The source may be a string representing one or more Python statements or a code object as returned by compile(). The globals must be a dictionary and locals can be any mapping, defaulting to the current globals and locals. If only globals is given, locals defaults to it. .UNINDENT .INDENT 0.0 .TP .B salt.renderers.pydsl.render(template, saltenv=\(aqbase\(aq, sls=\(aq\(aq, tmplpath=None, rendered_sls=None, **kws) .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 # NOTE: priority is new to 2017.7.0 priority = (\(aqos_family\(aq, \(aqos\(aq) class Ubuntu: __grain__ = \(aqos\(aq service = \(aqsmbd\(aq class Debian: server = \(aqsamba\(aq client = \(aqsamba\-client\(aq service = \(aqsamba\(aq class RHEL: __match__ = \(aqRedHat\(aq server = \(aqsamba\(aq client = \(aqsamba\(aq service = \(aqsmb\(aq .ft P .fi .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 By default, the \fBos_family\fP grain will be used as the target for matching. This can be overridden by specifying a \fB__grain__\fP attribute. .sp If a \fB__match__\fP attribute is defined for a given class, then that value will be matched against the targeted grain, otherwise the class name\(aqs value will be be matched. .sp Given the above example, the following is true: .INDENT 0.0 .IP 1. 3 Minions with an \fBos_family\fP of \fBDebian\fP will be assigned the attributes defined in the \fBDebian\fP class. .IP 2. 3 Minions with an \fBos\fP grain of \fBUbuntu\fP will be assigned the attributes defined in the \fBUbuntu\fP class. .IP 3. 3 Minions with an \fBos_family\fP grain of \fBRedHat\fP will be assigned the attributes defined in the \fBRHEL\fP class. .UNINDENT .sp That said, sometimes a minion may match more than one class. For instance, in the above example, Ubuntu minions will match both the \fBDebian\fP and \fBUbuntu\fP classes, since Ubuntu has an \fBos_family\fP grain of \fBDebian\fP and an \fBos\fP grain of \fBUbuntu\fP\&. As of the 2017.7.0 release, the order is dictated by the order of declaration, with classes defined later overriding earlier ones. Additionally, 2017.7.0 adds support for explicitly defining the ordering using an optional attribute called \fBpriority\fP\&. .sp Given the above example, \fBos_family\fP matches will be processed first, with \fBos\fP matches processed after. This would have the effect of assigning \fBsmbd\fP as the \fBservice\fP attribute on Ubuntu minions. If the \fBpriority\fP item was not defined, or if the order of the items in the \fBpriority\fP tuple were reversed, Ubuntu minions would have a \fBservice\fP attribute of \fBsamba\fP, since \fBos_family\fP matches would have been processed second. .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 .INDENT 0.0 .TP .B salt.renderers.pyobjects.render(template, saltenv=\(aqbase\(aq, sls=\(aq\(aq, salt_data=True, **kwargs) .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.toml .INDENT 0.0 .TP .B salt.renderers.toml.render(sls_data, saltenv=\(aqbase\(aq, sls=\(aq\(aq, **kws) Accepts TOML as a string or as a file object and runs it through the parser. .INDENT 7.0 .TP .B Return type A Python data structure .UNINDENT .UNINDENT .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 {"my_key": "my_value"} .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 {"first_level_dict_key": {"second_level_dict_key": "value_in_second_level_dict"}} .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 Using grains in a state .sp To use a grain in a state you can access it via \fI{{ grains[\(aqkey\(aq] }}\fP\&. .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 it possible to target based on specific data about your deployment, as in the example above. .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 .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 Grains in \fB/etc/salt/grains\fP are ignored if you specify the same grains in the minion config. .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 Grains are static, and since they are not often changed, they will need a grains refresh when they are updated. You can do this by calling: \fBsalt minion saltutil.refresh_modules\fP .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 You can equally configure static grains for Proxy Minions. As multiple Proxy Minion processes can run on the same machine, you need to index the files using the Minion ID, under \fB/etc/salt/proxy.d//grains\fP\&. For example, the grains for the Proxy Minion \fBrouter1\fP can be defined under \fB/etc/salt/proxy.d/router1/grains\fP, while the grains for the Proxy Minion \fBswitch7\fP can be put in \fB/etc/salt/proxy.d/switch7/grains\fP\&. .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 \(aqroles:webserver\(aq: \- match: grain \- state0 \(aqroles:memcache\(aq: \- match: grain \- state1 \- state2 .ft P .fi .UNINDENT .UNINDENT .sp For this example to work, you would need to have defined the grain \fBrole\fP for the minions you wish to match. .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 \fI\%Python dictionary\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["yourcustomgrain"] = True grains["anothergrain"] = "somevalue" 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 = {"foo": "bar", "hello": "world"} return my_grain def main(): # initialize a grains dictionary grains = {} grains["my_grains"] = _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. .sp For custom grains, if the function takes an argument \fBgrains\fP, then the previously rendered grains will be passed in. Because the rest of the grains could be rendered in any order, the only grains that can be relied upon to be passed in are \fBcore\fP grains. This was added in the 2019.2.0 release. .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/master/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. .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 When the \fBgrains_cache\fP is set to False, the grains dictionary is built and stored in memory on the minion. Every time the minion restarts or \fBsaltutil.refresh_grains\fP is run, the grain dictionary is rebuilt from scratch. .UNINDENT .UNINDENT .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 maps 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 Pillar definitions can also take a keyword argument \fBignore_missing\fP\&. When the value of \fBignore_missing\fP is \fBTrue\fP, all errors for missing pillar files are ignored. The default value for \fBignore_missing\fP is \fBFalse\fP\&. .sp Here is an example using the \fBignore_missing\fP keyword parameter to ignore errors for missing pillar files: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C base: \(aq*\(aq: \- servers \- systems \- ignore_missing: True .ft P .fi .UNINDENT .UNINDENT .sp Assuming that the pillar \fBservers\fP exists in the fileserver backend and the pillar \fBsystems\fP doesn\(aqt, all pillar data from \fBservers\fP pillar is delivered to minions and no error for the missing pillar \fBsystems\fP is noted under the key \fB_errors\fP in the pillar data delivered to minions. .sp Should the \fBignore_missing\fP keyword parameter have the value \fBFalse\fP, an error for the missing pillar \fBsystems\fP would produce the value \fBSpecified SLS \(aqservers\(aq in environment \(aqbase\(aq is not available on the salt master\fP under the key \fB_errors\fP in the pillar data delivered to minions. .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 dictionary: .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 .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 When working with multiple pillar environments, assuming that each pillar environment has its own top file, the jinja placeholder \fB{{ saltenv }}\fP can be used in place of the environment name: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C {{ saltenv }}: \(aq*\(aq: \- common_pillar .ft P .fi .UNINDENT .UNINDENT .sp Yes, this is \fB{{ saltenv }}\fP, and not \fB{{ pillarenv }}\fP\&. The reason for this is because the Pillar top files are parsed using some of the same code which parses top files when running states, so the pillar environment takes the place of \fB{{ saltenv }}\fP in the jinja context. .UNINDENT .UNINDENT .SS Dynamic Pillar Environments .sp If environment \fB__env__\fP is specified in \fBpillar_roots\fP, all environments that are not explicitly specified in \fBpillar_roots\fP will map to the directories from \fB__env__\fP\&. This allows one to use dynamic git branch based environments for state/pillar files with the same file\-based pillar applying to all environments. For example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C pillar_roots: __env__: \- /srv/pillar ext_pillar: \- git: \- __env__ https://example.com/git\-pillar.git .ft P .fi .UNINDENT .UNINDENT .sp New in version 2017.7.5,2018.3.1. .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 .sp Starting in the 2017.7.0 release, it is possible to pin the pillarenv to the effective saltenv, using the \fBpillarenv_from_saltenv\fP minion config option. When this is set to \fBTrue\fP, if a specific saltenv is specified when running states, the \fBpillarenv\fP will be the same. This essentially makes the following two commands equivalent: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq state.apply mystates saltenv=dev salt \(aq*\(aq state.apply mystates saltenv=dev pillarenv=dev .ft P .fi .UNINDENT .UNINDENT .sp However, if a pillarenv is specified, it will override this behavior. So, the following command will use the \fBqa\fP pillar environment but source the SLS files from the \fBdev\fP saltenv: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq state.apply mystates saltenv=dev pillarenv=qa .ft P .fi .UNINDENT .UNINDENT .sp So, if a \fBpillarenv\fP is set in the minion config file, \fBpillarenv_from_saltenv\fP will be ignored, and passing a \fBpillarenv\fP on the CLI will temporarily override \fBpillarenv_from_saltenv\fP\&. .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 data\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 Pillar Encryption .sp Salt\(aqs renderer system can be used to decrypt pillar data. This allows for pillar items to be stored in an encrypted state, and decrypted during pillar compilation. .SS Encrypted Pillar SLS .sp New in version 2017.7.0. .sp Consider the following pillar SLS file: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C secrets: vault: foo: | \-\-\-\-\-BEGIN PGP MESSAGE\-\-\-\-\- hQEMAw2B674HRhwSAQgAhTrN8NizwUv/VunVrqa4/X8t6EUulrnhKcSeb8sZS4th W1Qz3K2NjL4lkUHCQHKZVx/VoZY7zsddBIFvvoGGfj8+2wjkEDwFmFjGE4DEsS74 ZLRFIFJC1iB/O0AiQ+oU745skQkU6OEKxqavmKMrKo3rvJ8ZCXDC470+i2/Hqrp7 +KWGmaDOO422JaSKRm5D9bQZr9oX7KqnrPG9I1+UbJyQSJdsdtquPWmeIpamEVHb VMDNQRjSezZ1yKC4kCWm3YQbBF76qTHzG1VlLF5qOzuGI9VkyvlMaLfMibriqY73 zBbPzf6Bkp2+Y9qyzuveYMmwS4sEOuZL/PetqisWe9JGAWD/O+slQ2KRu9hNww06 KMDPJRdyj5bRuBVE4hHkkP23KrYr7SuhW2vpe7O/MvWEJ9uDNegpMLhTWruGngJh iFndxegN9w== =bAuo \-\-\-\-\-END PGP MESSAGE\-\-\-\-\- bar: this was unencrypted already baz: | \-\-\-\-\-BEGIN PGP MESSAGE\-\-\-\-\- hQEMAw2B674HRhwSAQf+Ne+IfsP2IcPDrUWct8sTJrga47jQvlPCmO+7zJjOVcqz gLjUKvMajrbI/jorBWxyAbF+5E7WdG9WHHVnuoywsyTB9rbmzuPqYCJCe+ZVyqWf 9qgJ+oUjcvYIFmH3h7H68ldqbxaAUkAOQbTRHdr253wwaTIC91ZeX0SCj64HfTg7 Izwk383CRWonEktXJpientApQFSUWNeLUWagEr/YPNFA3vzpPF5/Ia9X8/z/6oO2 q+D5W5mVsns3i2HHbg2A8Y+pm4TWnH6mTSh/gdxPqssi9qIrzGQ6H1tEoFFOEq1V kJBe0izlfudqMq62XswzuRB4CYT5Iqw1c97T+1RqENJCASG0Wz8AGhinTdlU5iQl JkLKqBxcBz4L70LYWyHhYwYROJWjHgKAywX5T67ftq0wi8APuZl9olnOkwSK+wrY 1OZi =7epf \-\-\-\-\-END PGP MESSAGE\-\-\-\-\- qux: \- foo \- bar \- | \-\-\-\-\-BEGIN PGP MESSAGE\-\-\-\-\- hQEMAw2B674HRhwSAQgAg1YCmokrweoOI1c9HO0BLamWBaFPTMblOaTo0WJLZoTS ksbQ3OJAMkrkn3BnnM/djJc5C7vNs86ZfSJ+pvE8Sp1Rhtuxh25EKMqGOn/SBedI gR6N5vGUNiIpG5Tf3DuYAMNFDUqw8uY0MyDJI+ZW3o3xrMUABzTH0ew+Piz85FDA YrVgwZfqyL+9OQuu6T66jOIdwQNRX2NPFZqvon8liZUPus5VzD8E5cAL9OPxQ3sF f7/zE91YIXUTimrv3L7eCgU1dSxKhhfvA2bEUi+AskMWFXFuETYVrIhFJAKnkFmE uZx+O9R9hADW3hM5hWHKH9/CRtb0/cC84I9oCWIQPdI+AaPtICxtsD2N8Q98hhhd 4M7I0sLZhV+4ZJqzpUsOnSpaGyfh1Zy/1d3ijJi99/l+uVHuvmMllsNmgR+ZTj0= =LrCQ \-\-\-\-\-END PGP MESSAGE\-\-\-\-\- .ft P .fi .UNINDENT .UNINDENT .sp When the pillar data is compiled, the results will be decrypted: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C # salt myminion pillar.items myminion: \-\-\-\-\-\-\-\-\-\- secrets: \-\-\-\-\-\-\-\-\-\- vault: \-\-\-\-\-\-\-\-\-\- bar: this was unencrypted already baz: rosebud foo: supersecret qux: \- foo \- bar \- baz .ft P .fi .UNINDENT .UNINDENT .sp Salt must be told what portions of the pillar data to decrypt. This is done using the \fBdecrypt_pillar\fP config option: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C decrypt_pillar: \- \(aqsecrets:vault\(aq: gpg .ft P .fi .UNINDENT .UNINDENT .sp The notation used to specify the pillar item(s) to be decrypted is the same as the one used in \fBpillar.get\fP function. .sp If a different delimiter is needed, it can be specified using the \fBdecrypt_pillar_delimiter\fP config option: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C decrypt_pillar: \- \(aqsecrets|vault\(aq: gpg decrypt_pillar_delimiter: \(aq|\(aq .ft P .fi .UNINDENT .UNINDENT .sp The name of the renderer used to decrypt a given pillar item can be omitted, and if so it will fall back to the value specified by the \fBdecrypt_pillar_default\fP config option, which defaults to \fBgpg\fP\&. So, the first example above could be rewritten as: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C decrypt_pillar: \- \(aqsecrets:vault\(aq .ft P .fi .UNINDENT .UNINDENT .SS Encrypted Pillar Data on the CLI .sp New in version 2016.3.0. .sp The following functions support passing pillar data on the CLI via the \fBpillar\fP argument: .INDENT 0.0 .IP \(bu 2 \fBpillar.items\fP .IP \(bu 2 \fBstate.apply\fP .IP \(bu 2 \fBstate.highstate\fP .IP \(bu 2 \fBstate.sls\fP .UNINDENT .sp Triggerring decryption of this CLI pillar data can be done in one of two ways: .INDENT 0.0 .IP 1. 3 Using the \fBpillar_enc\fP argument: .INDENT 3.0 .INDENT 3.5 .sp .nf .ft C # salt myminion pillar.items pillar_enc=gpg pillar=\(aq{foo: "\-\-\-\-\-BEGIN PGP MESSAGE\-\-\-\-\-\en\enhQEMAw2B674HRhwSAQf+OvPqEdDoA2fk15I5dYUTDoj1yf/pVolAma6iU4v8Zixn\enRDgWsaAnFz99FEiFACsAGDEFdZaVOxG80T0Lj+PnW4pVy0OXmXHnY2KjV9zx8FLS\enQxfvmhRR4t23WSFybozfMm0lsN8r1vfBBjbK+A72l0oxN78d1rybJ6PWNZiXi+aC\enmqIeunIbAKQ21w/OvZHhxH7cnIiGQIHc7N9nQH7ibyoKQzQMSZeilSMGr2abAHun\enmLzscr4wKMb+81Z0/fdBfP6g3bLWMJga3hSzSldU9ovu7KR8rDJI1qOlENj3Wm8C\enwTpDOB33kWIKMqiAjY3JFtb5MCHrafyggwQL7cX1+tI+AbSO6kZpbcDfzetb77LZ\enxc5NWnnGK4pGoqq4MAmZshw98RpecSHKMosto2gtiuWCuo9Zn5cV/FbjZ9CTWrQ=\en=0hO/\en\-\-\-\-\-END PGP MESSAGE\-\-\-\-\-"}\(aq .ft P .fi .UNINDENT .UNINDENT .sp The newlines in this example are specified using a literal \fB\en\fP\&. Newlines can be replaced with a literal \fB\en\fP using \fBsed\fP: .INDENT 3.0 .INDENT 3.5 .sp .nf .ft C $ echo \-n bar | gpg \-\-armor \-\-trust\-model always \-\-encrypt \-r user@domain.tld | sed \(aq:a;N;$!ba;s/\en/\e\en/g\(aq .ft P .fi .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 3.0 .INDENT 3.5 Using \fBpillar_enc\fP will perform the decryption minion\-side, so for this to work it will be necessary to set up the keyring in \fB/etc/salt/gpgkeys\fP on the minion just as one would typically do on the master. The easiest way to do this is to first export the keys from the master: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C # gpg \-\-homedir /etc/salt/gpgkeys \-\-export\-secret\-key \-a user@domain.tld >/tmp/keypair.gpg .ft P .fi .UNINDENT .UNINDENT .sp Then, copy the file to the minion, setup the keyring, and import: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C # mkdir \-p /etc/salt/gpgkeys # chmod 0700 /etc/salt/gpgkeys # gpg \-\-homedir /etc/salt/gpgkeys \-\-list\-keys # gpg \-\-homedir /etc/salt/gpgkeys \-\-import \-\-allow\-secret\-key\-import keypair.gpg .ft P .fi .UNINDENT .UNINDENT .sp The \fB\-\-list\-keys\fP command is run create a keyring in the newly\-created directory. .UNINDENT .UNINDENT .sp Pillar data which is decrypted minion\-side will still be securely transferred to the master, since the data sent between minion and master is encrypted with the master\(aqs public key. .IP 2. 3 Use the \fBdecrypt_pillar\fP option. This is less flexible in that the pillar key passed on the CLI must be pre\-configured on the master, but it doesn\(aqt require a keyring to be setup on the minion. One other caveat to this method is that pillar decryption on the master happens at the end of pillar compilation, so if the encrypted pillar data being passed on the CLI needs to be referenced by pillar or ext_pillar \fIduring pillar compilation\fP, it \fImust\fP be decrypted minion\-side. .UNINDENT .SS Adding New Renderers for Decryption .sp Those looking to add new renderers for decryption should look at the \fBgpg\fP renderer for an example of how to do so. The function that performs the decryption should be recursive and be able to traverse a mutable type such as a dictionary, and modify the values in\-place. .sp Once the renderer has been written, \fBdecrypt_pillar_renderers\fP should be modified so that Salt allows it to be used for decryption. .sp If the renderer is being submitted upstream to the Salt project, the renderer should be added in \fI\%salt/renderers/\fP\&. Additionally, the following should be done: .INDENT 0.0 .IP \(bu 2 Both occurrences of \fBdecrypt_pillar_renderers\fP in \fI\%salt/config/__init__.py\fP should be updated to include the name of the new renderer so that it is included in the default value for this config option. .IP \(bu 2 The documentation for the \fBdecrypt_pillar_renderers\fP config option in the \fI\%master config file\fP and \fI\%minion config file\fP should be updated to show the correct new default value. .IP \(bu 2 The commented example for the \fBdecrypt_pillar_renderers\fP config option in the \fI\%master config template\fP should be updated to show the correct new default value. .UNINDENT .SS Binary Data in the Pillar .sp Salt has partial support for binary pillar data. .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 There are some situations (such as salt\-ssh) where only text (ASCII or Unicode) is allowed. .UNINDENT .UNINDENT .sp The simplest way to embed binary data in your pillar is to make use of YAML\(aqs built\-in binary data type, which requires base64 encoded data. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt_pic: !!binary iVBORw0KGgoAAAANSUhEUgAAAAoAAAAKCAMAAAC67D+PAAAABGdBTUEAALGPC/xhBQAAACBjSFJNAA .ft P .fi .UNINDENT .UNINDENT .sp Then you can use it as a \fBcontents_pillar\fP in a state: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C /tmp/salt.png: file.managed: \- contents_pillar: salt_pic .ft P .fi .UNINDENT .UNINDENT .sp It is also possible to add ASCII\-armored encrypted data to pillars, as mentioned in the Pillar Encryption section. .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 minion as pillar, set \fBpillar_opts: True\fP in the master configuration file, and then for appropriate minions also set \fBpillar_opts: True\fP in the minion(s) 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 \fBpillar_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 \fBget\fP and \fBitems\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. .sp The pillar top file must include a reference to the new sls pillar file: .sp \fB/srv/pillar/top.sls\fP: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C base: \(aq*\(aq: \- pkg \- edit.vim .ft P .fi .UNINDENT .UNINDENT .SS Setting Pillar Data on the Command Line .sp Pillar data can be set on the command line when running \fBstate.apply T} T{ Glob T} T{ glob_match.py T} _ T{ \-C T} T{ Compound T} T{ compound_match.py T} _ T{ \-E T} T{ Perl\-Compatible Regular Expressions T} T{ pcre_match.py T} _ T{ \-L T} T{ List T} T{ list_match.py T} _ T{ \-G T} T{ Grain T} T{ grain_match.py T} _ T{ \-P T} T{ Grain Perl\-Compatible Regular Expressions T} T{ grain_pcre_match.py T} _ T{ \-N T} T{ Nodegroup T} T{ nodegroup_match.py T} _ T{ \-R T} T{ Range T} T{ range_match.py T} _ T{ \-I T} T{ Pillar T} T{ pillar_match.py T} _ T{ \-J T} T{ Pillar Perl\-Compatible Regular Expressions T} T{ pillar_pcre.py T} _ T{ \-S T} T{ IP\-Classless Internet Domain Routing T} T{ ipcidr_match.py T} _ .TE .SS The Salt Mine .sp The Salt Mine is used to collect arbitrary data from Minions and store it on the Master. This data is then made available to all Minions via the \fBsalt.modules.mine\fP module. .sp Mine data is gathered on the Minion and sent back to the Master where only the most recent data is maintained (if long term data is required use returners or the external job cache). .SS Mine vs Grains .sp Mine data is designed to be much more up\-to\-date than grain data. Grains are refreshed on a very limited basis and are largely static data. Mines are designed to replace slow peer publishing calls when Minions need data from other Minions. Rather than having a Minion reach out to all the other Minions for a piece of data, the Salt Mine, running on the Master, can collect it from all the Minions every \fI\%Mine Interval\fP, resulting in almost fresh data at any given time, with much less overhead. .SS Mine Functions .sp To enable the Salt Mine the \fBmine_functions\fP option needs to be applied to a Minion. This option can be applied via the Minion\(aqs configuration file, or the Minion\(aqs Pillar. The \fBmine_functions\fP option dictates what functions are being executed and allows for arguments to be passed in. The list of functions are available in the \fBsalt.module\fP\&. If no arguments are passed, an empty list must be added like in the \fBtest.ping\fP function in the example below: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C mine_functions: test.ping: [] network.ip_addrs: interface: eth0 cidr: 10.0.0.0/8 .ft P .fi .UNINDENT .UNINDENT .sp In the example above \fBsalt.modules.network.ip_addrs\fP has additional filters to help narrow down the results. In the above example IP addresses are only returned if they are on a eth0 interface and in the 10.0.0.0/8 IP range. .sp Changed in version 3000. .sp The format to define mine_functions has been changed to allow the same format as used for module.run. The old format (above) will still be supported. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C mine_functions: test.ping: [] network.ip_addrs: \- interface: eth0 \- cidr: 10.0.0.0/8 test.arg: \- isn\(aqt \- this \- fun \- this: that \- salt: stack .ft P .fi .UNINDENT .UNINDENT .SS Minion\-side Access Control .sp New in version 3000. .sp Mine functions can be targeted to only be available to specific minions. This uses the same targeting parameters as targeting but with keywords \fBallow_tgt\fP and \fBallow_tgt_type\fP\&. When a minion requests a function from the salt mine that is not allowed to be requested by that minion (i.e. when looking up the combination of \fBallow_tgt\fP and \fBallow_tgt_type\fP and the requesting minion is not in the list) it will get no data, just as if the requested function is not present in the salt mine. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C mine_functions: network.ip_addrs: \- interface: eth0 \- cidr: 10.0.0.0/8 \- allow_tgt: \(aqG@role:master\(aq \- allow_tgt_type: \(aqcompound\(aq .ft P .fi .UNINDENT .UNINDENT .SS Mine Functions Aliases .sp Function aliases can be used to provide friendly names, usage intentions or to allow multiple calls of the same function with different arguments. There is a different syntax for passing positional and key\-value arguments. Mixing positional and key\-value arguments is not supported. .sp New in version 2014.7.0. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C mine_functions: network.ip_addrs: [eth0] networkplus.internal_ip_addrs: [] internal_ip_addrs: mine_function: network.ip_addrs cidr: 192.168.0.0/16 ip_list: \- mine_function: grains.get \- ip_interfaces .ft P .fi .UNINDENT .UNINDENT .sp Changed in version 3000. .sp With the addition of the module.run\-like format for defining mine_functions, the method of adding aliases remains similar. Just add a \fBmine_function\fP kwarg with the name of the real function to call, making the key below \fBmine_functions\fP the alias: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C mine_functions: alias_name: \- mine_function: network.ip_addrs \- eth0 internal_ip_addrs: \- mine_function: network.ip_addrs \- cidr: 192.168.0.0/16 ip_list: \- mine_function: grains.get \- ip_interfaces .ft P .fi .UNINDENT .UNINDENT .SS Mine Interval .sp The Salt Mine functions are executed when the Minion starts and at a given interval by the scheduler. The default interval is every 60 minutes and can be adjusted for the Minion via the \fBmine_interval\fP option in the minion config: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C mine_interval: 60 .ft P .fi .UNINDENT .UNINDENT .SS Mine in Salt\-SSH .sp As of the 2015.5.0 release of salt, salt\-ssh supports \fBmine.get\fP\&. .sp Because the Minions cannot provide their own \fBmine_functions\fP configuration, we retrieve the args for specified mine functions in one of three places, searched in the following order: .INDENT 0.0 .IP 1. 3 Roster data .IP 2. 3 Pillar .IP 3. 3 Master config .UNINDENT .sp The \fBmine_functions\fP are formatted exactly the same as in normal salt, just stored in a different location. Here is an example of a flat roster containing \fBmine_functions\fP: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C test: host: 104.237.131.248 user: root mine_functions: cmd.run: [\(aqecho "hello!"\(aq] network.ip_addrs: interface: eth0 .ft P .fi .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 Because of the differences in the architecture of salt\-ssh, \fBmine.get\fP calls are somewhat inefficient. Salt must make a new salt\-ssh call to each of the Minions in question to retrieve the requested data, much like a publish call. However, unlike publish, it must run the requested function as a wrapper function, so we can retrieve the function args from the pillar of the Minion in question. This results in a non\-trivial delay in retrieving the requested data. .UNINDENT .UNINDENT .SS Minions Targeting with Mine .sp The \fBmine.get\fP function supports various methods of Minions targeting to fetch Mine data from particular hosts, such as glob or regular expression matching on Minion id (name), grains, pillars and compound matches\&. See the \fBsalt.modules.mine\fP module documentation for the reference. .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 Pillar data needs to be cached on Master for pillar targeting to work with Mine. Read the note in relevant section\&. .UNINDENT .UNINDENT .SS Example .sp One way to use data from Salt Mine is in a State. The values can be retrieved via Jinja and used in the SLS file. The following example is a partial HAProxy configuration file and pulls IP addresses from all Minions with the "web" grain to add them to the pool of load balanced servers. .sp \fB/srv/pillar/top.sls\fP: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C base: \(aqG@roles:web\(aq: \- web .ft P .fi .UNINDENT .UNINDENT .sp \fB/srv/pillar/web.sls\fP: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C mine_functions: network.ip_addrs: [eth0] .ft P .fi .UNINDENT .UNINDENT .sp Then trigger the minions to refresh their pillar data by running: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq saltutil.refresh_pillar .ft P .fi .UNINDENT .UNINDENT .sp Verify that the results are showing up in the pillar on the minions by executing the following and checking for \fBnetwork.ip_addrs\fP in the output: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pillar.items .ft P .fi .UNINDENT .UNINDENT .sp Which should show that the function is present on the minion, but not include the output: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C minion1.example.com: \-\-\-\-\-\-\-\-\-\- mine_functions: \-\-\-\-\-\-\-\-\-\- network.ip_addrs: \- eth0 .ft P .fi .UNINDENT .UNINDENT .sp Mine data is typically only updated on the master every 60 minutes, this can be modified by setting: .sp \fB/etc/salt/minion.d/mine.conf\fP: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C mine_interval: 5 .ft P .fi .UNINDENT .UNINDENT .sp To force the mine data to update immediately run: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq mine.update .ft P .fi .UNINDENT .UNINDENT .sp Setup the \fBsalt.states.file.managed\fP state in \fB/srv/salt/haproxy.sls\fP: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C haproxy_config: file.managed: \- name: /etc/haproxy/config \- source: salt://haproxy_config \- template: jinja .ft P .fi .UNINDENT .UNINDENT .sp Create the Jinja template in \fB/srv/salt/haproxy_config\fP: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C <...file contents snipped...> {% for server, addrs in salt[\(aqmine.get\(aq](\(aqroles:web\(aq, \(aqnetwork.ip_addrs\(aq, tgt_type=\(aqgrain\(aq) | dictsort() %} server {{ server }} {{ addrs[0] }}:80 check {% endfor %} <...file contents snipped...> .ft P .fi .UNINDENT .UNINDENT .sp In the above example, \fBserver\fP will be expanded to the \fBminion_id\fP\&. .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 The expr_form argument will be renamed to \fBtgt_type\fP in the 2017.7.0 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("Hello world") ... .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({"message": "A progress message"}, "progress") .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/master/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(): """ Print a list of all of the minions that are up """ client = salt.client.LocalClient(__opts__["conf_file"]) minions = client.cmd("*", "test.version", 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 proto: tcp .ft P .fi .UNINDENT .UNINDENT .sp New in version 3000. .sp Multiple copies of a particular Salt engine can be configured by including the \fBengine_module\fP parameter in the engine configuration. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C engines: \- production_logstash: host: production_log.my_network.com port: 5959 proto: tcp engine_module: logstash \- develop_logstash: host: develop_log.my_network.com port: 5959 proto: tcp engine_module: logstash .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. This option should be formatted as a list of directories to search, such as: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C engines_dirs: \- /home/bob/engines .ft P .fi .UNINDENT .UNINDENT .SS Writing an Engine .sp An example Salt engine, \fI\%https://github.com/saltstack/salt/blob/master/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 What is YAML and How To Use It .sp The default renderer for SLS files is the YAML renderer. .SS What is YAML .sp What does YAML stand for? It\(aqs an acronym for \fIYAML Ain\(aqt Markup Language\fP\&. .sp \fI\%The Official YAML Website\fP defines YAML as: .INDENT 0.0 .INDENT 3.5 \fI\&...a human friendly data serialization\fP \fIstandard for all programming languages.\fP .UNINDENT .UNINDENT .sp 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. .SS Defining YAML .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 {"my_key": "my_value"} .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 {"my_key": "my_value"} .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 {"first_level_dict_key": {"second_level_dict_key": "value_in_second_level_dict"}} .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 {"my_dictionary": ["list_value_one", "list_value_two", "list_value_three"]} .ft P .fi .UNINDENT .UNINDENT .SS Learning more about YAML .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 Here are some excellent links for experimenting with and referencing YAML: .INDENT 0.0 .IP \(bu 2 \fI\%Online YAML Parser\fP: Convert YAML to JSON or Python data structures. .IP \(bu 2 \fI\%The Official YAML Specification\fP .IP \(bu 2 \fI\%The Wikipedia page for YAML\fP .UNINDENT .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 \fBif\fP 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 against 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 .sp Includes must use full paths, like so: .sp spam/eggs.jinja .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C {% include \(aqspam/foobar.jinja\(aq %} .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 Errors .sp Saltstack allows raising custom errors using the \fBraise\fP jinja function. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C {{ raise(\(aqCustom Error\(aq) }} .ft P .fi .UNINDENT .UNINDENT .sp When rendering the template containing the above statement, a \fBTemplateError\fP exception is raised, causing the rendering to fail with the following message: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C TemplateError: Custom Error .ft P .fi .UNINDENT .UNINDENT .SS Filters .sp Saltstack extends \fI\%builtin filters\fP with these custom filters: .SS \fBstrftime\fP .sp Converts any time related object into a time based string. It requires valid strftime directives. An exhaustive list can be found \fI\%here\fP in the Python documentation. .INDENT 0.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 0.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 .SS \fBsequence\fP .sp Ensure that parsed data is a sequence. .SS \fByaml_encode\fP .sp 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 0.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 }} zip: {{ zip|yaml_encode }} zap: {{ 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. .SS \fByaml_dquote\fP .sp 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 0.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. .SS \fByaml_squote\fP .sp 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). .SS \fBto_bool\fP .sp New in version 2017.7.0. .sp Returns the logical value of an element. .sp Example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C {{ \(aqyes\(aq | to_bool }} {{ \(aqtrue\(aq | to_bool }} {{ 1 | to_bool }} {{ \(aqno\(aq | to_bool }} .ft P .fi .UNINDENT .UNINDENT .sp Will be rendered as: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C True True True False .ft P .fi .UNINDENT .UNINDENT .SS \fBexactly_n_true\fP .sp New in version 2017.7.0. .sp Tests that exactly N items in an iterable are "truthy" (neither None, False, nor 0). .sp Example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C {{ [\(aqyes\(aq, 0, False, \(aqTrue\(aq] | exactly_n_true(2) }} .ft P .fi .UNINDENT .UNINDENT .sp Returns: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C True .ft P .fi .UNINDENT .UNINDENT .SS \fBexactly_one_true\fP .sp New in version 2017.7.0. .sp Tests that exactly one item in an iterable is "truthy" (neither None, False, nor 0). .sp Example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C {{ [\(aqyes\(aq, False, 0, None] | exactly_one_true }} .ft P .fi .UNINDENT .UNINDENT .sp Returns: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C True .ft P .fi .UNINDENT .UNINDENT .SS \fBquote\fP .sp New in version 2017.7.0. .sp This text will be wrapped in quotes. .SS \fBregex_search\fP .sp New in version 2017.7.0. .sp Scan through string looking for a location where this regular expression produces a match. Returns \fBNone\fP in case there were no matches found .sp Example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C {{ \(aqabcdefabcdef\(aq | regex_search(\(aqBC(.*)\(aq, ignorecase=True) }} .ft P .fi .UNINDENT .UNINDENT .sp Returns: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C ("defabcdef",) .ft P .fi .UNINDENT .UNINDENT .SS \fBregex_match\fP .sp New in version 2017.7.0. .sp If zero or more characters at the beginning of string match this regular expression, otherwise returns \fBNone\fP\&. .sp Example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C {{ \(aqabcdefabcdef\(aq | regex_match(\(aqBC(.*)\(aq, ignorecase=True) }} .ft P .fi .UNINDENT .UNINDENT .sp Returns: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C None .ft P .fi .UNINDENT .UNINDENT .SS \fBregex_replace\fP .sp New in version 2017.7.0. .sp Searches for a pattern and replaces with a sequence of characters. .sp Example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C {% set my_text = \(aqyes, this is a TEST\(aq %} {{ my_text | regex_replace(\(aq ([a\-z])\(aq, \(aq__\e\e1\(aq, ignorecase=True) }} .ft P .fi .UNINDENT .UNINDENT .sp Returns: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C yes,__this__is__a__TEST .ft P .fi .UNINDENT .UNINDENT .SS \fBuuid\fP .sp New in version 2017.7.0. .sp Return a UUID. .sp Example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C {{ \(aqrandom\(aq | uuid }} .ft P .fi .UNINDENT .UNINDENT .sp Returns: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C 3652b285\-26ad\-588e\-a5dc\-c2ee65edc804 .ft P .fi .UNINDENT .UNINDENT .SS \fBis_list\fP .sp New in version 2017.7.0. .sp Return if an object is list. .sp Example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C {{ [1, 2, 3] | is_list }} .ft P .fi .UNINDENT .UNINDENT .sp Returns: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C True .ft P .fi .UNINDENT .UNINDENT .SS \fBis_iter\fP .sp New in version 2017.7.0. .sp Return if an object is iterable. .sp Example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C {{ [1, 2, 3] | is_iter }} .ft P .fi .UNINDENT .UNINDENT .sp Returns: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C True .ft P .fi .UNINDENT .UNINDENT .SS \fBmin\fP .sp New in version 2017.7.0. .sp Return the minimum value from a list. .sp Example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C {{ [1, 2, 3] | min }} .ft P .fi .UNINDENT .UNINDENT .sp Returns: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C 1 .ft P .fi .UNINDENT .UNINDENT .SS \fBmax\fP .sp New in version 2017.7.0. .sp Returns the maximum value from a list. .sp Example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C {{ [1, 2, 3] | max }} .ft P .fi .UNINDENT .UNINDENT .sp Returns: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C 3 .ft P .fi .UNINDENT .UNINDENT .SS \fBavg\fP .sp New in version 2017.7.0. .sp Returns the average value of the elements of a list .sp Example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C {{ [1, 2, 3] | avg }} .ft P .fi .UNINDENT .UNINDENT .sp Returns: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C 2 .ft P .fi .UNINDENT .UNINDENT .SS \fBunion\fP .sp New in version 2017.7.0. .sp Return the union of two lists. .sp Example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C {{ [1, 2, 3] | union([2, 3, 4]) | join(\(aq, \(aq) }} .ft P .fi .UNINDENT .UNINDENT .sp Returns: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C 1, 2, 3, 4 .ft P .fi .UNINDENT .UNINDENT .SS \fBintersect\fP .sp New in version 2017.7.0. .sp Return the intersection of two lists. .sp Example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C {{ [1, 2, 3] | intersect([2, 3, 4]) | join(\(aq, \(aq) }} .ft P .fi .UNINDENT .UNINDENT .sp Returns: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C 2, 3 .ft P .fi .UNINDENT .UNINDENT .SS \fBdifference\fP .sp New in version 2017.7.0. .sp Return the difference of two lists. .sp Example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C {{ [1, 2, 3] | difference([2, 3, 4]) | join(\(aq, \(aq) }} .ft P .fi .UNINDENT .UNINDENT .sp Returns: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C 1 .ft P .fi .UNINDENT .UNINDENT .SS \fBsymmetric_difference\fP .sp New in version 2017.7.0. .sp Return the symmetric difference of two lists. .sp Example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C {{ [1, 2, 3] | symmetric_difference([2, 3, 4]) | join(\(aq, \(aq) }} .ft P .fi .UNINDENT .UNINDENT .sp Returns: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C 1, 4 .ft P .fi .UNINDENT .UNINDENT .SS \fBmethod_call\fP .sp New in version 3001. .sp Returns a result of object\(aqs method call. .sp Example #1: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C {{ [1, 2, 1, 3, 4] | method_call(\(aqindex\(aq, 1, 1, 3) }} .ft P .fi .UNINDENT .UNINDENT .sp Returns: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C 2 .ft P .fi .UNINDENT .UNINDENT .sp This filter can be used with the \fI\%map filter\fP to apply object methods without using loop constructs or temporary variables. .sp Example #2: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C {% set host_list = [\(aqweb01.example.com\(aq, \(aqdb01.example.com\(aq] %} {% set host_list_split = [] %} {% for item in host_list %} {% do host_list_split.append(item.split(\(aq.\(aq, 1)) %} {% endfor %} {{ host_list_split }} .ft P .fi .UNINDENT .UNINDENT .sp Example #3: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C {{ host_list|map(\(aqmethod_call\(aq, \(aqsplit\(aq, \(aq.\(aq, 1)|list }} .ft P .fi .UNINDENT .UNINDENT .sp Return of examples #2 and #3: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C [[web01, example.com], [db01, example.com]] .ft P .fi .UNINDENT .UNINDENT .SS \fBis_sorted\fP .sp New in version 2017.7.0. .sp Return \fBTrue\fP if an iterable object is already sorted. .sp Example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C {{ [1, 2, 3] | is_sorted }} .ft P .fi .UNINDENT .UNINDENT .sp Returns: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C True .ft P .fi .UNINDENT .UNINDENT .SS \fBcompare_lists\fP .sp New in version 2017.7.0. .sp Compare two lists and return a dictionary with the changes. .sp Example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C {{ [1, 2, 3] | compare_lists([1, 2, 4]) }} .ft P .fi .UNINDENT .UNINDENT .sp Returns: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C {"new": [4], "old": [3]} .ft P .fi .UNINDENT .UNINDENT .SS \fBcompare_dicts\fP .sp New in version 2017.7.0. .sp Compare two dictionaries and return a dictionary with the changes. .sp Example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C {{ {\(aqa\(aq: \(aqb\(aq} | compare_dicts({\(aqa\(aq: \(aqc\(aq}) }} .ft P .fi .UNINDENT .UNINDENT .sp Returns: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C {"a": {"new": "c", "old": "b"}} .ft P .fi .UNINDENT .UNINDENT .SS \fBis_hex\fP .sp New in version 2017.7.0. .sp Return \fBTrue\fP if the value is hexadecimal. .sp Example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C {{ \(aq0xabcd\(aq | is_hex }} {{ \(aqxyzt\(aq | is_hex }} .ft P .fi .UNINDENT .UNINDENT .sp Returns: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C True False .ft P .fi .UNINDENT .UNINDENT .SS \fBcontains_whitespace\fP .sp New in version 2017.7.0. .sp Return \fBTrue\fP if a text contains whitespaces. .sp Example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C {{ \(aqabcd\(aq | contains_whitespace }} {{ \(aqab cd\(aq | contains_whitespace }} .ft P .fi .UNINDENT .UNINDENT .sp Returns: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C False True .ft P .fi .UNINDENT .UNINDENT .SS \fBsubstring_in_list\fP .sp New in version 2017.7.0. .sp Return \fBTrue\fP if a substring is found in a list of string values. .sp Example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C {{ \(aqabcd\(aq | substring_in_list([\(aqthis\(aq, \(aqis\(aq, \(aqan abcd example\(aq]) }} .ft P .fi .UNINDENT .UNINDENT .sp Returns: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C True .ft P .fi .UNINDENT .UNINDENT .SS \fBcheck_whitelist_blacklist\fP .sp New in version 2017.7.0. .sp Check a whitelist and/or blacklist to see if the value matches it. .sp This filter can be used with either a whitelist or a blacklist individually, or a whitelist and a blacklist can be passed simultaneously. .sp If whitelist is used alone, value membership is checked against the whitelist only. If the value is found, the function returns \fBTrue\fP\&. Otherwise, it returns \fBFalse\fP\&. .sp If blacklist is used alone, value membership is checked against the blacklist only. If the value is found, the function returns \fBFalse\fP\&. Otherwise, it returns \fBTrue\fP\&. .sp If both a whitelist and a blacklist are provided, value membership in the blacklist will be examined first. If the value is not found in the blacklist, then the whitelist is checked. If the value isn\(aqt found in the whitelist, the function returns \fBFalse\fP\&. .sp Whitelist Example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C {{ 5 | check_whitelist_blacklist(whitelist=[5, 6, 7]) }} .ft P .fi .UNINDENT .UNINDENT .sp Returns: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C True .ft P .fi .UNINDENT .UNINDENT .sp Blacklist Example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C {{ 5 | check_whitelist_blacklist(blacklist=[5, 6, 7]) }} .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C False .ft P .fi .UNINDENT .UNINDENT .SS \fBdate_format\fP .sp New in version 2017.7.0. .sp Converts unix timestamp into human\-readable string. .sp Example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C {{ 1457456400 | date_format }} {{ 1457456400 | date_format(\(aq%d.%m.%Y %H:%M\(aq) }} .ft P .fi .UNINDENT .UNINDENT .sp Returns: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C 2017\-03\-08 08.03.2017 17:00 .ft P .fi .UNINDENT .UNINDENT .SS \fBto_num\fP .sp New in version 2017.7.0. .sp New in version 2018.3.0: Renamed from \fBstr_to_num\fP to \fBto_num\fP\&. .sp Converts a string to its numerical value. .sp Example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C {{ \(aq5\(aq | to_num }} .ft P .fi .UNINDENT .UNINDENT .sp Returns: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C 5 .ft P .fi .UNINDENT .UNINDENT .SS \fBto_bytes\fP .sp New in version 2017.7.0. .sp Converts string\-type object to bytes. .sp Example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C {{ \(aqwall of text\(aq | to_bytes }} .ft P .fi .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 This option may have adverse effects when using the default renderer, \fBjinja|yaml\fP\&. This is due to the fact that YAML requires proper handling in regard to special characters. Please see the section on YAML ASCII support in the YAML Idiosyncracies documentation for more information. .UNINDENT .UNINDENT .SS \fBjson_encode_list\fP .sp New in version 2017.7.0. .sp New in version 2018.3.0: Renamed from \fBjson_decode_list\fP to \fBjson_encode_list\fP\&. When you encode something you get bytes, and when you decode, you get your locale\(aqs encoding (usually a \fBunicode\fP type). This filter was incorrectly\-named when it was added. \fBjson_decode_list\fP will be supported until the Aluminium release. .sp Deprecated since version 2018.3.3,2019.2.0: The \fI\%tojson\fP filter accomplishes what this filter was designed to do, making this filter redundant. .sp Recursively encodes all string elements of the list to bytes. .sp Example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C {{ [1, 2, 3] | json_encode_list }} .ft P .fi .UNINDENT .UNINDENT .sp Returns: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C [1, 2, 3] .ft P .fi .UNINDENT .UNINDENT .SS \fBjson_encode_dict\fP .sp New in version 2017.7.0. .sp New in version 2018.3.0: Renamed from \fBjson_decode_dict\fP to \fBjson_encode_dict\fP\&. When you encode something you get bytes, and when you decode, you get your locale\(aqs encoding (usually a \fBunicode\fP type). This filter was incorrectly\-named when it was added. \fBjson_decode_dict\fP will be supported until the Aluminium release. .sp Deprecated since version 2018.3.3,2019.2.0: The \fI\%tojson\fP filter accomplishes what this filter was designed to do, making this filter redundant. .sp Recursively encodes all string items in the dictionary to bytes. .sp Example: .sp Assuming that \fBpillar[\(aqfoo\(aq]\fP contains \fB{u\(aqa\(aq: u\(aq\eu0414\(aq}\fP, and your locale is \fBen_US.UTF\-8\fP: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C {{ pillar[\(aqfoo\(aq] | json_encode_dict }} .ft P .fi .UNINDENT .UNINDENT .sp Returns: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C {"a": "\exd0\ex94"} .ft P .fi .UNINDENT .UNINDENT .SS \fBtojson\fP .sp New in version 2018.3.3,2019.2.0. .sp Dumps a data structure to JSON. .sp This filter was added to provide this functionality to hosts which have a Jinja release older than version 2.9 installed. If Jinja 2.9 or newer is installed, then the upstream version of the filter will be used. See the \fI\%upstream docs\fP for more information. .SS \fBrandom_hash\fP .sp New in version 2017.7.0. .sp New in version 2018.3.0: Renamed from \fBrand_str\fP to \fBrandom_hash\fP to more accurately describe what the filter does. \fBrand_str\fP will be supported to ensure backwards compatibility but please use the preferred \fBrandom_hash\fP\&. .sp Generates a random number between 1 and the number passed to the filter, and then hashes it. The default hash type is the one specified by the minion\(aqs \fBhash_type\fP config option, but an alternate hash type can be passed to the filter as an argument. .sp Example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C {% set num_range = 99999999 %} {{ num_range | random_hash }} {{ num_range | random_hash(\(aqsha512\(aq) }} .ft P .fi .UNINDENT .UNINDENT .sp Returns: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C 43ec517d68b6edd3015b3edc9a11367b d94a45acd81f8e3107d237dbc0d5d195f6a52a0d188bc0284c0763ece1eac9f9496fb6a531a296074c87b3540398dace1222b42e150e67c9301383fde3d66ae5 .ft P .fi .UNINDENT .UNINDENT .SS \fBset_dict_key_value\fP .sp New in version 3000. .sp Allows you to set a value in a nested dictionary without having to worry if all the nested keys actually exist. Missing keys will be automatically created if they do not exist. The default delimiter for the keys is \(aq:\(aq, however, with the \fIdelimiter\fP\-parameter, a different delimiter can be specified. .sp Examples: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .TP .B Example 1: {%\- set foo = {} %} {{ foo | set_dict_key_value(\(aqbar:baz\(aq, 42) }} .TP .B Example 2: {{ {} | set_dict_key_value(\(aqbar.baz.qux\(aq, 42, delimiter=\(aq.\(aq) }} .UNINDENT .sp Returns: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .TP .B Example 1: {\(aqbar\(aq: {\(aqbaz\(aq: 42}} .TP .B Example 2: {\(aqbar\(aq: {\(aqbaz\(aq: {\(aqqux\(aq: 42}}} .UNINDENT .SS \fBappend_dict_key_value\fP .sp New in version 3000. .sp Allows you to append to a list nested (deep) in a dictionary without having to worry if all the nested keys (or the list itself) actually exist. Missing keys will automatically be created if they do not exist. The default delimiter for the keys is \(aq:\(aq, however, with the \fIdelimiter\fP\-parameter, a different delimiter can be specified. .sp Examples: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .TP .B Example 1: {%\- set foo = {\(aqbar\(aq: {\(aqbaz\(aq: [1, 2]}} %} {{ foo | append_dict_key_value(\(aqbar:baz\(aq, 42) }} .TP .B Example 2: {%\- set foo = {} %} {{ foo | append_dict_key_value(\(aqbar:baz:qux\(aq, 42) }} .UNINDENT .sp Returns: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .TP .B Example 1: {\(aqbar\(aq: {\(aqbaz\(aq: [1, 2, 42]}} .TP .B Example 2: {\(aqbar\(aq: {\(aqbaz\(aq: {\(aqqux\(aq: [42]}}} .UNINDENT .SS \fBextend_dict_key_value\fP .sp New in version 3000. .sp Allows you to extend a list nested (deep) in a dictionary without having to worry if all the nested keys (or the list itself) actually exist. Missing keys will automatically be created if they do not exist. The default delimiter for the keys is \(aq:\(aq, however, with the \fIdelimiter\fP\-parameter, a different delimiter can be specified. .sp Examples: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .TP .B Example 1: {%\- set foo = {\(aqbar\(aq: {\(aqbaz\(aq: [1, 2]}} %} {{ foo | extend_dict_key_value(\(aqbar:baz\(aq, [42, 42]) }} .TP .B Example 2: {{ {} | extend_dict_key_value(\(aqbar:baz:qux\(aq, [42]) }} .UNINDENT .sp Returns: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .TP .B Example 1: {\(aqbar\(aq: {\(aqbaz\(aq: [1, 2, 42, 42]}} .TP .B Example 2: {\(aqbar\(aq: {\(aqbaz\(aq: {\(aqqux\(aq: [42]}}} .UNINDENT .SS \fBupdate_dict_key_value\fP .sp New in version 3000. .sp Allows you to update a dictionary nested (deep) in another dictionary without having to worry if all the nested keys actually exist. Missing keys will automatically be created if they do not exist. The default delimiter for the keys is \(aq:\(aq, however, with the \fIdelimiter\fP\-parameter, a different delimiter can be specified. .sp Examples: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .TP .B Example 1: {%\- set foo = {\(aqbar\(aq: {\(aqbaz\(aq: {\(aqqux\(aq: 1}}} %} {{ foo | update_dict_key_value(\(aqbar:baz\(aq, {\(aqquux\(aq: 3}) }} .TP .B Example 2: {{ {} | update_dict_key_value(\(aqbar:baz:qux\(aq, {\(aqquux\(aq: 3}) }} .UNINDENT .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .TP .B Example 1: {\(aqbar\(aq: {\(aqbaz\(aq: {\(aqqux\(aq: 1, \(aqquux\(aq: 3}}} .TP .B Example 2: {\(aqbar\(aq: {\(aqbaz\(aq: {\(aqqux\(aq: {\(aqquux\(aq: 3}}}} .UNINDENT .SS \fBmd5\fP .sp New in version 2017.7.0. .sp Return the md5 digest of a string. .sp Example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C {{ \(aqrandom\(aq | md5 }} .ft P .fi .UNINDENT .UNINDENT .sp Returns: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C 7ddf32e17a6ac5ce04a8ecbf782ca509 .ft P .fi .UNINDENT .UNINDENT .SS \fBsha256\fP .sp New in version 2017.7.0. .sp Return the sha256 digest of a string. .sp Example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C {{ \(aqrandom\(aq | sha256 }} .ft P .fi .UNINDENT .UNINDENT .sp Returns: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C a441b15fe9a3cf56661190a0b93b9dec7d04127288cc87250967cf3b52894d11 .ft P .fi .UNINDENT .UNINDENT .SS \fBsha512\fP .sp New in version 2017.7.0. .sp Return the sha512 digest of a string. .sp Example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C {{ \(aqrandom\(aq | sha512 }} .ft P .fi .UNINDENT .UNINDENT .sp Returns: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C 811a90e1c8e86c7b4c0eef5b2c0bf0ec1b19c4b1b5a242e6455be93787cb473cb7bc9b0fdeb960d00d5c6881c2094dd63c5c900ce9057255e2a4e271fc25fef1 .ft P .fi .UNINDENT .UNINDENT .SS \fBbase64_encode\fP .sp New in version 2017.7.0. .sp Encode a string as base64. .sp Example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C {{ \(aqrandom\(aq | base64_encode }} .ft P .fi .UNINDENT .UNINDENT .sp Returns: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C cmFuZG9t .ft P .fi .UNINDENT .UNINDENT .SS \fBbase64_decode\fP .sp New in version 2017.7.0. .sp Decode a base64\-encoded string. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C {{ \(aqZ2V0IHNhbHRlZA==\(aq | base64_decode }} .ft P .fi .UNINDENT .UNINDENT .sp Returns: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C get salted .ft P .fi .UNINDENT .UNINDENT .SS \fBhmac\fP .sp New in version 2017.7.0. .sp Verify a challenging hmac signature against a string / shared\-secret. Returns a boolean value. .sp Example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C {{ \(aqget salted\(aq | hmac(\(aqshared secret\(aq, \(aqeBWf9bstXg+NiP5AOwppB5HMvZiYMPzEM9W5YMm/AmQ=\(aq) }} .ft P .fi .UNINDENT .UNINDENT .sp Returns: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C True .ft P .fi .UNINDENT .UNINDENT .SS \fBhttp_query\fP .sp New in version 2017.7.0. .sp Return the HTTP reply object from a URL. .sp Example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C {{ \(aqhttp://jsonplaceholder.typicode.com/posts/1\(aq | http_query }} .ft P .fi .UNINDENT .UNINDENT .sp Returns: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C { \(aqbody\(aq: \(aq{ "userId": 1, "id": 1, "title": "sunt aut facere repellat provident occaecati excepturi option reprehenderit", "body": "quia et suscipit\e\ensuscipit recusandae consequuntur expedita et cum\e\enreprehenderit molestiae ut ut quas totam\e\ennostrum rerum est autem sunt rem eveniet architecto" }\(aq } .ft P .fi .UNINDENT .UNINDENT .SS \fBtraverse\fP .sp New in version 2018.3.3. .sp Traverse a dict or list using a colon\-delimited target string. The target \(aqfoo:bar:0\(aq will return data[\(aqfoo\(aq][\(aqbar\(aq][0] if this value exists, and will otherwise return the provided default value. .sp Example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C {{ {\(aqa1\(aq: {\(aqb1\(aq: {\(aqc1\(aq: \(aqfoo\(aq}}, \(aqa2\(aq: \(aqbar\(aq} | traverse(\(aqa1:b1\(aq, \(aqdefault\(aq) }} .ft P .fi .UNINDENT .UNINDENT .sp Returns: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C {"c1": "foo"} .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C {{ {\(aqa1\(aq: {\(aqb1\(aq: {\(aqc1\(aq: \(aqfoo\(aq}}, \(aqa2\(aq: \(aqbar\(aq} | traverse(\(aqa2:b2\(aq, \(aqdefault\(aq) }} .ft P .fi .UNINDENT .UNINDENT .sp Returns: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C "default" .ft P .fi .UNINDENT .UNINDENT .SS \fBjson_query\fP .sp New in version 3000. .sp A port of Ansible \fBjson_query\fP Jinja filter to make queries against JSON data using \fI\%JMESPath language\fP\&. Could be used to filter \fBpillar\fP data, \fByaml\fP maps, and together with \fI\%http_query\fP\&. Depends on the \fI\%jmespath\fP Python module. .sp Examples: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C Example 1: {{ [1, 2, 3, 4, [5, 6]] | json_query(\(aq[]\(aq) }} Example 2: {{ {"machines": [ {"name": "a", "state": "running"}, {"name": "b", "state": "stopped"}, {"name": "c", "state": "running"} ]} | json_query("machines[?state==\(aqrunning\(aq].name") }} Example 3: {{ {"services": [ {"name": "http", "host": "1.2.3.4", "port": 80}, {"name": "smtp", "host": "1.2.3.5", "port": 25}, {"name": "ssh", "host": "1.2.3.6", "port": 22}, ]} | json_query("services[].port") }} .ft P .fi .UNINDENT .UNINDENT .sp Returns: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C Example 1: [1, 2, 3, 4, 5, 6] Example 2: [\(aqa\(aq, \(aqc\(aq] Example 3: [80, 25, 22] .ft P .fi .UNINDENT .UNINDENT .SS \fBto_snake_case\fP .sp New in version 3000. .sp Converts a string from camelCase (or CamelCase) to snake_case. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C Example: {{ camelsWillLoveThis | to_snake_case }} .ft P .fi .UNINDENT .UNINDENT .sp Returns: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C Example: camels_will_love_this .ft P .fi .UNINDENT .UNINDENT .SS \fBto_camelcase\fP .sp New in version 3000. .sp Converts a string from snake_case to camelCase (or UpperCamelCase if so indicated). .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C Example 1: {{ snake_case_for_the_win | to_camelcase }} Example 2: {{ snake_case_for_the_win | to_camelcase(uppercamel=True) }} .ft P .fi .UNINDENT .UNINDENT .sp Returns: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C Example 1: snakeCaseForTheWin Example 2: SnakeCaseForTheWin .ft P .fi .UNINDENT .UNINDENT .SS Networking Filters .sp The following networking\-related filters are supported: .SS \fBis_ip\fP .sp New in version 2017.7.0. .sp Return if a string is a valid IP Address. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C {{ \(aq192.168.0.1\(aq | is_ip }} .ft P .fi .UNINDENT .UNINDENT .sp Additionally accepts the following options: .INDENT 0.0 .IP \(bu 2 global .IP \(bu 2 link\-local .IP \(bu 2 loopback .IP \(bu 2 multicast .IP \(bu 2 private .IP \(bu 2 public .IP \(bu 2 reserved .IP \(bu 2 site\-local .IP \(bu 2 unspecified .UNINDENT .sp Example \- test if a string is a valid loopback IP address. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C {{ \(aq192.168.0.1\(aq | is_ip(options=\(aqloopback\(aq) }} .ft P .fi .UNINDENT .UNINDENT .SS \fBis_ipv4\fP .sp New in version 2017.7.0. .sp Returns if a string is a valid IPv4 address. Supports the same options as \fBis_ip\fP\&. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C {{ \(aq192.168.0.1\(aq | is_ipv4 }} .ft P .fi .UNINDENT .UNINDENT .SS \fBis_ipv6\fP .sp New in version 2017.7.0. .sp Returns if a string is a valid IPv6 address. Supports the same options as \fBis_ip\fP\&. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C {{ \(aqfe80::\(aq | is_ipv6 }} .ft P .fi .UNINDENT .UNINDENT .SS \fBipaddr\fP .sp New in version 2017.7.0. .sp From a list, returns only valid IP entries. Supports the same options as \fBis_ip\fP\&. The list can contains also IP interfaces/networks. .sp Example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C {{ [\(aq192.168.0.1\(aq, \(aqfoo\(aq, \(aqbar\(aq, \(aqfe80::\(aq] | ipaddr }} .ft P .fi .UNINDENT .UNINDENT .sp Returns: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C ["192.168.0.1", "fe80::"] .ft P .fi .UNINDENT .UNINDENT .SS \fBipv4\fP .sp New in version 2017.7.0. .sp From a list, returns only valid IPv4 entries. Supports the same options as \fBis_ip\fP\&. The list can contains also IP interfaces/networks. .sp Example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C {{ [\(aq192.168.0.1\(aq, \(aqfoo\(aq, \(aqbar\(aq, \(aqfe80::\(aq] | ipv4 }} .ft P .fi .UNINDENT .UNINDENT .sp Returns: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C ["192.168.0.1"] .ft P .fi .UNINDENT .UNINDENT .SS \fBipv6\fP .sp New in version 2017.7.0. .sp From a list, returns only valid IPv6 entries. Supports the same options as \fBis_ip\fP\&. The list can contains also IP interfaces/networks. .sp Example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C {{ [\(aq192.168.0.1\(aq, \(aqfoo\(aq, \(aqbar\(aq, \(aqfe80::\(aq] | ipv6 }} .ft P .fi .UNINDENT .UNINDENT .sp Returns: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C ["fe80::"] .ft P .fi .UNINDENT .UNINDENT .SS \fBnetwork_hosts\fP .sp New in version 2017.7.0. .sp Return the list of hosts within a networks. This utility works for both IPv4 and IPv6. .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 When running this command with a large IPv6 network, the command will take a long time to gather all of the hosts. .UNINDENT .UNINDENT .sp Example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C {{ \(aq192.168.0.1/30\(aq | network_hosts }} .ft P .fi .UNINDENT .UNINDENT .sp Returns: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C ["192.168.0.1", "192.168.0.2"] .ft P .fi .UNINDENT .UNINDENT .SS \fBnetwork_size\fP .sp New in version 2017.7.0. .sp Return the size of the network. This utility works for both IPv4 and IPv6. .sp Example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C {{ \(aq192.168.0.1/8\(aq | network_size }} .ft P .fi .UNINDENT .UNINDENT .sp Returns: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C 16777216 .ft P .fi .UNINDENT .UNINDENT .SS \fBgen_mac\fP .sp New in version 2017.7.0. .sp Generates a MAC address with the defined OUI prefix. .sp Common prefixes: .INDENT 0.0 .IP \(bu 2 \fB00:16:3E\fP \-\- Xen .IP \(bu 2 \fB00:18:51\fP \-\- OpenVZ .IP \(bu 2 \fB00:50:56\fP \-\- VMware (manually generated) .IP \(bu 2 \fB52:54:00\fP \-\- QEMU/KVM .IP \(bu 2 \fBAC:DE:48\fP \-\- PRIVATE .UNINDENT .sp Example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C {{ \(aq00:50\(aq | gen_mac }} .ft P .fi .UNINDENT .UNINDENT .sp Returns: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C 00:50:71:52:1C .ft P .fi .UNINDENT .UNINDENT .SS \fBmac_str_to_bytes\fP .sp New in version 2017.7.0. .sp Converts a string representing a valid MAC address to bytes. .sp Example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C {{ \(aq00:11:22:33:44:55\(aq | mac_str_to_bytes }} .ft P .fi .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 This option may have adverse effects when using the default renderer, \fBjinja|yaml\fP\&. This is due to the fact that YAML requires proper handling in regard to special characters. Please see the section on YAML ASCII support in the YAML Idiosyncracies documentation for more information. .UNINDENT .UNINDENT .SS \fBdns_check\fP .sp New in version 2017.7.0. .sp Return the ip resolved by dns, but do not exit on failure, only raise an exception. Obeys system preference for IPv4/6 address resolution. .sp Example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C {{ \(aqwww.google.com\(aq | dns_check(port=443) }} .ft P .fi .UNINDENT .UNINDENT .sp Returns: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C \(aq172.217.3.196\(aq .ft P .fi .UNINDENT .UNINDENT .SS File filters .SS \fBis_text_file\fP .sp New in version 2017.7.0. .sp Return if a file is text. .sp Uses heuristics to guess whether the given file is text or binary, by reading a single block of bytes from the file. If more than 30% of the chars in the block are non\-text, or there are NUL (\(aqx00\(aq) bytes in the block, assume this is a binary file. .sp Example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C {{ \(aq/etc/salt/master\(aq | is_text_file }} .ft P .fi .UNINDENT .UNINDENT .sp Returns: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C True .ft P .fi .UNINDENT .UNINDENT .SS \fBis_binary_file\fP .sp New in version 2017.7.0. .sp Return if a file is binary. .sp Detects if the file is a binary, returns bool. Returns True if the file is a bin, False if the file is not and None if the file is not available. .sp Example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C {{ \(aq/etc/salt/master\(aq | is_binary_file }} .ft P .fi .UNINDENT .UNINDENT .sp Returns: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C False .ft P .fi .UNINDENT .UNINDENT .SS \fBis_empty_file\fP .sp New in version 2017.7.0. .sp Return if a file is empty. .sp Example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C {{ \(aq/etc/salt/master\(aq | is_empty_file }} .ft P .fi .UNINDENT .UNINDENT .sp Returns: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C False .ft P .fi .UNINDENT .UNINDENT .SS \fBfile_hashsum\fP .sp New in version 2017.7.0. .sp Return the hashsum of a file. .sp Example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C {{ \(aq/etc/salt/master\(aq | file_hashsum }} .ft P .fi .UNINDENT .UNINDENT .sp Returns: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C 02d4ef135514934759634f10079653252c7ad594ea97bd385480c532bca0fdda .ft P .fi .UNINDENT .UNINDENT .SS \fBlist_files\fP .sp New in version 2017.7.0. .sp Return a recursive list of files under a specific path. .sp Example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C {{ \(aq/etc/salt/\(aq | list_files | join(\(aq\en\(aq) }} .ft P .fi .UNINDENT .UNINDENT .sp Returns: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C /etc/salt/master /etc/salt/proxy /etc/salt/minion /etc/salt/pillar/top.sls /etc/salt/pillar/device1.sls .ft P .fi .UNINDENT .UNINDENT .SS \fBpath_join\fP .sp New in version 2017.7.0. .sp Joins absolute paths. .sp Example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C {{ \(aq/etc/salt/\(aq | path_join(\(aqpillar\(aq, \(aqdevice1.sls\(aq) }} .ft P .fi .UNINDENT .UNINDENT .sp Returns: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C /etc/salt/pillar/device1.sls .ft P .fi .UNINDENT .UNINDENT .SS \fBwhich\fP .sp New in version 2017.7.0. .sp Python clone of /usr/bin/which. .sp Example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C {{ \(aqsalt\-master\(aq | which }} .ft P .fi .UNINDENT .UNINDENT .sp Returns: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C /usr/local/salt/virtualenv/bin/salt\-master .ft P .fi .UNINDENT .UNINDENT .SS Tests .sp Saltstack extends \fI\%builtin tests\fP with these custom tests: .SS \fBequalto\fP .sp Tests the equality between two values. .sp Can be used in an \fBif\fP statement directly: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C {% if 1 is equalto(1) %} < statements > {% endif %} .ft P .fi .UNINDENT .UNINDENT .sp If clause evaluates to \fBTrue\fP .sp or with the \fBselectattr\fP filter: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C {{ [{\(aqvalue\(aq: 1}, {\(aqvalue\(aq: 2} , {\(aqvalue\(aq: 3}] | selectattr(\(aqvalue\(aq, \(aqequalto\(aq, 3) | list }} .ft P .fi .UNINDENT .UNINDENT .sp Returns: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C [{"value": 3}] .ft P .fi .UNINDENT .UNINDENT .SS \fBmatch\fP .sp Tests that a string matches the regex passed as an argument. .sp Can be used in a \fBif\fP statement directly: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C {% if \(aqa\(aq is match(\(aq[a\-b]\(aq) %} < statements > {% endif %} .ft P .fi .UNINDENT .UNINDENT .sp If clause evaluates to \fBTrue\fP .sp or with the \fBselectattr\fP filter: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C {{ [{\(aqvalue\(aq: \(aqa\(aq}, {\(aqvalue\(aq: \(aqb\(aq}, {\(aqvalue\(aq: \(aqc\(aq}] | selectattr(\(aqvalue\(aq, \(aqmatch\(aq, \(aq[b\-e]\(aq) | list }} .ft P .fi .UNINDENT .UNINDENT .sp Returns: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C [{"value": "b"}, {"value": "c"}] .ft P .fi .UNINDENT .UNINDENT .sp Test supports additional optional arguments: \fBignorecase\fP, \fBmultiline\fP .SS Escape filters .SS \fBregex_escape\fP .sp New in version 2017.7.0. .sp Allows escaping of strings so they can be interpreted literally by another function. .sp Example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C regex_escape = {{ \(aqhttps://example.com?foo=bar%20baz\(aq | regex_escape }} .ft P .fi .UNINDENT .UNINDENT .sp will be rendered as: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C regex_escape = https\e:\e/\e/example\e.com\e?foo\e=bar\e%20baz .ft P .fi .UNINDENT .UNINDENT .SS Set Theory Filters .SS \fBunique\fP .sp New in version 2017.7.0. .sp Performs set math using Jinja filters. .sp Example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C unique = {{ [\(aqfoo\(aq, \(aqfoo\(aq, \(aqbar\(aq] | unique }} .ft P .fi .UNINDENT .UNINDENT .sp will be rendered as: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C unique = [\(aqfoo\(aq, \(aqbar\(aq] .ft P .fi .UNINDENT .UNINDENT .SS Jinja in Files .sp \fI\%Jinja\fP 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 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()|yaml(False) }} .ft P .fi .UNINDENT .UNINDENT .SS Logs .sp New in version 2017.7.0. .sp Yes, in Salt, one is able to debug a complex Jinja template using the logs. For example, making the call: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C {%\- do salt.log.error(\(aqtesting jinja logging\(aq) \-%} .ft P .fi .UNINDENT .UNINDENT .sp Will insert the following message in the minion logs: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C 2017\-02\-01 01:24:40,728 [salt.module.logmod][ERROR ][3779] testing jinja logging .ft P .fi .UNINDENT .UNINDENT .SS Profiling .sp New in version 3002. .sp When working with a very large codebase, it becomes increasingly imperative to trace inefficiencies with state and pillar render times. The \fIprofile\fP jinja block enables the user to get finely detailed information on the most expensive areas in the codebase. .SS Profiling blocks .sp Any block of jinja code can be wrapped in a \fBprofile\fP block. The syntax for a profile block is \fB{% profile as \(aq\(aq %}{% endprofile %}\fP, where \fB\fP can be any string. The \fB\fP token will appear in the log at the \fBprofile\fP level along with the render time of the block. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C # /srv/salt/example.sls {%\- profile as \(aqlocal data\(aq %} {%\- set local_data = {\(aqcounter\(aq: 0} %} {%\- for i in range(313377) %} {%\- do local_data.update({\(aqcounter\(aq: i}) %} {%\- endfor %} {%\- endprofile %} test: cmd.run: \- name: |\- printf \(aqdata: %s\(aq \(aq{{ local_data[\(aqcounter\(aq] }}\(aq .ft P .fi .UNINDENT .UNINDENT .sp The \fBprofile\fP block in the \fBexample.sls\fP state will emit the following log statement: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C # salt\-call \-\-local \-l profile state.apply example [...] [PROFILE ] Time (in seconds) to render profile block \(aqlocal data\(aq: 0.9385035037994385 [...] .ft P .fi .UNINDENT .UNINDENT .SS Profiling imports .sp Using the same logic as the \fBprofile\fP block, the \fBimport_yaml\fP, \fBimport_json\fP, and \fBimport_text\fP blocks will emit similar statements at the \fBprofile\fP log level. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C # /srv/salt/data.sls {%\- set values = {\(aqcounter\(aq: 0} %} {%\- for i in range(524288) %} {%\- do values.update({\(aqcounter\(aq: i}) %} {%\- endfor %} data: {{ values[\(aqcounter\(aq] }} .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C # /srv/salt/example.sls {%\- import_yaml \(aqdata.sls\(aq as imported %} test: cmd.run: \- name: |\- printf \(aqdata: %s\(aq \(aq{{ imported[\(aqdata\(aq] }}\(aq .ft P .fi .UNINDENT .UNINDENT .sp For \fBimport_*\fP blocks, the \fBprofile\fP log statement has the following form: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C # salt\-call \-\-local \-l profile state.apply example [...] [PROFILE ] Time (in seconds) to render import_yaml \(aqdata.sls\(aq: 1.5500736236572266 [...] .ft P .fi .UNINDENT .UNINDENT .SS Python Methods .sp A powerful feature of jinja that is only hinted at in the official jinja documentation is that you can use the native python methods of the variable type. Here is the python documentation for \fI\%string methods\fP\&. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C {% set hostname,domain = grains.id.partition(\(aq.\(aq)[::2] %}{{ hostname }} .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C {% set strings = grains.id.split(\(aq\-\(aq) %}{{ strings[0] }} .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 Custom Jinja filters .sp Given that all execution modules are available in the Jinja template, one can easily define a custom module as in the previous paragraph and use it as a Jinja filter. However, please note that it will not be accessible through the pipe. .sp For example, instead of: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C {{ my_variable | my_jinja_filter }} .ft P .fi .UNINDENT .UNINDENT .sp The user will need to define \fBmy_jinja_filter\fP function under an extension module, say \fBmy_filters\fP and use as: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C {{ salt.my_filters.my_jinja_filter(my_variable) }} .ft P .fi .UNINDENT .UNINDENT .sp The greatest benefit is that you are able to access thousands of existing functions, e.g.: .INDENT 0.0 .IP \(bu 2 get the DNS AAAA records for a specific address using the \fBdnsutil\fP: .INDENT 2.0 .INDENT 3.5 .sp .nf .ft C {{ salt.dnsutil.AAAA(\(aqwww.google.com\(aq) }} .ft P .fi .UNINDENT .UNINDENT .IP \(bu 2 retrieve a specific field value from a \fBRedis\fP hash: .INDENT 2.0 .INDENT 3.5 .sp .nf .ft C {{ salt.redis.hget(\(aqfoo_hash\(aq, \(aqbar_field\(aq) }} .ft P .fi .UNINDENT .UNINDENT .IP \(bu 2 get the routes to \fB0.0.0.0/0\fP using the \fBNAPALM route\fP: .INDENT 2.0 .INDENT 3.5 .sp .nf .ft C {{ salt.route.show(\(aq0.0.0.0/0\(aq) }} .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS Tutorials Index .SS Autoaccept minions from Grains .sp New in version 2018.3.0. .sp To automatically accept minions based on certain characteristics, e.g. the \fBuuid\fP you can specify certain grain values on the salt master. Minions with matching grains will have their keys automatically accepted. .INDENT 0.0 .IP 1. 3 Configure the autosign_grains_dir in the master config file: .UNINDENT .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C autosign_grains_dir: /etc/salt/autosign_grains .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .IP 2. 3 Configure the grain values to be accepted .UNINDENT .sp Place a file named like the grain in the autosign_grains_dir and write the values that should be accepted automatically inside that file. For example to automatically accept minions based on their \fBuuid\fP create a file named \fB/etc/salt/autosign_grains/uuid\fP: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C 8f7d68e2\-30c5\-40c6\-b84a\-df7e978a03ee 1d3c5473\-1fbc\-479e\-b0c7\-877705a0730f .ft P .fi .UNINDENT .UNINDENT .sp The master is now setup to accept minions with either of the two specified uuids. Multiple values must always be written into separate lines. Lines starting with a \fB#\fP are ignored. .INDENT 0.0 .IP 3. 3 Configure the minion to send the specific grains to the master in the minion config file: .UNINDENT .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C autosign_grains: \- uuid .ft P .fi .UNINDENT .UNINDENT .sp Now 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 Salt as a Cloud Controller .sp In Salt 0.14.0, an advanced cloud control system was introduced, allowing 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 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, and 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://opensuse.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\%https://wiki.centos.org/Cloud/OpenNebula\fP .SS Fedora Linux .sp Images for Fedora Linux can be found here: \fI\%https://alt.fedoraproject.org/cloud\fP .SS openSUSE .sp \fI\%https://download.opensuse.org/distribution/leap/15.1/jeos/openSUSE\-Leap\-15.1\-JeOS.x86_64\-15.1.0\-kvm\-and\-xen\-Current.qcow2.meta4\fP .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 using the \fIvirt runner\fP\&. .sp Start by running a Salt Virt hypervisor info command: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt\-run virt.host_info .ft P .fi .UNINDENT .UNINDENT .sp This will query the running hypervisor(s) for stats and display useful information such as the number of CPUs and amount of memory. .sp You can also list all VMs and their current states on all hypervisor nodes: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt\-run virt.list .ft P .fi .UNINDENT .UNINDENT .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 The Salt Virt runner will now automatically select a hypervisor to deploy the new virtual machine on. Using \fBsalt://\fP assumes that the CentOS virtual machine image is located in the root of the file\-server on the master. When images are cloned (i.e. copied locally after retrieval from the file server), the destination directory on the hypervisor minion is determined by the \fBvirt:images\fP config option; by default this is \fB/srv/salt\-images/\fP\&. .sp When a VM is initialized using \fBvirt.init\fP, the image is copied to the hypervisor using \fBcp.cache_file\fP and will be mounted and seeded with a minion. Seeding includes setting pre\-authenticated keys on the new machine. A minion will only be installed if one can not be found on the image using the default arguments to \fBseed.apply\fP\&. .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 You can also deploy an image on a particular minion by directly calling the \fBvirt\fP execution module with an absolute image path. This can be quite handy for testing: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt \(aqhypervisor*\(aq virt.init centos1 2 512 image=/var/lib/libvirt/images/centos.img .ft P .fi .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 QEMU Copy on Write Support .sp For fast image cloning, you can use the \fI\%qcow\fP disk image format. Pass the \fBenable_qcow\fP flag and a \fI\&.qcow2\fP image path to \fIvirt.init\fP: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt \(aqhypervisor*\(aq virt.init centos1 2 512 image=/var/lib/libvirt/images/centos.qcow2 enable_qcow=True start=False .ft P .fi .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 Beware that attempting to boot a qcow image too quickly after cloning can result in a race condition where libvirt may try to boot the machine before image seeding has completed. For that reason, it is recommended to also pass \fBstart=False\fP to \fBvirt.init\fP\&. .sp Also know that you \fBmust not\fP modify the original base image without first making a copy and then \fIrebasing\fP all overlay images onto it. See the \fBqemu\-img rebase\fP \fI\%usage docs\fP\&. .UNINDENT .UNINDENT .SS Migrating Virtual Machines .sp Salt Virt comes with full support for virtual machine migration. 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 be found in: .sp Opening the Firewall up for Salt .UNINDENT .UNINDENT .sp Salt also needs the \fBvirt:tunnel\fP option 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. .sp To turn on \fBvirt:tunnel\fP, simply 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 Although not enabled by default, Salt Virt can also set up VNC consoles allowing for remote visual consoles to be opened up. When creating a new VM using \fBvirt.init\fP, pass the \fBenable_vnc=True\fP parameter to have a console configured for the new VM. .sp The information from a \fBvirt.query\fP routine will display the VNC console port for the specific VMs: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C centos CPU: 2 Memory: 524288 State: running Graphics: vnc \- hyper6:5900 Disk \- vda: Size: 2.0G File: /srv/salt\-images/ubuntu2/system.qcow2 File Format: qcow2 Nic \- ac:de:48:98:08:77: Source: br0 Type: bridge .ft P .fi .UNINDENT .UNINDENT .sp The line \fIGraphics: vnc \- hyper6:5900\fP holds the key. First the port named, in this case 5900, will need to be available in the hypervisor\(aqs firewall. Once the port is open, then the console can be easily opened via vncviewer: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C vncviewer hyper6:5900 .ft P .fi .UNINDENT .UNINDENT .sp By default there is no VNC security set up on these ports, which suggests that keeping them firewalled and mandating that SSH tunnels be used to access these VNC interfaces. Keep in mind that activity on a VNC interface that is accessed can be viewed by any other user that accesses that same VNC interface, and any other user logging in can also operate with the logged in user on the virtual machine. .SS Conclusion .sp Now with Salt Virt running, new hypervisors can be seamlessly added just by running the above states on new bare metal machines, and these machines will be instantly available to Salt Virt. .SS Running Salt States and Commands in Docker Containers .sp The 2016.11.0 release of Salt introduces the ability to execute Salt States and Salt remote execution commands directly inside of Docker containers. .sp This addition makes it possible to not only deploy fresh containers using Salt States. This also allows for running containers to be audited and modified using Salt, but without running a Salt Minion inside the container. Some of the applications include security audits of running containers as well as gathering operating data from containers. .sp This new feature is simple and straightforward, and can be used via a running Salt Minion, the Salt Call command, or via Salt SSH. For this tutorial we will use the \fIsalt\-call\fP command, but like all salt commands these calls are directly translatable to \fIsalt\fP and \fIsalt\-ssh\fP\&. .SS Step 1 \- Install Docker .sp Since setting up Docker is well covered in the Docker documentation we will make no such effort to describe it here. Please see the Docker Installation Documentation for installing and setting up Docker: \fI\%https://docs.docker.com/engine/installation/\fP .sp The Docker integration also requires that the \fIdocker\-py\fP library is installed. This can easily be done using pip or via your system package manager: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C pip install docker\-py .ft P .fi .UNINDENT .UNINDENT .SS Step 2 \- Install Salt .sp For this tutorial we will be using Salt Call, which is available in the \fIsalt\-minion\fP package, please follow the Salt Installation docs found here: \fI\%https://repo.saltstack.com/\fP .SS Step 3 \- Create With Salt States .sp Next some Salt States are needed, for this example a very basic state which installs \fIvim\fP is used, but anything Salt States can do can be done here, please see the Salt States Introduction Tutorial to learn more about Salt States: \fI\%https://docs.saltstack.com/en/stage/getstarted/config/\fP .sp For this tutorial, simply create a small state file in \fI/srv/salt/vim.sls\fP: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C vim: pkg.installed .ft P .fi .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 The base image you choose will need to have python 2.6 or 2.7 installed. We are hoping to resolve this constraint in a future release. .sp If \fIbase\fP is omitted the default image used is a minimal openSUSE image with Python support, maintained by SUSE .UNINDENT .UNINDENT .sp Next run the \fIdocker.sls_build\fP command: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt\-call \-\-local dockerng.sls_build test base=my_base_image mods=vim .ft P .fi .UNINDENT .UNINDENT .sp Now we have a fresh image called \fItest\fP to work with and vim has been installed. .SS Step 4 \- Running Commands Inside the Container .sp Salt can now run remote execution functions inside the container with another simple \fIsalt\-call\fP command: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt\-call \-\-local dockerng.call test test.version salt\-call \-\-local dockerng.call test network.interfaces salt\-call \-\-local dockerng.call test disk.usage salt\-call \-\-local dockerng.call test pkg.list_pkgs salt\-call \-\-local dockerng.call test service.running httpd salt\-call \-\-local dockerng.call test cmd.run \(aqls \-l /etc\(aq .ft P .fi .UNINDENT .UNINDENT .SS Automatic Updates / Frozen Deployments .sp New in version 0.10.3.d. .sp Salt has support for the \fI\%Esky\fP application freezing and update tool. This tool allows one to build a complete zipfile out of the salt scripts and all their dependencies \- including shared objects / DLLs. .SS Getting Started .sp To build frozen applications, suitable build environment will be needed for each platform. You should probably set up a virtualenv in order to limit the scope of Q/A. .sp This process does work on Windows. Directions are available at \fI\%https://github.com/saltstack/salt\-windows\-install\fP for details on installing Salt in Windows. Only the 32\-bit Python and dependencies have been tested, but they have been tested on 64\-bit Windows. .sp Install \fBbbfreeze\fP, and then \fBesky\fP from PyPI in order to enable the \fBbdist_esky\fP command in \fBsetup.py\fP\&. Salt itself must also be installed, in addition to its dependencies. .SS Building and Freezing .sp Once you have your tools installed and the environment configured, use \fBsetup.py\fP to prepare the distribution files. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C python setup.py sdist python setup.py bdist .ft P .fi .UNINDENT .UNINDENT .sp Once the distribution files are in place, Esky can be used traverse the module tree and pack all the scripts up into a redistributable. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C python setup.py bdist_esky .ft P .fi .UNINDENT .UNINDENT .sp There will be an appropriately versioned \fBsalt\-VERSION.zip\fP in \fBdist/\fP if everything went smoothly. .SS Windows .sp \fBC:\ePython27\elib\esite\-packages\ezmq\fP will need to be added to the PATH variable. This helps bbfreeze find the zmq DLL so it can pack it up. .SS Using the Frozen Build .sp Unpack the zip file in the desired install location. Scripts like \fBsalt\-minion\fP and \fBsalt\-call\fP will be in the root of the zip file. The associated libraries and bootstrapping will be in the directories at the same level. (Check the \fI\%Esky\fP documentation for more information) .sp To support updating your minions in the wild, put the builds on a web server that the minions can reach. \fBsalt.modules.saltutil.update()\fP will trigger an update and (optionally) a restart of the minion service under the new version. .SS Troubleshooting .SS A Windows minion isn\(aqt responding .sp The process dispatch on Windows is slower than it is on *nix. It may be necessary to add \(aq\-t 15\(aq to salt commands to give minions plenty of time to return. .SS Windows and the Visual Studio Redist .sp The Visual C++ 2008 32\-bit redistributable will need to be installed on all Windows minions. Esky has an option to pack the library into the zipfile, but OpenSSL does not seem to acknowledge the new location. If a \fBno OPENSSL_Applink\fP error appears on the console when trying to start a frozen minion, the redistributable is not installed. .SS Mixed Linux environments and Yum .sp The Yum Python module doesn\(aqt appear to be available on any of the standard Python package mirrors. If RHEL/CentOS systems need to be supported, the frozen build should created on that platform to support all the Linux nodes. Remember to build the virtualenv with \fB\-\-system\-site\-packages\fP so that the \fByum\fP module is included. .SS Automatic (Python) module discovery .sp Automatic (Python) module discovery does not work with the late\-loaded scheme that Salt uses for (Salt) modules. Any misbehaving modules will need to be explicitly added to the \fBfreezer_includes\fP in Salt\(aqs \fBsetup.py\fP\&. Always check the zipped application to make sure that the necessary modules were included. .SS 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 its 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 Minion 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 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.version\fP to respond with salt\(aqs version installed (Example: \fB2018.3.4\fP\&. 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.version 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.version\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 .SS Installing and Configuring Halite .sp \fBWARNING:\fP .INDENT 0.0 .INDENT 3.5 Halite is deprecated .sp The Halite project is retired. The code will remain available on GitHub. .UNINDENT .UNINDENT .sp In this tutorial, we\(aqll walk through installing and setting up Halite. The current version of Halite is considered pre\-alpha and is supported only in Salt \fBv2014.1.0\fP or greater. Additional information is available on GitHub: \fI\%https://github.com/saltstack/halite\fP .sp Before beginning this tutorial, ensure that the salt\-master is installed. To install the salt\-master, please review the installation documentation: \fI\%http://docs.saltstack.com/topics/installation/index.html\fP .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 Halite only works with Salt versions greater than 2014.1.0. .UNINDENT .UNINDENT .SS Installing Halite Via Package .sp On CentOS, RHEL, or Fedora: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C $ yum install python\-halite .ft P .fi .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 By default python\-halite only installs CherryPy. If you would like to use a different webserver please review the instructions below to install pip and your server of choice. The package does not modify the master configuration with \fB/etc/salt/master\fP\&. .UNINDENT .UNINDENT .SS Installing Halite Using pip .sp To begin the installation of Halite from PyPI, you\(aqll need to install pip. The Salt package, as well as the bootstrap, do not install pip by default. .sp On CentOS, RHEL, or Fedora: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C $ yum install python\-pip .ft P .fi .UNINDENT .UNINDENT .sp On Debian: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C $ apt\-get install python\-pip .ft P .fi .UNINDENT .UNINDENT .sp Once you have pip installed, use it to install halite: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C $ pip install \-U halite .ft P .fi .UNINDENT .UNINDENT .sp Depending on the webserver you want to run halite through, you\(aqll need to install that piece as well. On RHEL based distros, use one of the following: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C $ pip install cherrypy .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C $ pip install paste .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C $ yum install python\-devel $ yum install gcc $ pip install gevent $ pip install pyopenssl .ft P .fi .UNINDENT .UNINDENT .sp On Debian based distributions: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C $ pip install CherryPy .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C $ pip install paste .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C $ apt\-get install gcc $ apt\-get install python\-dev $ apt\-get install libevent\-dev $ pip install gevent $ pip install pyopenssl .ft P .fi .UNINDENT .UNINDENT .SS Configuring Halite Permissions .sp Configuring Halite access permissions is easy. By default, you only need to ensure that the @runner group is configured. In the \fB/etc/salt/master\fP file, uncomment and modify the following lines: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C external_auth: pam: testuser: \- .* \- \(aq@runner\(aq .ft P .fi .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 You cannot use the root user for pam login; it will fail to authenticate. .UNINDENT .UNINDENT .sp Halite uses the runner manage.present to get the status of minions, so runner permissions are required. For example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C external_auth: pam: mytestuser: \- .* \- \(aq@runner\(aq \- \(aq@wheel\(aq .ft P .fi .UNINDENT .UNINDENT .sp Currently Halite allows, but does not require, any wheel modules. .SS Configuring Halite Settings .sp Once you\(aqve configured the permissions for Halite, you\(aqll need to set up the Halite settings in the /etc/salt/master file. Halite supports CherryPy, Paste, and Gevent out of the box. .sp To configure cherrypy, add the following to the bottom of your /etc/salt/master file: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C halite: level: \(aqdebug\(aq server: \(aqcherrypy\(aq host: \(aq0.0.0.0\(aq port: \(aq8080\(aq cors: False tls: True certpath: \(aq/etc/pki/tls/certs/localhost.crt\(aq keypath: \(aq/etc/pki/tls/certs/localhost.key\(aq pempath: \(aq/etc/pki/tls/certs/localhost.pem\(aq .ft P .fi .UNINDENT .UNINDENT .sp If you wish to use paste: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C halite: level: \(aqdebug\(aq server: \(aqpaste\(aq host: \(aq0.0.0.0\(aq port: \(aq8080\(aq cors: False tls: True certpath: \(aq/etc/pki/tls/certs/localhost.crt\(aq keypath: \(aq/etc/pki/tls/certs/localhost.key\(aq pempath: \(aq/etc/pki/tls/certs/localhost.pem\(aq .ft P .fi .UNINDENT .UNINDENT .sp To use gevent: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C halite: level: \(aqdebug\(aq server: \(aqgevent\(aq host: \(aq0.0.0.0\(aq port: \(aq8080\(aq cors: False tls: True certpath: \(aq/etc/pki/tls/certs/localhost.crt\(aq keypath: \(aq/etc/pki/tls/certs/localhost.key\(aq pempath: \(aq/etc/pki/tls/certs/localhost.pem\(aq .ft P .fi .UNINDENT .UNINDENT .sp The "cherrypy" and "gevent" servers require the certpath and keypath files to run tls/ssl. The .crt file holds the public cert and the .key file holds the private key. Whereas the "paste" server requires a single .pem file that contains both the cert and key. This can be created simply by concatenating the .crt and .key files. .sp If you want to use a self\-signed cert, you can create one using the Salt.tls module: .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 The following command needs to be run on your salt master. .UNINDENT .UNINDENT .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt\-call tls.create_self_signed_cert tls .ft P .fi .UNINDENT .UNINDENT .sp Note that certs generated by the above command can be found under the \fB/etc/pki/tls/certs/\fP directory. When using self\-signed certs, browsers will need approval before accepting the cert. If the web application page has been cached with a non\-HTTPS version of the app, then the browser cache will have to be cleared before it will recognize and prompt to accept the self\-signed certificate. .SS Starting Halite .sp Once you\(aqve configured the halite section of your /etc/salt/master, you can restart the salt\-master service, and your halite instance will be available. Depending on your configuration, the instance will be available either at \fI\%https://localhost:8080/app\fP, \fI\%https://domain:8080/app\fP, or \fI\%https://123.456.789.012:8080/app\fP . .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 halite requires an HTML 5 compliant browser. .UNINDENT .UNINDENT .sp All logs relating to halite are logged to the default /var/log/salt/master file. .SS HTTP Modules .sp This tutorial demonstrates using the various HTTP modules available in Salt. These modules wrap the Python \fBtornado\fP, \fBurllib2\fP, and \fBrequests\fP libraries, extending them in a manner that is more consistent with Salt workflows. .SS The \fBsalt.utils.http\fP Library .sp This library forms the core of the HTTP modules. Since it is designed to be used from the minion as an execution module, in addition to the master as a runner, it was abstracted into this multi\-use library. This library can also be imported by 3rd\-party programs wishing to take advantage of its extended functionality. .sp Core functionality of the execution, state, and runner modules is derived from this library, so common usages between them are described here. Documentation specific to each module is described below. .sp This library can be imported with: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C import salt.utils.http .ft P .fi .UNINDENT .UNINDENT .SS Configuring Libraries .sp This library can make use of either \fBtornado\fP, which is required by Salt, \fBurllib2\fP, which ships with Python, or \fBrequests\fP, which can be installed separately. By default, \fBtornado\fP will be used. In order to switch to \fBurllib2\fP, set the following variable: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C backend: urllib2 .ft P .fi .UNINDENT .UNINDENT .sp In order to switch to \fBrequests\fP, set the following variable: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C backend: requests .ft P .fi .UNINDENT .UNINDENT .sp This can be set in the master or minion configuration file, or passed as an option directly to any \fBhttp.query()\fP functions. .SS \fBsalt.utils.http.query()\fP .sp This function forms a basic query, but with some add\-ons not present in the \fBtornado\fP, \fBurllib2\fP, and \fBrequests\fP libraries. Not all functionality currently available in these libraries has been added, but can be in future iterations. .SS HTTPS Request Methods .sp A basic query can be performed by calling this function with no more than a single URL: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt.utils.http.query("http://example.com") .ft P .fi .UNINDENT .UNINDENT .sp By default the query will be performed with a \fBGET\fP method. The method can be overridden with the \fBmethod\fP argument: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt.utils.http.query("http://example.com/delete/url", "DELETE") .ft P .fi .UNINDENT .UNINDENT .sp When using the \fBPOST\fP method (and others, such as \fBPUT\fP), extra data is usually sent as well. This data can be sent directly (would be URL encoded when necessary), or in whatever format is required by the remote server (XML, JSON, plain text, etc). .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt.utils.http.query( "http://example.com/post/url", method="POST", data=json.dumps(mydict) ) .ft P .fi .UNINDENT .UNINDENT .SS Data Formatting and Templating .sp Bear in mind that the data must be sent pre\-formatted; this function will not format it for you. However, a templated file stored on the local system may be passed through, along with variables to populate it with. To pass through only the file (untemplated): .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt.utils.http.query( "http://example.com/post/url", method="POST", data_file="/srv/salt/somefile.xml" ) .ft P .fi .UNINDENT .UNINDENT .sp To pass through a file that contains jinja + yaml templating (the default): .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt.utils.http.query( "http://example.com/post/url", method="POST", data_file="/srv/salt/somefile.jinja", data_render=True, template_dict={"key1": "value1", "key2": "value2"}, ) .ft P .fi .UNINDENT .UNINDENT .sp To pass through a file that contains mako templating: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt.utils.http.query( "http://example.com/post/url", method="POST", data_file="/srv/salt/somefile.mako", data_render=True, data_renderer="mako", template_dict={"key1": "value1", "key2": "value2"}, ) .ft P .fi .UNINDENT .UNINDENT .sp Because this function uses Salt\(aqs own rendering system, any Salt renderer can be used. Because Salt\(aqs renderer requires \fB__opts__\fP to be set, an \fBopts\fP dictionary should be passed in. If it is not, then the default \fB__opts__\fP values for the node type (master or minion) will be used. Because this library is intended primarily for use by minions, the default node type is \fBminion\fP\&. However, this can be changed to \fBmaster\fP if necessary. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt.utils.http.query( "http://example.com/post/url", method="POST", data_file="/srv/salt/somefile.jinja", data_render=True, template_dict={"key1": "value1", "key2": "value2"}, opts=__opts__, ) salt.utils.http.query( "http://example.com/post/url", method="POST", data_file="/srv/salt/somefile.jinja", data_render=True, template_dict={"key1": "value1", "key2": "value2"}, node="master", ) .ft P .fi .UNINDENT .UNINDENT .SS Headers .sp Headers may also be passed through, either as a \fBheader_list\fP, a \fBheader_dict\fP, or as a \fBheader_file\fP\&. As with the \fBdata_file\fP, the \fBheader_file\fP may also be templated. Take note that because HTTP headers are normally syntactically\-correct YAML, they will automatically be imported as an a Python dict. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt.utils.http.query( "http://example.com/delete/url", method="POST", header_file="/srv/salt/headers.jinja", header_render=True, header_renderer="jinja", template_dict={"key1": "value1", "key2": "value2"}, ) .ft P .fi .UNINDENT .UNINDENT .sp Because much of the data that would be templated between headers and data may be the same, the \fBtemplate_dict\fP is the same for both. Correcting possible variable name collisions is up to the user. .SS Authentication .sp The \fBquery()\fP function supports basic HTTP authentication. A username and password may be passed in as \fBusername\fP and \fBpassword\fP, respectively. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt.utils.http.query( "http://example.com", username="larry", password="5700g3543v4r", ) .ft P .fi .UNINDENT .UNINDENT .SS Cookies and Sessions .sp Cookies are also supported, using Python\(aqs built\-in \fBcookielib\fP\&. However, they are turned off by default. To turn cookies on, set \fBcookies\fP to True. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt.utils.http.query("http://example.com", cookies=True) .ft P .fi .UNINDENT .UNINDENT .sp By default cookies are stored in Salt\(aqs cache directory, normally \fB/var/cache/salt\fP, as a file called \fBcookies.txt\fP\&. However, this location may be changed with the \fBcookie_jar\fP argument: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt.utils.http.query( "http://example.com", cookies=True, cookie_jar="/path/to/cookie_jar.txt" ) .ft P .fi .UNINDENT .UNINDENT .sp By default, the format of the cookie jar is LWP (aka, lib\-www\-perl). This default was chosen because it is a human\-readable text file. If desired, the format of the cookie jar can be set to Mozilla: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt.utils.http.query( "http://example.com", cookies=True, cookie_jar="/path/to/cookie_jar.txt", cookie_format="mozilla", ) .ft P .fi .UNINDENT .UNINDENT .sp Because Salt commands are normally one\-off commands that are piped together, this library cannot normally behave as a normal browser, with session cookies that persist across multiple HTTP requests. However, the session can be persisted in a separate cookie jar. The default filename for this file, inside Salt\(aqs cache directory, is \fBcookies.session.p\fP\&. This can also be changed. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt.utils.http.query( "http://example.com", persist_session=True, session_cookie_jar="/path/to/jar.p" ) .ft P .fi .UNINDENT .UNINDENT .sp The format of this file is msgpack, which is consistent with much of the rest of Salt\(aqs internal structure. Historically, the extension for this file is \fB\&.p\fP\&. There are no current plans to make this configurable. .SS Proxy .sp If the \fBtornado\fP backend is used (\fBtornado\fP is the default), proxy information configured in \fBproxy_host\fP, \fBproxy_port\fP, \fBproxy_username\fP, \fBproxy_password\fP and \fBno_proxy\fP from the \fB__opts__\fP dictionary will be used. Normally these are set in the minion configuration file. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C proxy_host: proxy.my\-domain proxy_port: 31337 proxy_username: charon proxy_password: obolus no_proxy: [\(aq127.0.0.1\(aq, \(aqlocalhost\(aq] .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt.utils.http.query("http://example.com", opts=__opts__, backend="tornado") .ft P .fi .UNINDENT .UNINDENT .SS Return Data .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 Return data encoding .sp If \fBdecode\fP is set to \fBTrue\fP, \fBquery()\fP will attempt to decode the return data. \fBdecode_type\fP defaults to \fBauto\fP\&. Set it to a specific encoding, \fBxml\fP, for example, to override autodetection. .UNINDENT .UNINDENT .sp Because Salt\(aqs http library was designed to be used with REST interfaces, \fBquery()\fP will attempt to decode the data received from the remote server when \fBdecode\fP is set to \fBTrue\fP\&. First it will check the \fBContent\-type\fP header to try and find references to XML. If it does not find any, it will look for references to JSON. If it does not find any, it will fall back to plain text, which will not be decoded. .sp JSON data is translated into a dict using Python\(aqs built\-in \fBjson\fP library. XML is translated using \fBsalt.utils.xml_util\fP, which will use Python\(aqs built\-in XML libraries to attempt to convert the XML into a dict. In order to force either JSON or XML decoding, the \fBdecode_type\fP may be set: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt.utils.http.query("http://example.com", decode_type="xml") .ft P .fi .UNINDENT .UNINDENT .sp Once translated, the return dict from \fBquery()\fP will include a dict called \fBdict\fP\&. .sp If the data is not to be translated using one of these methods, decoding may be turned off. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt.utils.http.query("http://example.com", decode=False) .ft P .fi .UNINDENT .UNINDENT .sp If decoding is turned on, and references to JSON or XML cannot be found, then this module will default to plain text, and return the undecoded data as \fBtext\fP (even if text is set to \fBFalse\fP; see below). .sp The \fBquery()\fP function can return the HTTP status code, headers, and/or text as required. However, each must individually be turned on. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt.utils.http.query("http://example.com", status=True, headers=True, text=True) .ft P .fi .UNINDENT .UNINDENT .sp The return from these will be found in the return dict as \fBstatus\fP, \fBheaders\fP and \fBtext\fP, respectively. .SS Writing Return Data to Files .sp It is possible to write either the return data or headers to files, as soon as the response is received from the server, but specifying file locations via the \fBtext_out\fP or \fBheaders_out\fP arguments. \fBtext\fP and \fBheaders\fP do not need to be returned to the user in order to do this. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt.utils.http.query( "http://example.com", text=False, headers=False, text_out="/path/to/url_download.txt", headers_out="/path/to/headers_download.txt", ) .ft P .fi .UNINDENT .UNINDENT .SS SSL Verification .sp By default, this function will verify SSL certificates. However, for testing or debugging purposes, SSL verification can be turned off. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt.utils.http.query( "https://example.com", verify_ssl=False, ) .ft P .fi .UNINDENT .UNINDENT .SS CA Bundles .sp The \fBrequests\fP library has its own method of detecting which CA (certificate authority) bundle file to use. Usually this is implemented by the packager for the specific operating system distribution that you are using. However, \fBurllib2\fP requires a little more work under the hood. By default, Salt will try to auto\-detect the location of this file. However, if it is not in an expected location, or a different path needs to be specified, it may be done so using the \fBca_bundle\fP variable. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt.utils.http.query( "https://example.com", ca_bundle="/path/to/ca_bundle.pem", ) .ft P .fi .UNINDENT .UNINDENT .SS Updating CA Bundles .sp The \fBupdate_ca_bundle()\fP function can be used to update the bundle file at a specified location. If the target location is not specified, then it will attempt to auto\-detect the location of the bundle file. If the URL to download the bundle from does not exist, a bundle will be downloaded from the cURL website. .sp CAUTION: The \fBtarget\fP and the \fBsource\fP should always be specified! Failure to specify the \fBtarget\fP may result in the file being written to the wrong location on the local system. Failure to specify the \fBsource\fP may cause the upstream URL to receive excess unnecessary traffic, and may cause a file to be download which is hazardous or does not meet the needs of the user. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt.utils.http.update_ca_bundle( target="/path/to/ca\-bundle.crt", source="https://example.com/path/to/ca\-bundle.crt", opts=__opts__, ) .ft P .fi .UNINDENT .UNINDENT .sp The \fBopts\fP parameter should also always be specified. If it is, then the \fBtarget\fP and the \fBsource\fP may be specified in the relevant configuration file (master or minion) as \fBca_bundle\fP and \fBca_bundle_url\fP, respectively. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C ca_bundle: /path/to/ca\-bundle.crt ca_bundle_url: https://example.com/path/to/ca\-bundle.crt .ft P .fi .UNINDENT .UNINDENT .sp If Salt is unable to auto\-detect the location of the CA bundle, it will raise an error. .sp The \fBupdate_ca_bundle()\fP function can also be passed a string or a list of strings which represent files on the local system, which should be appended (in the specified order) to the end of the CA bundle file. This is useful in environments where private certs need to be made available, and are not otherwise reasonable to add to the bundle file. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt.utils.http.update_ca_bundle( opts=__opts__, merge_files=[ "/etc/ssl/private_cert_1.pem", "/etc/ssl/private_cert_2.pem", "/etc/ssl/private_cert_3.pem", ], ) .ft P .fi .UNINDENT .UNINDENT .SS Test Mode .sp This function may be run in test mode. This mode will perform all work up until the actual HTTP request. By default, instead of performing the request, an empty dict will be returned. Using this function with \fBTRACE\fP logging turned on will reveal the contents of the headers and POST data to be sent. .sp Rather than returning an empty dict, an alternate \fBtest_url\fP may be passed in. If this is detected, then test mode will replace the \fBurl\fP with the \fBtest_url\fP, set \fBtest\fP to \fBTrue\fP in the return data, and perform the rest of the requested operations as usual. This allows a custom, non\-destructive URL to be used for testing when necessary. .SS Execution Module .sp The \fBhttp\fP execution module is a very thin wrapper around the \fBsalt.utils.http\fP library. The \fBopts\fP can be passed through as well, but if they are not specified, the minion defaults will be used as necessary. .sp Because passing complete data structures from the command line can be tricky at best and dangerous (in terms of execution injection attacks) at worse, the \fBdata_file\fP, and \fBheader_file\fP are likely to see more use here. .sp All methods for the library are available in the execution module, as kwargs. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt myminion http.query http://example.com/restapi method=POST \e username=\(aqlarry\(aq password=\(aq5700g3543v4r\(aq headers=True text=True \e status=True decode_type=xml data_render=True \e header_file=/tmp/headers.txt data_file=/tmp/data.txt \e header_render=True cookies=True persist_session=True .ft P .fi .UNINDENT .UNINDENT .SS Runner Module .sp Like the execution module, the \fBhttp\fP runner module is a very thin wrapper around the \fBsalt.utils.http\fP library. The only significant difference is that because runners execute on the master instead of a minion, a target is not required, and default opts will be derived from the master config, rather than the minion config. .sp All methods for the library are available in the runner module, as kwargs. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt\-run http.query http://example.com/restapi method=POST \e username=\(aqlarry\(aq password=\(aq5700g3543v4r\(aq headers=True text=True \e status=True decode_type=xml data_render=True \e header_file=/tmp/headers.txt data_file=/tmp/data.txt \e header_render=True cookies=True persist_session=True .ft P .fi .UNINDENT .UNINDENT .SS State Module .sp The state module is a wrapper around the runner module, which applies stateful logic to a query. All kwargs as listed above are specified as usual in state files, but two more kwargs are available to apply stateful logic. A required parameter is \fBmatch\fP, which specifies a pattern to look for in the return text. By default, this will perform a string comparison of looking for the value of match in the return text. In Python terms this looks like: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C def myfunc(): if match in html_text: return True .ft P .fi .UNINDENT .UNINDENT .sp If more complex pattern matching is required, a regular expression can be used by specifying a \fBmatch_type\fP\&. By default this is set to \fBstring\fP, but it can be manually set to \fBpcre\fP instead. Please note that despite the name, this will use Python\(aqs \fBre.search()\fP rather than \fBre.match()\fP\&. .sp Therefore, the following states are valid: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C http://example.com/restapi: http.query: \- match: \(aqSUCCESS\(aq \- username: \(aqlarry\(aq \- password: \(aq5700g3543v4r\(aq \- data_render: True \- header_file: /tmp/headers.txt \- data_file: /tmp/data.txt \- header_render: True \- cookies: True \- persist_session: True http://example.com/restapi: http.query: \- match_type: pcre \- match: \(aq(?i)succe[ss|ed]\(aq \- username: \(aqlarry\(aq \- password: \(aq5700g3543v4r\(aq \- data_render: True \- header_file: /tmp/headers.txt \- data_file: /tmp/data.txt \- header_render: True \- cookies: True \- persist_session: True .ft P .fi .UNINDENT .UNINDENT .sp In addition to, or instead of a match pattern, the status code for a URL can be checked. This is done using the \fBstatus\fP argument: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C http://example.com/: http.query: \- status: 200 .ft P .fi .UNINDENT .UNINDENT .sp If both are specified, both will be checked, but if only one is \fBTrue\fP and the other is \fBFalse\fP, then \fBFalse\fP will be returned. In this case, the comments in the return data will contain information for troubleshooting. .sp Because this is a monitoring state, it will return extra data to code that expects it. This data will always include \fBtext\fP and \fBstatus\fP\&. Optionally, \fBheaders\fP and \fBdict\fP may also be requested by setting the \fBheaders\fP and \fBdecode\fP arguments to True, respectively. .SS Using Salt at scale .sp The focus of this tutorial will be building a Salt infrastructure for handling large numbers of minions. This will include tuning, topology, and best practices. .sp For how to install the Salt Master please go here: \fI\%Installing saltstack\fP .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 This tutorial is intended for large installations, although these same settings won\(aqt hurt, it may not be worth the complexity to smaller installations. .sp When used with minions, the term \(aqmany\(aq refers to at least a thousand and \(aqa few\(aq always means 500. .sp For simplicity reasons, this tutorial will default to the standard ports used by Salt. .UNINDENT .UNINDENT .SS The Master .sp The most common problems on the Salt Master are: .INDENT 0.0 .IP 1. 3 too many minions authing at once .IP 2. 3 too many minions re\-authing at once .IP 3. 3 too many minions re\-connecting at once .IP 4. 3 too many minions returning at once .IP 5. 3 too few resources (CPU/HDD) .UNINDENT .sp The first three are all "thundering herd" problems. To mitigate these issues we must configure the minions to back\-off appropriately when the Master is under heavy load. .sp The fourth is caused by masters with little hardware resources in combination with a possible bug in ZeroMQ. At least that\(aqs what it looks like till today (\fI\%Issue 118651\fP, \fI\%Issue 5948\fP, \fI\%Mail thread\fP) .sp To fully understand each problem, it is important to understand, how Salt works. .sp Very briefly, the Salt Master offers two services to the minions. .INDENT 0.0 .IP \(bu 2 a job publisher on port 4505 .IP \(bu 2 an open port 4506 to receive the minions returns .UNINDENT .sp All minions are always connected to the publisher on port 4505 and only connect to the open return port 4506 if necessary. On an idle Master, there will only be connections on port 4505. .SS Too many minions authing .sp When the Minion service is first started up, it will connect to its Master\(aqs publisher on port 4505. If too many minions are started at once, this can cause a "thundering herd". This can be avoided by not starting too many minions at once. .sp The connection itself usually isn\(aqt the culprit, the more likely cause of master\-side issues is the authentication that the Minion must do with the Master. If the Master is too heavily loaded to handle the auth request it will time it out. The Minion will then wait \fIacceptance_wait_time\fP to retry. If \fIacceptance_wait_time_max\fP is set then the Minion will increase its wait time by the \fIacceptance_wait_time\fP each subsequent retry until reaching \fIacceptance_wait_time_max\fP\&. .SS Too many minions re\-authing .sp This is most likely to happen in the testing phase of a Salt deployment, when all Minion keys have already been accepted, but the framework is being tested and parameters are frequently changed in the Salt Master\(aqs configuration file(s). .sp The Salt Master generates a new AES key to encrypt its publications at certain events such as a Master restart or the removal of a Minion key. If you are encountering this problem of too many minions re\-authing against the Master, you will need to recalibrate your setup to reduce the rate of events like a Master restart or Minion key removal (\fBsalt\-key \-d\fP). .sp When the Master generates a new AES key, the minions aren\(aqt notified of this but will discover it on the next pub job they receive. When the Minion receives such a job it will then re\-auth with the Master. Since Salt does minion\-side filtering this means that all the minions will re\-auth on the next command published on the master\-\- causing another "thundering herd". This can be avoided by setting the .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C random_reauth_delay: 60 .ft P .fi .UNINDENT .UNINDENT .sp in the minions configuration file to a higher value and stagger the amount of re\-auth attempts. Increasing this value will of course increase the time it takes until all minions are reachable via Salt commands. .SS Too many minions re\-connecting .sp By default the zmq socket will re\-connect every 100ms which for some larger installations may be too quick. This will control how quickly the TCP session is re\-established, but has no bearing on the auth load. .sp To tune the minions sockets reconnect attempts, there are a few values in the sample configuration file (default values) .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C recon_default: 1000 recon_max: 5000 recon_randomize: True .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .IP \(bu 2 recon_default: the default value the socket should use, i.e. 1000. This value is in milliseconds. (1000ms = 1 second) .IP \(bu 2 recon_max: the max value that the socket should use as a delay before trying to reconnect This value is in milliseconds. (5000ms = 5 seconds) .IP \(bu 2 recon_randomize: enables randomization between recon_default and recon_max .UNINDENT .sp To tune this values to an existing environment, a few decision have to be made. .INDENT 0.0 .IP 1. 3 How long can one wait, before the minions should be online and reachable via Salt? .IP 2. 3 How many reconnects can the Master handle without a syn flood? .UNINDENT .sp These questions can not be answered generally. Their answers depend on the hardware and the administrators requirements. .sp Here is an example scenario with the goal, to have all minions reconnect within a 60 second time\-frame on a Salt Master service restart. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C recon_default: 1000 recon_max: 59000 recon_randomize: True .ft P .fi .UNINDENT .UNINDENT .sp 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 and 60000ms (or between 1 and 60 seconds). The generated random\-value will be doubled after each attempt to reconnect (ZeroMQ default behavior). .sp Lets say the generated random value is 11 seconds (or 11000ms). .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C 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. .ft P .fi .UNINDENT .UNINDENT .sp With a thousand minions this will mean .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C 1000/60 = ~16 .ft P .fi .UNINDENT .UNINDENT .sp round about 16 connection attempts a second. These values should be altered to values that match your environment. Keep in mind though, that it may grow over time and that more minions might raise the problem again. .SS Too many minions returning at once .sp This can also happen during the testing phase, if all minions are addressed at once with .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C $ salt * disk.usage .ft P .fi .UNINDENT .UNINDENT .sp it may cause thousands of minions trying to return their data to the Salt Master open port 4506. Also causing a flood of syn\-flood if the Master can\(aqt handle that many returns at once. .sp This can be easily avoided with Salt\(aqs batch mode: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C $ salt * disk.usage \-b 50 .ft P .fi .UNINDENT .UNINDENT .sp This will only address 50 minions at once while looping through all addressed minions. .SS Too few resources .sp The masters resources always have to match the environment. There is no way to give good advise without knowing the environment the Master is supposed to run in. But here are some general tuning tips for different situations: .SS The Master is CPU bound .sp Salt uses RSA\-Key\-Pairs on the masters and minions end. Both generate 4096 bit key\-pairs on first start. While the key\-size for the Master is currently not configurable, the minions keysize can be configured with different key\-sizes. For example with a 2048 bit key: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C keysize: 2048 .ft P .fi .UNINDENT .UNINDENT .sp With thousands of decryptions, the amount of time that can be saved on the masters end should not be neglected. See here for reference: \fI\%Pull Request 9235\fP how much influence the key\-size can have. .sp Downsizing the Salt Master\(aqs key is not that important, because the minions do not encrypt as many messages as the Master does. .sp In installations with large or with complex pillar files, it is possible for the master to exhibit poor performance as a result of having to render many pillar files at once. This exhibit itself in a number of ways, both as high load on the master and on minions which block on waiting for their pillar to be delivered to them. .sp To reduce pillar rendering times, it is possible to cache pillars on the master. To do this, see the set of master configuration options which are prefixed with \fIpillar_cache\fP\&. .sp If many pillars are encrypted using \fBgpg\fP renderer, it is possible to cache GPG data. To do this, see the set of master configuration options which are prefixed with \fIgpg_cache\fP\&. .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 Caching pillars or GPG data on the master may introduce security considerations. Be certain to read caveats outlined in the master configuration file to understand how pillar caching may affect a master\(aqs ability to protect sensitive data! .UNINDENT .UNINDENT .SS The Master is disk IO bound .sp By default, the Master saves every Minion\(aqs return for every job in its job\-cache. The cache can then be used later, to lookup results for previous jobs. The default directory for this is: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C cachedir: /var/cache/salt .ft P .fi .UNINDENT .UNINDENT .sp and then in the \fB/proc\fP directory. .sp Each job return for every Minion is saved in a single file. Over time this directory can grow quite large, depending on the number of published jobs. The amount of files and directories will scale with the number of jobs published and the retention time defined by .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C keep_jobs: 24 .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C 250 jobs/day * 2000 minions returns = 500,000 files a day .ft P .fi .UNINDENT .UNINDENT .SS Use and External Job Cache .sp An external job cache allows for job storage to be placed on an external system, such as a database. .INDENT 0.0 .IP \(bu 2 ext_job_cache: this will have the minions store their return data directly into a returner (not sent through the Master) .IP \(bu 2 master_job_cache (New in \fI2014.7.0\fP): this will make the Master store the job data using a returner (instead of the local job cache on disk). .UNINDENT .sp If a master has many accepted keys, it may take a long time to publish a job because the master must first determine the matching minions and deliver that information back to the waiting client before the job can be published. .sp To mitigate this, a key cache may be enabled. This will reduce the load on the master to a single file open instead of thousands or tens of thousands. .sp This cache is updated by the maintanence process, however, which means that minions with keys that are accepted may not be targeted by the master for up to sixty seconds by default. .sp To enable the master key cache, set \fIkey_cache: \(aqsched\(aq\fP in the master configuration file. .SS Disable The Job Cache .sp The job cache is a central component of the Salt Master and many aspects of the Salt Master will not function correctly without a running job cache. .sp Disabling the job cache is \fBSTRONGLY DISCOURAGED\fP and should not be done unless the master is being used to execute routines that require no history or reliable feedback! .sp The job cache can be disabled: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C job_cache: False .ft P .fi .UNINDENT .UNINDENT .SS How to Convert Jinja Logic to an Execution Module .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 This tutorial assumes a basic knowledge of Salt states and specifically experience using the \fImaps.jinja\fP idiom. .sp This tutorial was written by a salt user who was told "if your maps.jinja is too complicated, write an execution module!". If you are experiencing over\-complicated jinja, read on. .UNINDENT .UNINDENT .SS The Problem: Jinja Gone Wild .sp It is often said in the Salt community that "Jinja is not a Programming Language". There\(aqs an even older saying known as Maslow\(aqs hammer. It goes something like "if all you have is a hammer, everything looks like a nail". Jinja is a reliable hammer, and so is the \fImaps.jinja\fP idiom. Unfortunately, it can lead to code that looks like the following. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C # storage/maps.yaml {% import_yaml \(aqstorage/defaults.yaml\(aq as default_settings %} {% set storage = default_settings.storage %} {% do storage.update(salt[\(aqgrains.filter_by\(aq]({ \(aqDebian\(aq: { }, \(aqRedHat\(aq: { } }, merge=salt[\(aqpillar.get\(aq](\(aqstorage:lookup\(aq))) %} {% if \(aqVirtualBox\(aq == grains.get(\(aqvirtual\(aq, None) or \(aqoracle\(aq == grains.get(\(aqvirtual\(aq, None) %} {% do storage.update({\(aqdepot_ip\(aq: \(aq192.168.33.81\(aq, \(aqserver_ip\(aq: \(aq192.168.33.51\(aq}) %} {% else %} {% set colo = pillar.get(\(aqinventory\(aq, {}).get(\(aqcolo\(aq, \(aqUnknown\(aq) %} {% set servers_list = pillar.get(\(aqstorage_servers\(aq, {}).get(colo, [storage.depot_ip, ]) %} {% if opts.id.startswith(\(aqfoo\(aq) %} {% set modulus = servers_list | count %} {% set integer_id = opts.id | replace(\(aqfoo\(aq, \(aq\(aq) | int %} {% set server_index = integer_id % modulus %} {% else %} {% set server_index = 0 %} {% endif %} {% do storage.update({\(aqserver_ip\(aq: servers_list[server_index]}) %} {% endif %} {% for network, _ in salt.pillar.get(\(aqinventory:networks\(aq, {}) | dictsort %} {% do storage.ipsets.hash_net.foo_networks.append(network) %} {% endfor %} .ft P .fi .UNINDENT .UNINDENT .sp This is an example from the author\(aqs salt formulae demonstrating misuse of jinja. Aside from being difficult to read and maintain, accessing the logic it contains from a non\-jinja renderer while probably possible is a significant barrier! .SS Refactor .sp The first step is to reduce the maps.jinja file to something reasonable. This gives us an idea of what the module we are writing needs to do. There is a lot of logic around selecting a storage server ip. Let\(aqs move that to an execution module. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C # storage/maps.yaml {% import_yaml \(aqstorage/defaults.yaml\(aq as default_settings %} {% set storage = default_settings.storage %} {% do storage.update(salt[\(aqgrains.filter_by\(aq]({ \(aqDebian\(aq: { }, \(aqRedHat\(aq: { } }, merge=salt[\(aqpillar.get\(aq](\(aqstorage:lookup\(aq))) %} {% if \(aqVirtualBox\(aq == grains.get(\(aqvirtual\(aq, None) or \(aqoracle\(aq == grains.get(\(aqvirtual\(aq, None) %} {% do storage.update({\(aqdepot_ip\(aq: \(aq192.168.33.81\(aq}) %} {% endif %} {% do storage.update({\(aqserver_ip\(aq: salt[\(aqstorage.ip\(aq]()}) %} {% for network, _ in salt.pillar.get(\(aqinventory:networks\(aq, {}) | dictsort %} {% do storage.ipsets.hash_net.af_networks.append(network) %} {% endfor %} .ft P .fi .UNINDENT .UNINDENT .sp And then, write the module. Note how the module encapsulates all of the logic around finding the storage server IP. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C # _modules/storage.py #!python """ Functions related to storage servers. """ import re def ips(): """ Provide a list of all local storage server IPs. CLI Example:: salt \e* storage.ips """ if __grains__.get("virtual", None) in ["VirtualBox", "oracle"]: return [ "192.168.33.51", ] colo = __pillar__.get("inventory", {}).get("colo", "Unknown") return __pillar__.get("storage_servers", {}).get(colo, ["unknown",]) def ip(): """ Select and return a local storage server IP. This loadbalances across storage servers by using the modulus of the client\(aqs id number. :maintainer: Andrew Hammond :maturity: new :depends: None :platform: all CLI Example:: salt \e* storage.ip """ numerical_suffix = re.compile(r"^.*(\ed+)$") servers_list = ips() m = numerical_suffix.match(__grains__["id"]) if m: modulus = len(servers_list) server_number = int(m.group(1)) server_index = server_number % modulus else: server_index = 0 return servers_list[server_index] .ft P .fi .UNINDENT .UNINDENT .SS Conclusion .sp That was... surprisingly straight\-forward. Now the logic is available in every renderer, instead of just Jinja. Best of all, it can be maintained in Python, which is a whole lot easier than Jinja. .SS Using Apache Libcloud for declarative and procedural multi\-cloud orchestration .sp New in version 2018.3.0. .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 This walkthrough assumes basic knowledge of Salt and Salt States. To get up to speed, check out the Salt Walkthrough\&. .UNINDENT .UNINDENT .sp Apache Libcloud is a Python library which hides differences between different cloud provider APIs and allows you to manage different cloud resources through a unified and easy to use API. Apache Libcloud supports over 60 cloud platforms, including Amazon, Microsoft Azure, DigitalOcean, Google Cloud Platform and OpenStack. .INDENT 0.0 .TP .B Execution and state modules are available for Compute, DNS, Storage and Load Balancer drivers from Apache Libcloud in SaltStack. .UNINDENT .INDENT 0.0 .IP \(bu 2 .INDENT 2.0 .TP .B \fBlibcloud_compute\fP \- Compute \- services such as OpenStack Nova, Amazon EC2, Microsoft Azure VMs .UNINDENT .IP \(bu 2 .INDENT 2.0 .TP .B \fBlibcloud_dns\fP \- DNS as a Service \- services such as Amazon Route 53 and Zerigo .UNINDENT .IP \(bu 2 .INDENT 2.0 .TP .B \fBlibcloud_loadbalancer\fP \- Load Balancers as a Service \- services such as Amazon Elastic Load Balancer and GoGrid LoadBalancers .UNINDENT .IP \(bu 2 .INDENT 2.0 .TP .B \fBlibcloud_storage\fP \- Cloud Object Storage and CDN \- services such as Amazon S3 and Rackspace CloudFiles, OpenStack Swift .UNINDENT .UNINDENT .sp These modules are designed as a way of having a multi\-cloud deployment and abstracting simple differences between platform to design a high\-availability architecture. .sp The Apache Libcloud functionality is available through both execution modules and Salt states. .SS Configuring Drivers .sp Drivers can be configured in the Salt Configuration/Minion settings. All libcloud modules expect a list of "profiles" to be configured with authentication details for each driver. .sp Each driver will have a string identifier, these can be found in the libcloud..types.Provider class for each API, \fI\%https://libcloud.readthedocs.io/en/latest/supported_providers.html\fP .sp Some drivers require additional parameters, which are documented in the Apache Libcloud documentation. For example, GoDaddy DNS expects "\fIshopper_id\fP", which is the customer ID. These additional parameters can be added to the profile settings and will be passed directly to the driver instantiation method. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C libcloud_dns: godaddy: driver: godaddy shopper_id: 90425123 key: AFDDJFGIjDFVNSDIFNASMC secret: FG(#f8vdfgjlkm) libcloud_storage: google: driver: google_storage key: GOOG4ASDIDFNVIdfnIVW secret: R+qYE9hkfdhv89h4invhdfvird4Pq3an8rnK .ft P .fi .UNINDENT .UNINDENT .sp You can have multiple profiles for a single driver, for example if you wanted 2 DNS profiles for Amazon Route53, naming them "route53_prod" and "route54_test" would help your administrators distinguish their purpose. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C libcloud_dns: route53_prod: driver: route53 key: AFDDJFGIjDFVNSDIFNASMC secret: FG(#f8vdfgjlkm) route53_test: driver: route53 key: AFDDJFGIjdfgdfgdf secret: FG(#f8vdfgjlkm) .ft P .fi .UNINDENT .UNINDENT .SS Using the execution modules .sp Amongst over 60 clouds that Apache Libcloud supports, you can add profiles to your Salt configuration to access and control these clouds. Each of the libcloud execution modules exposes the common API methods for controlling Compute, DNS, Load Balancers and Object Storage. To see which functions are supported across specific clouds, see the Libcloud \fI\%supported methods\fP documentation. .sp The module documentation explains each of the API methods and how to leverage them. .INDENT 0.0 .IP \(bu 2 .INDENT 2.0 .TP .B \fBlibcloud_compute\fP \- Compute \- services such as OpenStack Nova, Amazon EC2, Microsoft Azure VMs .UNINDENT .IP \(bu 2 .INDENT 2.0 .TP .B \fBlibcloud_dns\fP \- DNS as a Service \- services such as Amazon Route 53 and Zerigo .UNINDENT .IP \(bu 2 .INDENT 2.0 .TP .B \fBlibcloud_loadbalancer\fP \- Load Balancers as a Service \- services such as Amazon Elastic Load Balancer and GoGrid LoadBalancers .UNINDENT .IP \(bu 2 .INDENT 2.0 .TP .B \fBlibcloud_storage\fP \- Cloud Object Storage and CDN \- services such as Amazon S3 and Rackspace CloudFiles, OpenStack Swift .UNINDENT .UNINDENT .sp For example, listing buckets in the Google Storage platform: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C $ salt\-call libcloud_storage.list_containers google local: |_ \-\-\-\-\-\-\-\-\-\- extra: \-\-\-\-\-\-\-\-\-\- creation_date: 2017\-01\-05T05:44:56.324Z name: anthonypjshaw .ft P .fi .UNINDENT .UNINDENT .sp The Apache Libcloud storage module can be used to synchronize files between multiple storage clouds, such as Google Storage, S3 and OpenStack Swift .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C $ salt \(aq*\(aq libcloud_storage.download_object DeploymentTools test.sh /tmp/test.sh google_storage .ft P .fi .UNINDENT .UNINDENT .SS Using the state modules .sp For each configured profile, the assets available in the API (e.g. storage objects, containers, DNS records and load balancers) can be deployed via Salt\(aqs state system. .sp The state module documentation explains the specific states that each module supports .INDENT 0.0 .IP \(bu 2 .INDENT 2.0 .TP .B \fBlibcloud_storage\fP \- Cloud Object Storage and CDN .INDENT 7.0 .IP \(bu 2 services such as Amazon S3 and Rackspace CloudFiles, OpenStack Swift .UNINDENT .UNINDENT .IP \(bu 2 .INDENT 2.0 .TP .B \fBlibcloud_loadbalancer\fP \- Load Balancers as a Service .INDENT 7.0 .IP \(bu 2 services such as Amazon Elastic Load Balancer and GoGrid LoadBalancers .UNINDENT .UNINDENT .IP \(bu 2 .INDENT 2.0 .TP .B \fBlibcloud_dns\fP \- DNS as a Service .INDENT 7.0 .IP \(bu 2 services such as Amazon Route 53 and Zerigo .UNINDENT .UNINDENT .UNINDENT .sp For DNS, the state modules can be used to provide DNS resilience for multiple nameservers, for example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C libcloud_dns: godaddy: driver: godaddy shopper_id: 12345 key: 2orgk34kgk34g secret: fjgoidhjgoim amazon: driver: route53 key: blah secret: blah .ft P .fi .UNINDENT .UNINDENT .sp And then in a state file: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C webserver: libcloud_dns.zone_present: name: mywebsite.com profile: godaddy libcloud_dns.record_present: name: www zone: mywebsite.com type: A data: 12.34.32.3 profile: godaddy libcloud_dns.zone_present: name: mywebsite.com profile: amazon libcloud_dns.record_present: name: www zone: mywebsite.com type: A data: 12.34.32.3 profile: amazon .ft P .fi .UNINDENT .UNINDENT .sp This could be combined with a multi\-cloud load balancer deployment, .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C webserver: libcloud_dns.zone_present: \- name: mywebsite.com \- profile: godaddy ... libcloud_loadbalancer.balancer_present: \- name: web_main \- port: 80 \- protocol: http \- members: \- ip: 1.2.4.5 port: 80 \- ip: 2.4.5.6 port: 80 \- profile: google_gce libcloud_loadbalancer.balancer_present: \- name: web_main \- port: 80 \- protocol: http \- members: \- ip: 1.2.4.5 port: 80 \- ip: 2.4.5.6 port: 80 \- profile: amazon_elb .ft P .fi .UNINDENT .UNINDENT .sp Extended parameters can be passed to the specific cloud, for example you can specify the region with the Google Cloud API, because \fIcreate_balancer\fP can accept a \fIex_region\fP argument. Adding this argument to the state will pass the additional command to the driver. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C lb_test: libcloud_loadbalancer.balancer_absent: \- name: example \- port: 80 \- protocol: http \- profile: google \- ex_region: us\-east1 .ft P .fi .UNINDENT .UNINDENT .SS Accessing custom arguments in execution modules .sp Some cloud providers have additional functionality that can be accessed on top of the base API, for example the Google Cloud Engine load balancer service offers the ability to provision load balancers into a specific region. .sp Looking at the \fI\%API documentation\fP, we can see that it expects an \fIex_region\fP in the \fIcreate_balancer\fP method, so when we execute the salt command, we can add this additional parameter like this: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C $ salt myminion libcloud_storage.create_balancer my_balancer 80 http profile1 ex_region=us\-east1 $ salt myminion libcloud_storage.list_container_objects my_bucket profile1 ex_prefix=me .ft P .fi .UNINDENT .UNINDENT .SS Accessing custom methods in Libcloud drivers .sp Some cloud APIs have additional methods that are prefixed with \fIex_\fP in Apache Libcloud, these methods are part of the non\-standard API but can still be accessed from the Salt modules for \fIlibcloud_storage\fP, \fIlibcloud_loadbalancer\fP and \fIlibcloud_dns\fP\&. The extra methods are available via the \fIextra\fP command, which expects the name of the method as the first argument, the profile as the second and then accepts a list of keyword arguments to pass onto the driver method, for example, accessing permissions in Google Storage objects: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C $ salt myminion libcloud_storage.extra ex_get_permissions google container_name=my_container object_name=me.jpg \-\-out=yaml .ft P .fi .UNINDENT .UNINDENT .SS Example profiles .SS Google Cloud .sp Using Service Accounts with GCE, you can provide a path to the JSON file and the project name in the parameters. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C google: driver: gce user_id: 234234\-compute@developer.gserviceaccount.com key: /path/to/service_account_download.json auth_type: SA project: project\-name .ft P .fi .UNINDENT .UNINDENT .SS LXC Management with Salt .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 .SS Dependencies .sp Manipulation of LXC containers in Salt requires the minion to have an LXC version of at least 1.0 (an alpha or beta release of LXC 1.0 is acceptable). The following distributions are known to have new enough versions of LXC packaged: .INDENT 0.0 .IP \(bu 2 RHEL/CentOS 6 and later (via \fI\%EPEL\fP) .IP \(bu 2 Fedora (All non\-EOL releases) .IP \(bu 2 Debian 8.0 (Jessie) .IP \(bu 2 Ubuntu 14.04 LTS and later (LXC templates are packaged separately as \fBlxc\-templates\fP, it is recommended to also install this package) .IP \(bu 2 openSUSE 13.2 and later .UNINDENT .SS Profiles .sp Profiles allow for a sort of shorthand for commonly\-used configurations to be defined in the minion config file, grains, pillar, or the master config file. The profile is retrieved by Salt using the \fBconfig.get\fP function, which looks in those locations, in that order. This allows for profiles to be defined centrally in the master config file, with several options for overriding them (if necessary) on groups of minions or individual minions. .sp There are two types of profiles: .INDENT 0.0 .INDENT 3.5 .INDENT 0.0 .IP \(bu 2 One for defining the parameters used in container creation/clone. .IP \(bu 2 One for defining the container\(aqs network interface(s) settings. .UNINDENT .UNINDENT .UNINDENT .SS Container Profiles .sp LXC container profiles are defined underneath the \fBlxc.container_profile\fP config option: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C lxc.container_profile: centos: template: centos backing: lvm vgname: vg1 lvname: lxclv size: 10G centos_big: template: centos backing: lvm vgname: vg1 lvname: lxclv size: 20G .ft P .fi .UNINDENT .UNINDENT .sp Profiles are retrieved using the \fBconfig.get\fP function, with the \fBrecurse\fP merge strategy. This means that a profile can be defined at a lower level (for example, the master config file) and then parts of it can be overridden at a higher level (for example, in pillar data). Consider the following container profile data: .sp \fBIn the Master config file:\fP .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C lxc.container_profile: centos: template: centos backing: lvm vgname: vg1 lvname: lxclv size: 10G .ft P .fi .UNINDENT .UNINDENT .sp \fBIn the Pillar data\fP .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C lxc.container_profile: centos: size: 20G .ft P .fi .UNINDENT .UNINDENT .sp Any minion with the above Pillar data would have the \fBsize\fP parameter in the \fBcentos\fP profile overridden to 20G, while those minions without the above Pillar data would have the 10G \fBsize\fP value. This is another way of achieving the same result as the \fBcentos_big\fP profile above, without having to define another whole profile that differs in just one value. .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 In the 2014.7.x release cycle and earlier, container profiles are defined under \fBlxc.profile\fP\&. This parameter will still work in version 2015.5.0, but is deprecated and will be removed in a future release. Please note however that the profile merging feature described above will only work with profiles defined under \fBlxc.container_profile\fP, and only in versions 2015.5.0 and later. .UNINDENT .UNINDENT .sp Additionally, in version 2015.5.0 container profiles have been expanded to support passing template\-specific CLI options to \fBlxc.create\fP\&. Below is a table describing the parameters which can be configured in container profiles: .TS center; |l|l|l|. _ T{ Parameter T} T{ 2015.5.0 and Newer T} T{ 2014.7.x and Earlier T} _ T{ \fItemplate\fP\s-2\u1\d\s0 T} T{ Yes T} T{ Yes T} _ T{ \fIoptions\fP\s-2\u1\d\s0 T} T{ Yes T} T{ No T} _ T{ \fIimage\fP\s-2\u1\d\s0 T} T{ Yes T} T{ Yes T} _ T{ \fIbacking\fP T} T{ Yes T} T{ Yes T} _ T{ \fIsnapshot\fP\s-2\u2\d\s0 T} T{ Yes T} T{ Yes T} _ T{ \fIlvname\fP\s-2\u1\d\s0 T} T{ Yes T} T{ Yes T} _ T{ \fIfstype\fP\s-2\u1\d\s0 T} T{ Yes T} T{ Yes T} _ T{ \fIsize\fP T} T{ Yes T} T{ Yes T} _ .TE .INDENT 0.0 .IP 1. 3 Parameter is only supported for container creation, and will be ignored if the profile is used when cloning a container. .IP 2. 3 Parameter is only supported for container cloning, and will be ignored if the profile is used when not cloning a container. .UNINDENT .SS Network Profiles .sp LXC network profiles are defined defined underneath the \fBlxc.network_profile\fP config option. By default, the module uses a DHCP based configuration and try to guess a bridge to get connectivity. .sp \fBWARNING:\fP .INDENT 0.0 .INDENT 3.5 on pre \fB2015.5.2\fP, you need to specify explicitly the network bridge .UNINDENT .UNINDENT .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C lxc.network_profile: centos: eth0: link: br0 type: veth flags: up ubuntu: eth0: link: lxcbr0 type: veth flags: up .ft P .fi .UNINDENT .UNINDENT .sp As with container profiles, network profiles are retrieved using the \fBconfig.get\fP function, with the \fBrecurse\fP merge strategy. Consider the following network profile data: .sp \fBIn the Master config file:\fP .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C lxc.network_profile: centos: eth0: link: br0 type: veth flags: up .ft P .fi .UNINDENT .UNINDENT .sp \fBIn the Pillar data\fP .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C lxc.network_profile: centos: eth0: link: lxcbr0 .ft P .fi .UNINDENT .UNINDENT .sp Any minion with the above Pillar data would use the \fBlxcbr0\fP interface as the bridge interface for any container configured using the \fBcentos\fP network profile, while those minions without the above Pillar data would use the \fBbr0\fP interface for the same. .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 In the 2014.7.x release cycle and earlier, network profiles are defined under \fBlxc.nic\fP\&. This parameter will still work in version 2015.5.0, but is deprecated and will be removed in a future release. Please note however that the profile merging feature described above will only work with profiles defined under \fBlxc.network_profile\fP, and only in versions 2015.5.0 and later. .UNINDENT .UNINDENT .sp The following are parameters which can be configured in network profiles. These will directly correspond to a parameter in an LXC configuration file (see \fBman 5 lxc.container.conf\fP). .INDENT 0.0 .IP \(bu 2 \fBtype\fP \- Corresponds to \fBlxc.network.type\fP .IP \(bu 2 \fBlink\fP \- Corresponds to \fBlxc.network.link\fP .IP \(bu 2 \fBflags\fP \- Corresponds to \fBlxc.network.flags\fP .UNINDENT .sp Interface\-specific options (MAC address, IPv4/IPv6, etc.) must be passed on a container\-by\-container basis, for instance using the \fBnic_opts\fP argument to \fBlxc.create\fP: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt myminion lxc.create container1 profile=centos network_profile=centos nic_opts=\(aq{eth0: {ipv4: 10.0.0.20/24, gateway: 10.0.0.1}}\(aq .ft P .fi .UNINDENT .UNINDENT .sp \fBWARNING:\fP .INDENT 0.0 .INDENT 3.5 The \fBipv4\fP, \fBipv6\fP, \fBgateway\fP, and \fBlink\fP (bridge) settings in network profiles / nic_opts will only work if the container doesn\(aqt redefine the network configuration (for example in \fB/etc/sysconfig/network\-scripts/ifcfg\-\fP on RHEL/CentOS, or \fB/etc/network/interfaces\fP on Debian/Ubuntu/etc.). Use these with caution. The container images installed using the \fBdownload\fP template, for instance, typically are configured for eth0 to use DHCP, which will conflict with static IP addresses set at the container level. .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 For LXC < 1.0.7 and DHCP support, set \fBipv4.gateway: \(aqauto\(aq\fP is your network profile, ie.: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C lxc.network_profile.nic: debian: eth0: link: lxcbr0 ipv4.gateway: \(aqauto\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .UNINDENT .SS Old lxc support (<1.0.7) .sp With saltstack \fB2015.5.2\fP and above, normally the setting is autoselected, but before, you\(aqll need to teach your network profile to set \fBlxc.network.ipv4.gateway\fP to \fBauto\fP when using a classic ipv4 configuration. .sp Thus you\(aqll need .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C lxc.network_profile.foo: etho: link: lxcbr0 ipv4.gateway: auto .ft P .fi .UNINDENT .UNINDENT .SS Tricky network setups Examples .sp This example covers how to make a container with both an internal ip and a public routable ip, wired on two veth pairs. .sp The another interface which receives directly a public routable ip can\(aqt be on the first interface that we reserve for private inter LXC networking. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C lxc.network_profile.foo: eth0: {gateway: null, bridge: lxcbr0} eth1: # replace that by your main interface \(aqlink\(aq: \(aqbr0\(aq \(aqmac\(aq: \(aq00:16:5b:01:24:e1\(aq \(aqgateway\(aq: \(aq2.20.9.14\(aq \(aqipv4\(aq: \(aq2.20.9.1\(aq .ft P .fi .UNINDENT .UNINDENT .SS Creating a Container on the CLI .SS From a Template .sp LXC is commonly distributed with several template scripts in /usr/share/lxc/templates. Some distros may package these separately in an \fBlxc\-templates\fP package, so make sure to check if this is the case. .sp There are LXC template scripts for several different operating systems, but some of them are designed to use tools specific to a given distribution. For instance, the \fBubuntu\fP template uses deb_bootstrap, the \fBcentos\fP template uses yum, etc., making these templates impractical when a container from a different OS is desired. .sp The \fBlxc.create\fP function is used to create containers using a template script. To create a CentOS container named \fBcontainer1\fP on a CentOS minion named \fBmycentosminion\fP, using the \fBcentos\fP LXC template, one can simply run the following command: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt mycentosminion lxc.create container1 template=centos .ft P .fi .UNINDENT .UNINDENT .sp For these instances, there is a \fBdownload\fP template which retrieves minimal container images for several different operating systems. To use this template, it is necessary to provide an \fBoptions\fP parameter when creating the container, with three values: .INDENT 0.0 .IP 1. 3 \fBdist\fP \- the Linux distribution (i.e. \fBubuntu\fP or \fBcentos\fP) .IP 2. 3 \fBrelease\fP \- the release name/version (i.e. \fBtrusty\fP or \fB6\fP) .IP 3. 3 \fBarch\fP \- CPU architecture (i.e. \fBamd64\fP or \fBi386\fP) .UNINDENT .sp The \fBlxc.images\fP function (new in version 2015.5.0) can be used to list the available images. Alternatively, the releases can be viewed on \fI\%http://images.linuxcontainers.org/images/\fP\&. The images are organized in such a way that the \fBdist\fP, \fBrelease\fP, and \fBarch\fP can be determined using the following URL format: \fBhttp://images.linuxcontainers.org/images/dist/release/arch\fP\&. For example, \fBhttp://images.linuxcontainers.org/images/centos/6/amd64\fP would correspond to a \fBdist\fP of \fBcentos\fP, a \fBrelease\fP of \fB6\fP, and an \fBarch\fP of \fBamd64\fP\&. .sp Therefore, to use the \fBdownload\fP template to create a new 64\-bit CentOS 6 container, the following command can be used: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt myminion lxc.create container1 template=download options=\(aq{dist: centos, release: 6, arch: amd64}\(aq .ft P .fi .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 These command\-line options can be placed into a \fI\%container profile\fP, like so: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C lxc.container_profile.cent6: template: download options: dist: centos release: 6 arch: amd64 .ft P .fi .UNINDENT .UNINDENT .sp The \fBoptions\fP parameter is not supported in profiles for the 2014.7.x release cycle and earlier, so it would still need to be provided on the command\-line. .UNINDENT .UNINDENT .SS Cloning an Existing Container .sp To clone a container, use the \fBlxc.clone\fP function: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt myminion lxc.clone container2 orig=container1 .ft P .fi .UNINDENT .UNINDENT .SS Using a Container Image .sp While cloning is a good way to create new containers from a common base container, the source container that is being cloned needs to already exist on the minion. This makes deploying a common container across minions difficult. For this reason, Salt\(aqs \fBlxc.create\fP is capable of installing a container from a tar archive of another container\(aqs rootfs. To create an image of a container named \fBcent6\fP, run the following command as root: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C tar czf cent6.tar.gz \-C /var/lib/lxc/cent6 rootfs .ft P .fi .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 Before doing this, it is recommended that the container is stopped. .UNINDENT .UNINDENT .sp The resulting tarball can then be placed alongside the files in the salt fileserver and referenced using a \fBsalt://\fP URL. To create a container using an image, use the \fBimage\fP parameter with \fBlxc.create\fP: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt myminion lxc.create new\-cent6 image=salt://path/to/cent6.tar.gz .ft P .fi .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 Making images of containers with LVM backing .sp For containers with LVM backing, the rootfs is not mounted, so it is necessary to mount it first before creating the tar archive. When a container is created using LVM backing, an empty \fBrootfs\fP dir is handily created within \fB/var/lib/lxc/container_name\fP, so this can be used as the mountpoint. The location of the logical volume for the container will be \fB/dev/vgname/lvname\fP, where \fBvgname\fP is the name of the volume group, and \fBlvname\fP is the name of the logical volume. Therefore, assuming a volume group of \fBvg1\fP, a logical volume of \fBlxc\-cent6\fP, and a container name of \fBcent6\fP, the following commands can be used to create a tar archive of the rootfs: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C mount /dev/vg1/lxc\-cent6 /var/lib/lxc/cent6/rootfs tar czf cent6.tar.gz \-C /var/lib/lxc/cent6 rootfs umount /var/lib/lxc/cent6/rootfs .ft P .fi .UNINDENT .UNINDENT .UNINDENT .UNINDENT .sp \fBWARNING:\fP .INDENT 0.0 .INDENT 3.5 One caveat of using this method of container creation is that \fB/etc/hosts\fP is left unmodified. This could cause confusion for some distros if salt\-minion is later installed on the container, as the functions that determine the hostname take \fB/etc/hosts\fP into account. .sp Additionally, when creating an rootfs image, be sure to remove \fB/etc/salt/minion_id\fP and make sure that \fBid\fP is not defined in \fB/etc/salt/minion\fP, as this will cause similar issues. .UNINDENT .UNINDENT .SS Initializing a New Container as a Salt Minion .sp The above examples illustrate a few ways to create containers on the CLI, but often it is desirable to also have the new container run as a Minion. To do this, the \fBlxc.init\fP function can be used. This function will do the following: .INDENT 0.0 .IP 1. 3 Create a new container .IP 2. 3 Optionally set password and/or DNS .IP 3. 3 Bootstrap the minion (using either \fI\%salt\-bootstrap\fP or a custom command) .UNINDENT .sp By default, the new container will be pointed at the same Salt Master as the host machine on which the container was created. It will then request to authenticate with the Master like any other bootstrapped Minion, at which point it can be accepted. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt myminion lxc.init test1 profile=centos salt\-key \-a test1 .ft P .fi .UNINDENT .UNINDENT .sp For even greater convenience, the \fBLXC runner\fP contains a runner function of the same name (\fBlxc.init\fP), which creates a keypair, seeds the new minion with it, and pre\-accepts the key, allowing for the new Minion to be created and authorized in a single step: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt\-run lxc.init test1 host=myminion profile=centos .ft P .fi .UNINDENT .UNINDENT .SS Running Commands Within a Container .sp For containers which are not running their own Minion, commands can be run within the container in a manner similar to using (\fBcmd.run \(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.version salt \(aq*.example.org\(aq test.version .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.version .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.version .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.version .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.version .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.version .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 Multi Master Tutorial .sp As of Salt 0.16.0, the ability to connect minions to multiple masters has been made available. The multi\-master system allows for redundancy of Salt masters and facilitates multiple points of communication out to minions. When using a multi\-master setup, all masters are running hot, and any active master can be used to send commands out to the minions. .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 If you need failover capabilities with multiple masters, there is also a MultiMaster\-PKI setup available, that uses a different topology \fI\%MultiMaster\-PKI with Failover Tutorial\fP .UNINDENT .UNINDENT .sp In 0.16.0, the masters do not share any information, keys need to be accepted on both masters, and shared files need to be shared manually or use tools like the git fileserver backend to ensure that the \fBfile_roots\fP are kept consistent. .sp Beginning with Salt 2016.11.0, the Pluggable Minion Data Cache was introduced. The minion data cache contains the Salt Mine data, minion grains, and minion pillar information cached on the Salt Master. By default, Salt uses the \fBlocalfs\fP cache module, but other external data stores can be used instead. .sp Using a pluggable minion cache modules allows for the data stored on a Salt Master about Salt Minions to be replicated on other Salt Masters the Minion is connected to. Please see the Minion Data Cache documentation for more information and configuration examples. .SS Summary of Steps .INDENT 0.0 .IP 1. 3 Create a redundant master server .IP 2. 3 Copy primary master key to redundant master .IP 3. 3 Start redundant master .IP 4. 3 Configure minions to connect to redundant master .IP 5. 3 Restart minions .IP 6. 3 Accept keys on redundant master .UNINDENT .SS Prepping a Redundant Master .sp The first task is to prepare the redundant master. If the redundant master is already running, stop it. There is only one requirement when preparing a redundant master, which is that masters share the same private key. When the first master was created, the master\(aqs identifying key pair was generated and placed in the master\(aqs \fBpki_dir\fP\&. The default location of the master\(aqs key pair is \fB/etc/salt/pki/master/\fP\&. Take the private key, \fBmaster.pem\fP, and copy it to the same location on the redundant master. Do the same for the master\(aqs public key, \fBmaster.pub\fP\&. Assuming that no minions have yet been connected to the new redundant master, it is safe to delete any existing key in this location and replace it. .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 There is no logical limit to the number of redundant masters that can be used. .UNINDENT .UNINDENT .sp Once the new key is in place, the redundant master can be safely started. .SS Configure Minions .sp Since minions need to be master\-aware, the new master needs to be added to the minion configurations. Simply update the minion configurations to list all connected masters: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C master: \- saltmaster1.example.com \- saltmaster2.example.com .ft P .fi .UNINDENT .UNINDENT .sp Now the minion can be safely restarted. .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 If the ipc_mode for the minion is set to TCP (default in Windows), then each minion in the multi\-minion setup (one per master) needs its own tcp_pub_port and tcp_pull_port. .sp If these settings are left as the default 4510/4511, each minion object will receive a port 2 higher than the previous. Thus the first minion will get 4510/4511, the second will get 4512/4513, and so on. If these port decisions are unacceptable, you must configure tcp_pub_port and tcp_pull_port with lists of ports for each master. The length of these lists should match the number of masters, and there should not be overlap in the lists. .UNINDENT .UNINDENT .sp Now the minions will check into the original master and also check into the new redundant master. Both masters are first\-class and have rights to the minions. .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 Minions can automatically detect failed masters and attempt to reconnect to them quickly. To enable this functionality, set \fImaster_alive_interval\fP in the minion config and specify a number of seconds to poll the masters for connection status. .sp If this option is not set, minions will still reconnect to failed masters but the first command sent after a master comes back up may be lost while the minion authenticates. .UNINDENT .UNINDENT .SS Sharing Files Between Masters .sp Salt does not automatically share files between multiple masters. A number of files should be shared or sharing of these files should be strongly considered. .SS Minion Keys .sp Minion keys can be accepted the normal way using \fBsalt\-key\fP on both masters. Keys accepted, deleted, or rejected on one master will NOT be automatically managed on redundant masters; this needs to be taken care of by running salt\-key on both masters or sharing the \fB/etc/salt/pki/master/{minions,minions_pre,minions_rejected}\fP directories between masters. .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 While sharing the \fB/etc/salt/pki/master\fP directory will work, it is strongly discouraged, since allowing access to the \fBmaster.pem\fP key outside of Salt creates a \fISERIOUS\fP security risk. .UNINDENT .UNINDENT .SS File_Roots .sp The \fBfile_roots\fP contents should be kept consistent between masters. Otherwise state runs will not always be consistent on minions since instructions managed by one master will not agree with other masters. .sp The recommended way to sync these is to use a fileserver backend like gitfs or to keep these files on shared storage. .sp \fBIMPORTANT:\fP .INDENT 0.0 .INDENT 3.5 If using gitfs/git_pillar with the cachedir shared between masters using \fI\%GlusterFS\fP, nfs, or another network filesystem, and the masters are running Salt 2015.5.9 or later, it is strongly recommended not to turn off \fBgitfs_global_lock\fP/\fBgit_pillar_global_lock\fP as doing so will cause lock files to be removed if they were created by a different master. .UNINDENT .UNINDENT .SS Pillar_Roots .sp Pillar roots should be given the same considerations as \fBfile_roots\fP\&. .SS Master Configurations .sp While reasons may exist to maintain separate master configurations, it is wise to remember that each master maintains independent control over minions. Therefore, access controls should be in sync between masters unless a valid reason otherwise exists to keep them inconsistent. .sp These access control options include but are not limited to: .INDENT 0.0 .IP \(bu 2 external_auth .IP \(bu 2 publisher_acl .IP \(bu 2 peer .IP \(bu 2 peer_run .UNINDENT .SS Multi\-Master\-PKI Tutorial With Failover .sp This tutorial will explain, how to run a salt\-environment where a single minion can have multiple masters and fail\-over between them if its current master fails. .sp The individual steps are .INDENT 0.0 .IP \(bu 2 setup the master(s) to sign its auth\-replies .IP \(bu 2 setup minion(s) to verify master\-public\-keys .IP \(bu 2 enable multiple masters on minion(s) .IP \(bu 2 enable master\-check on minion(s) .INDENT 2.0 .INDENT 3.5 Please note, that it is advised to have good knowledge of the salt\- authentication and communication\-process to understand this tutorial. All of the settings described here, go on top of the default authentication/communication process. .UNINDENT .UNINDENT .UNINDENT .SS Motivation .sp The default behaviour of a salt\-minion is to connect to a master and accept the masters public key. With each publication, the master sends his public\-key for the minion to check and if this public\-key ever changes, the minion complains and exits. Practically this means, that there can only be a single master at any given time. .sp Would it not be much nicer, if the minion could have any number of masters (1:n) and jump to the next master if its current master died because of a network or hardware failure? .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 There is also a MultiMaster\-Tutorial with a different approach and topology than this one, that might also suite your needs or might even be better suited \fI\%Multi\-Master Tutorial\fP .UNINDENT .UNINDENT .sp It is also desirable, to add some sort of authenticity\-check to the very first public key a minion receives from a master. Currently a minions takes the first masters public key for granted. .SS The Goal .sp Setup the master to sign the public key it sends to the minions and enable the minions to verify this signature for authenticity. .SS Prepping the master to sign its public key .sp For signing to work, both master and minion must have the signing and/or verification settings enabled. If the master signs the public key but the minion does not verify it, the minion will complain and exit. The same happens, when the master does not sign but the minion tries to verify. .sp The easiest way to have the master sign its public key is to set .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C master_sign_pubkey: True .ft P .fi .UNINDENT .UNINDENT .sp After restarting the salt\-master service, the master will automatically generate a new key\-pair .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C master_sign.pem master_sign.pub .ft P .fi .UNINDENT .UNINDENT .sp A custom name can be set for the signing key\-pair by setting .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C master_sign_key_name: .ft P .fi .UNINDENT .UNINDENT .sp The master will then generate that key\-pair upon restart and use it for creating the public keys signature attached to the auth\-reply. .sp The computation is done for every auth\-request of a minion. If many minions auth very often, it is advised to use conf_master:\fImaster_pubkey_signature\fP and conf_master:\fImaster_use_pubkey_signature\fP settings described below. .sp If multiple masters are in use and should sign their auth\-replies, the signing key\-pair master_sign.* has to be copied to each master. Otherwise a minion will fail to verify the masters public when connecting to a different master than it did initially. That is because the public keys signature was created with a different signing key\-pair. .SS Prepping the minion to verify received public keys .sp The minion must have the public key (and only that one!) available to be able to verify a signature it receives. That public key (defaults to master_sign.pub) must be copied from the master to the minions pki\-directory. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C /etc/salt/pki/minion/master_sign.pub .ft P .fi .UNINDENT .UNINDENT .sp \fBIMPORTANT:\fP .INDENT 0.0 .INDENT 3.5 DO NOT COPY THE master_sign.pem FILE. IT MUST STAY ON THE MASTER AND ONLY THERE! .UNINDENT .UNINDENT .sp When that is done, enable the signature checking in the minions configuration .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C verify_master_pubkey_sign: True .ft P .fi .UNINDENT .UNINDENT .sp and restart the minion. For the first try, the minion should be run in manual debug mode. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt\-minion \-l debug .ft P .fi .UNINDENT .UNINDENT .sp Upon connecting to the master, the following lines should appear on the output: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C [DEBUG ] Attempting to authenticate with the Salt Master at 172.16.0.10 [DEBUG ] Loaded minion key: /etc/salt/pki/minion/minion.pem [DEBUG ] salt.crypt.verify_signature: Loading public key [DEBUG ] salt.crypt.verify_signature: Verifying signature [DEBUG ] Successfully verified signature of master public key with verification public key master_sign.pub [INFO ] Received signed and verified master pubkey from master 172.16.0.10 [DEBUG ] Decrypting the current master AES key .ft P .fi .UNINDENT .UNINDENT .sp If the signature verification fails, something went wrong and it will look like this .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C [DEBUG ] Attempting to authenticate with the Salt Master at 172.16.0.10 [DEBUG ] Loaded minion key: /etc/salt/pki/minion/minion.pem [DEBUG ] salt.crypt.verify_signature: Loading public key [DEBUG ] salt.crypt.verify_signature: Verifying signature [DEBUG ] Failed to verify signature of public key [CRITICAL] The Salt Master server\(aqs public key did not authenticate! .ft P .fi .UNINDENT .UNINDENT .sp In a case like this, it should be checked, that the verification pubkey (master_sign.pub) on the minion is the same as the one on the master. .sp Once the verification is successful, the minion can be started in daemon mode again. .sp For the paranoid among us, its also possible to verify the publication whenever it is received from the master. That is, for every single auth\-attempt which can be quite frequent. For example just the start of the minion will force the signature to be checked 6 times for various things like auth, mine, highstate, etc. .sp If that is desired, enable the setting .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C always_verify_signature: True .ft P .fi .UNINDENT .UNINDENT .SS Multiple Masters For A Minion .sp Configuring multiple masters on a minion is done by specifying two settings: .INDENT 0.0 .IP \(bu 2 a list of masters addresses .IP \(bu 2 what type of master is defined .UNINDENT .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C master: \- 172.16.0.10 \- 172.16.0.11 \- 172.16.0.12 .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C master_type: failover .ft P .fi .UNINDENT .UNINDENT .sp This tells the minion that all the master above are available for it to connect to. When started with this configuration, it will try the master in the order they are defined. To randomize that order, set .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C master_shuffle: True .ft P .fi .UNINDENT .UNINDENT .sp The master\-list will then be shuffled before the first connection attempt. .sp The first master that accepts the minion, is used by the minion. If the master does not yet know the minion, that counts as accepted and the minion stays on that master. .sp For the minion to be able to detect if its still connected to its current master enable the check for it .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C master_alive_interval: .ft P .fi .UNINDENT .UNINDENT .sp If the loss of the connection is detected, the minion will temporarily remove the failed master from the list and try one of the other masters defined (again shuffled if that is enabled). .SS Testing the setup .sp At least two running masters are needed to test the failover setup. .sp Both masters should be running and the minion should be running on the command line in debug mode .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt\-minion \-l debug .ft P .fi .UNINDENT .UNINDENT .sp The minion will connect to the first master from its master list .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C [DEBUG ] Attempting to authenticate with the Salt Master at 172.16.0.10 [DEBUG ] Loaded minion key: /etc/salt/pki/minion/minion.pem [DEBUG ] salt.crypt.verify_signature: Loading public key [DEBUG ] salt.crypt.verify_signature: Verifying signature [DEBUG ] Successfully verified signature of master public key with verification public key master_sign.pub [INFO ] Received signed and verified master pubkey from master 172.16.0.10 [DEBUG ] Decrypting the current master AES key .ft P .fi .UNINDENT .UNINDENT .sp A test.version on the master the minion is currently connected to should be run to test connectivity. .sp If successful, that master should be turned off. A firewall\-rule denying the minions packets will also do the trick. .sp Depending on the configured conf_minion:\fImaster_alive_interval\fP, the minion will notice the loss of the connection and log it to its logfile. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C [INFO ] Connection to master 172.16.0.10 lost [INFO ] Trying to tune in to next master from master\-list .ft P .fi .UNINDENT .UNINDENT .sp The minion will then remove the current master from the list and try connecting to the next master .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C [INFO ] Removing possibly failed master 172.16.0.10 from list of masters [WARNING ] Master ip address changed from 172.16.0.10 to 172.16.0.11 [DEBUG ] Attempting to authenticate with the Salt Master at 172.16.0.11 .ft P .fi .UNINDENT .UNINDENT .sp If everything is configured correctly, the new masters public key will be verified successfully .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C [DEBUG ] Loaded minion key: /etc/salt/pki/minion/minion.pem [DEBUG ] salt.crypt.verify_signature: Loading public key [DEBUG ] salt.crypt.verify_signature: Verifying signature [DEBUG ] Successfully verified signature of master public key with verification public key master_sign.pub .ft P .fi .UNINDENT .UNINDENT .sp the authentication with the new master is successful .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C [INFO ] Received signed and verified master pubkey from master 172.16.0.11 [DEBUG ] Decrypting the current master AES key [DEBUG ] Loaded minion key: /etc/salt/pki/minion/minion.pem [INFO ] Authentication with master successful! .ft P .fi .UNINDENT .UNINDENT .sp and the minion can be pinged again from its new master. .SS Performance Tuning .sp With the setup described above, the master computes a signature for every auth\-request of a minion. With many minions and many auth\-requests, that can chew up quite a bit of CPU\-Power. .sp To avoid that, the master can use a pre\-created signature of its public\-key. The signature is saved as a base64 encoded string which the master reads once when starting and attaches only that string to auth\-replies. .sp Enabling this also gives paranoid users the possibility, to have the signing key\-pair on a different system than the actual salt\-master and create the public keys signature there. Probably on a system with more restrictive firewall rules, without internet access, less users, etc. .sp That signature can be created with .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt\-key \-\-gen\-signature .ft P .fi .UNINDENT .UNINDENT .sp This will create a default signature file in the master pki\-directory .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C /etc/salt/pki/master/master_pubkey_signature .ft P .fi .UNINDENT .UNINDENT .sp It is a simple text\-file with the binary\-signature converted to base64. .sp If no signing\-pair is present yet, this will auto\-create the signing pair and the signature file in one call .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt\-key \-\-gen\-signature \-\-auto\-create .ft P .fi .UNINDENT .UNINDENT .sp Telling the master to use the pre\-created signature is done with .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C master_use_pubkey_signature: True .ft P .fi .UNINDENT .UNINDENT .sp That requires the file \(aqmaster_pubkey_signature\(aq to be present in the masters pki\-directory with the correct signature. .sp If the signature file is named differently, its name can be set with .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C master_pubkey_signature: .ft P .fi .UNINDENT .UNINDENT .sp With many masters and many public\-keys (default and signing), it is advised to use the salt\-masters hostname for the signature\-files name. Signatures can be easily confused because they do not provide any information about the key the signature was created from. .sp Verifying that everything works is done the same way as above. .SS How the signing and verification works .sp The default key\-pair of the salt\-master is .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C /etc/salt/pki/master/master.pem /etc/salt/pki/master/master.pub .ft P .fi .UNINDENT .UNINDENT .sp To be able to create a signature of a message (in this case a public\-key), another key\-pair has to be added to the setup. Its default name is: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C master_sign.pem master_sign.pub .ft P .fi .UNINDENT .UNINDENT .sp The combination of the master.* and master_sign.* key\-pairs give the possibility of generating signatures. The signature of a given message is unique and can be verified, if the public\-key of the signing\-key\-pair is available to the recipient (the minion). .sp The signature of the masters public\-key in master.pub is computed with .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C master_sign.pem master.pub M2Crypto.EVP.sign_update() .ft P .fi .UNINDENT .UNINDENT .sp This results in a binary signature which is converted to base64 and attached to the auth\-reply send to the minion. .sp With the signing\-pairs public\-key available to the minion, the attached signature can be verified with .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C master_sign.pub master.pub M2Cryptos EVP.verify_update(). .ft P .fi .UNINDENT .UNINDENT .sp When running multiple masters, either the signing key\-pair has to be present on all of them, or the master_pubkey_signature has to be pre\-computed for each master individually (because they all have different public\-keys). .INDENT 0.0 .INDENT 3.5 DO NOT PUT THE SAME master.pub ON ALL MASTERS FOR EASE OF USE. .UNINDENT .UNINDENT .SS Packaging External Modules for Salt .SS External Modules Setuptools Entry\-Points Support .sp The salt loader was enhanced to look for external modules by looking at the \fIsalt.loader\fP entry\-point: .INDENT 0.0 .INDENT 3.5 \fI\%https://setuptools.readthedocs.io/en/latest/pkg_resources.html#entry\-points\fP .UNINDENT .UNINDENT .sp \fIpkg_resources\fP should be installed, which is normally included in setuptools. .INDENT 0.0 .INDENT 3.5 \fI\%https://setuptools.readthedocs.io/en/latest/pkg_resources.html\fP .UNINDENT .UNINDENT .sp The package which has custom engines, minion modules, outputters, etc, should require setuptools and should define the following entry points in its setup function: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C from setuptools import setup, find_packages setup( name=THE_NAME, version=THE_VERSION, description=THE_DESCRIPTION, author=THE_AUTHOR_NAME, author_email=THE_AUTHOR_EMAIL, url=" ... ", packages=find_packages(), entry_points=""" [salt.loader] engines_dirs = .:engines_dirs fileserver_dirs = .:fileserver_dirs pillar_dirs = .:pillar_dirs returner_dirs = .:returner_dirs roster_dirs = .:roster_dirs """, ) .ft P .fi .UNINDENT .UNINDENT .sp The above setup script example mentions a loader module. here\(aqs an example of how \fI/.py\fP it should look: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C # \-*\- coding: utf\-8 \-*\- # Import python libs import os PKG_DIR = os.path.abspath(os.path.dirname(__file__)) def engines_dirs(): """ yield one path per parent directory of where engines can be found """ yield os.path.join(PKG_DIR, "engines_1") yield os.path.join(PKG_DIR, "engines_2") def fileserver_dirs(): """ yield one path per parent directory of where fileserver modules can be found """ yield os.path.join(PKG_DIR, "fileserver") def pillar_dirs(): """ yield one path per parent directory of where external pillar modules can be found """ yield os.path.join(PKG_DIR, "pillar") def returner_dirs(): """ yield one path per parent directory of where returner modules can be found """ yield os.path.join(PKG_DIR, "returners") def roster_dirs(): """ yield one path per parent directory of where roster modules can be found """ yield os.path.join(PKG_DIR, "roster") .ft P .fi .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 dictionaries, lists, strings, and numbers. 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 four, 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 its 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 \fBjinja|yaml\fP renderer. The \fBjinja|yaml\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 \fBfile state\fP, as well as the \fI\%MooseFS example\fP below. .UNINDENT .UNINDENT .SS Getting to Know the Default \- jinja|yaml .sp The default renderer \- \fBjinja|yaml\fP, allows for use of the jinja templating system. A guide to the Jinja templating system can be found here: \fI\%https://jinja.palletsprojects.com/en/2.11.x/\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(): """ Install the django package """ return {"include": ["python"], "django": {"pkg": ["installed"]}} .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("python", delayed=True) state("django").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("python") 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.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 equivalent to the following python pseudo\-code: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C import salt.modules.file file.group_to_gid("some_group_that_exists") .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["network.hw_addr"]("eth0") .ft P .fi .UNINDENT .UNINDENT .sp To examine the possible arguments to each execution module function, one can examine the \fI\%module 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 States Tutorial, Part 5 \- Orchestration with Salt .sp This was moved to Orchestrate Runner\&. .SS Syslog\-ng usage .SS Overview .sp Syslog_ng state module is for generating syslog\-ng configurations. You can do the following things: .INDENT 0.0 .IP \(bu 2 generate syslog\-ng configuration from YAML, .IP \(bu 2 use non\-YAML configuration, .IP \(bu 2 start, stop or reload syslog\-ng. .UNINDENT .sp There is also an execution module, which can check the syntax of the configuration, get the version and other information about syslog\-ng. .SS Configuration .sp Users can create syslog\-ng configuration statements with the \fBsyslog_ng.config\fP function. It requires a \fIname\fP and a \fIconfig\fP parameter. The \fIname\fP parameter determines the name of the generated statement and the \fIconfig\fP parameter holds a parsed YAML structure. .sp A statement can be declared in the following forms (both are equivalent): .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C source.s_localhost: syslog_ng.config: \- config: \- tcp: \- ip: "127.0.0.1" \- port: 1233 .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C s_localhost: syslog_ng.config: \- config: source: \- tcp: \- ip: "127.0.0.1" \- port: 1233 .ft P .fi .UNINDENT .UNINDENT .sp The first one is called short form, because it needs less typing. Users can use lists and dictionaries to specify their configuration. The format is quite self describing and there are more examples [at the end](#examples) of this document. .SS Quotation .INDENT 0.0 .TP .B The quotation can be tricky sometimes but here are some rules to follow: .INDENT 7.0 .IP \(bu 2 when a string meant to be \fB"string"\fP in the generated configuration, it should be like \fB\(aq"string"\(aq\fP in the YAML document .IP \(bu 2 similarly, users should write \fB"\(aqstring\(aq"\fP to get \fB\(aqstring\(aq\fP in the generated configuration .UNINDENT .UNINDENT .SS Full example .sp The following configuration is an example, how a complete syslog\-ng configuration looks like: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C # Set the location of the configuration file set_location: module.run: \- name: syslog_ng.set_config_file \- m_name: "/home/tibi/install/syslog\-ng/etc/syslog\-ng.conf" # The syslog\-ng and syslog\-ng\-ctl binaries are here. You needn\(aqt use # this method if these binaries can be found in a directory in your PATH. set_bin_path: module.run: \- name: syslog_ng.set_binary_path \- m_name: "/home/tibi/install/syslog\-ng/sbin" # Writes the first lines into the config file, also erases its previous # content write_version: module.run: \- name: syslog_ng.write_version \- m_name: "3.6" # There is a shorter form to set the above variables set_variables: module.run: \- name: syslog_ng.set_parameters \- version: "3.6" \- binary_path: "/home/tibi/install/syslog\-ng/sbin" \- config_file: "/home/tibi/install/syslog\-ng/etc/syslog\-ng.conf" # Some global options options.global_options: syslog_ng.config: \- config: \- time_reap: 30 \- mark_freq: 10 \- keep_hostname: "yes" source.s_localhost: syslog_ng.config: \- config: \- tcp: \- ip: "127.0.0.1" \- port: 1233 destination.d_log_server: syslog_ng.config: \- config: \- tcp: \- "127.0.0.1" \- port: 1234 log.l_log_to_central_server: syslog_ng.config: \- config: \- source: s_localhost \- destination: d_log_server some_comment: module.run: \- name: syslog_ng.write_config \- config: | # Multi line # comment # Another mode to use comments or existing configuration snippets config.other_comment_form: syslog_ng.config: \- config: | # Multi line # comment .ft P .fi .UNINDENT .UNINDENT .sp The \fBsyslog_ng.reloaded\fP function can generate syslog\-ng configuration from YAML. If the statement (source, destination, parser, etc.) has a name, this function uses the id as the name, otherwise (log statement) its purpose is like a mandatory comment. .sp After execution this example the syslog_ng state will generate this file: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C #Generated by Salt on 2014\-08\-18 00:11:11 @version: 3.6 options { time_reap( 30 ); mark_freq( 10 ); keep_hostname( yes ); }; source s_localhost { tcp( ip( 127.0.0.1 ), port( 1233 ) ); }; destination d_log_server { tcp( 127.0.0.1, port( 1234 ) ); }; log { source( s_localhost ); destination( d_log_server ); }; # Multi line # comment # Multi line # comment .ft P .fi .UNINDENT .UNINDENT .sp Users can include arbitrary texts in the generated configuration with using the \fBconfig\fP statement (see the example above). .SS Syslog_ng module functions .sp You can use \fBsyslog_ng.set_binary_path\fP to set the directory which contains the syslog\-ng and syslog\-ng\-ctl binaries. If this directory is in your PATH, you don\(aqt need to use this function. There is also a \fBsyslog_ng.set_config_file\fP function to set the location of the configuration file. .SS Examples .SS Simple source .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C source s_tail { file( "/var/log/apache/access.log", follow_freq(1), flags(no\-parse, validate\-utf8) ); }; .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C s_tail: # Salt will call the source function of syslog_ng module syslog_ng.config: \- config: source: \- file: \- file: \(aq\(aq"/var/log/apache/access.log"\(aq\(aq \- follow_freq : 1 \- flags: \- no\-parse \- validate\-utf8 .ft P .fi .UNINDENT .UNINDENT .sp OR .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C s_tail: syslog_ng.config: \- config: source: \- file: \- \(aq\(aq"/var/log/apache/access.log"\(aq\(aq \- follow_freq : 1 \- flags: \- no\-parse \- validate\-utf8 .ft P .fi .UNINDENT .UNINDENT .sp OR .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C source.s_tail: syslog_ng.config: \- config: \- file: \- \(aq\(aq"/var/log/apache/access.log"\(aq\(aq \- follow_freq : 1 \- flags: \- no\-parse \- validate\-utf8 .ft P .fi .UNINDENT .UNINDENT .SS Complex source .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C source s_gsoc2014 { tcp( ip("0.0.0.0"), port(1234), flags(no\-parse) ); }; .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C s_gsoc2014: syslog_ng.config: \- config: source: \- tcp: \- ip: 0.0.0.0 \- port: 1234 \- flags: no\-parse .ft P .fi .UNINDENT .UNINDENT .SS Filter .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C filter f_json { match( "@json:" ); }; .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C f_json: syslog_ng.config: \- config: filter: \- match: \- \(aq\(aq"@json:"\(aq\(aq .ft P .fi .UNINDENT .UNINDENT .SS Template .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C template t_demo_filetemplate { template( "$ISODATE $HOST $MSG " ); template_escape( no ); }; .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C t_demo_filetemplate: syslog_ng.config: \-config: template: \- template: \- \(aq"$ISODATE $HOST $MSG\en"\(aq \- template_escape: \- "no" .ft P .fi .UNINDENT .UNINDENT .SS Rewrite .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C rewrite r_set_message_to_MESSAGE { set( "${.json.message}", value("$MESSAGE") ); }; .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C r_set_message_to_MESSAGE: syslog_ng.config: \- config: rewrite: \- set: \- \(aq"${.json.message}"\(aq \- value : \(aq"$MESSAGE"\(aq .ft P .fi .UNINDENT .UNINDENT .SS Global options .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C options { time_reap(30); mark_freq(10); keep_hostname(yes); }; .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C global_options: syslog_ng.config: \- config: options: \- time_reap: 30 \- mark_freq: 10 \- keep_hostname: "yes" .ft P .fi .UNINDENT .UNINDENT .SS Log .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C log { source(s_gsoc2014); junction { channel { filter(f_json); parser(p_json); rewrite(r_set_json_tag); rewrite(r_set_message_to_MESSAGE); destination { file( "/tmp/json\-input.log", template(t_gsoc2014) ); }; flags(final); }; channel { filter(f_not_json); parser { syslog\-parser( ); }; rewrite(r_set_syslog_tag); flags(final); }; }; destination { file( "/tmp/all.log", template(t_gsoc2014) ); }; }; .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C l_gsoc2014: syslog_ng.config: \- config: log: \- source: s_gsoc2014 \- junction: \- channel: \- filter: f_json \- parser: p_json \- rewrite: r_set_json_tag \- rewrite: r_set_message_to_MESSAGE \- destination: \- file: \- \(aq"/tmp/json\-input.log"\(aq \- template: t_gsoc2014 \- flags: final \- channel: \- filter: f_not_json \- parser: \- syslog\-parser: [] \- rewrite: r_set_syslog_tag \- flags: final \- destination: \- file: \- "/tmp/all.log" \- template: t_gsoc2014 .ft P .fi .UNINDENT .UNINDENT .SS Salt in 10 Minutes .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 Welcome to SaltStack! I am excited that you are interested in Salt and starting down the path to better infrastructure management. I developed (and am continuing to develop) Salt with the goal of making the best software available to manage computers of almost any kind. I hope you enjoy working with Salt and that the software can solve your real world needs! .INDENT 0.0 .IP \(bu 2 Thomas S Hatch .IP \(bu 2 Salt creator and Chief Developer .IP \(bu 2 CTO of SaltStack, Inc. .UNINDENT .UNINDENT .UNINDENT .SS Getting Started .SS What is Salt? .sp Salt is a different approach to infrastructure management, founded on the idea that high\-speed communication with large numbers of systems can open up new capabilities. This approach makes Salt a powerful multitasking system that can solve many specific problems in an infrastructure. .sp The backbone of Salt is the remote execution engine, which creates a high\-speed, secure and bi\-directional communication net for groups of systems. On top of this communication system, Salt provides an extremely fast, flexible, and easy\-to\-use configuration management system called \fBSalt States\fP\&. .SS Installing Salt .sp SaltStack has been made to be very easy to install and get started. The installation documents contain instructions for all supported platforms. .SS Starting Salt .sp Salt functions on a master/minion topology. A master server acts as a central control bus for the clients, which are called \fBminions\fP\&. The minions connect back to the master. .SS Setting Up the Salt Master .sp Turning on the Salt Master is easy \-\- just turn it on! The default configuration is suitable for the vast majority of installations. The Salt Master can be controlled by the local Linux/Unix service manager: .sp On Systemd based platforms (newer Debian, openSUSE, Fedora): .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C systemctl start salt\-master .ft P .fi .UNINDENT .UNINDENT .sp On Upstart based systems (Ubuntu, older Fedora/RHEL): .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C service salt\-master start .ft P .fi .UNINDENT .UNINDENT .sp On SysV Init systems (Gentoo, older Debian etc.): .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C /etc/init.d/salt\-master start .ft P .fi .UNINDENT .UNINDENT .sp Alternatively, the Master can be started directly on the command\-line: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt\-master \-d .ft P .fi .UNINDENT .UNINDENT .sp The Salt Master can also be started in the foreground in debug mode, thus greatly increasing the command output: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt\-master \-l debug .ft P .fi .UNINDENT .UNINDENT .sp The Salt Master needs to bind to two TCP network ports on the system. These ports are \fB4505\fP and \fB4506\fP\&. For more in depth information on firewalling these ports, the firewall tutorial is available here\&. .SS Finding the Salt Master .sp When a minion starts, by default it searches for a system that resolves to the \fBsalt\fP hostname on the network. If found, the minion initiates the handshake and key authentication process with the Salt master. This means that the easiest configuration approach is to set internal DNS to resolve the name \fBsalt\fP back to the Salt Master IP. .sp Otherwise, the minion configuration file will need to be edited so that the configuration option \fBmaster\fP points to the DNS name or the IP of the Salt Master: .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 The default location of the configuration files is \fB/etc/salt\fP\&. Most platforms adhere to this convention, but platforms such as FreeBSD and Microsoft Windows place this file in different locations. .UNINDENT .UNINDENT .sp \fB/etc/salt/minion:\fP .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C master: saltmaster.example.com .ft P .fi .UNINDENT .UNINDENT .SS Setting up a Salt Minion .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 The Salt Minion can operate with or without a Salt Master. This walk\-through assumes that the minion will be connected to the master, for information on how to run a master\-less minion please see the master\-less quick\-start guide: .sp Masterless Minion Quickstart .UNINDENT .UNINDENT .sp Now that the master can be found, start the minion in the same way as the master; with the platform init system or via the command line directly: .sp As a daemon: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt\-minion \-d .ft P .fi .UNINDENT .UNINDENT .sp In the foreground in debug mode: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt\-minion \-l debug .ft P .fi .UNINDENT .UNINDENT .sp When the minion is started, it will generate an \fBid\fP value, unless it has been generated on a previous run and cached (in \fB/etc/salt/minion_id\fP by default). This is the name by which the minion will attempt to authenticate to the master. The following steps are attempted, in order to try to find a value that is not \fBlocalhost\fP: .INDENT 0.0 .IP 1. 3 The Python function \fBsocket.getfqdn()\fP is run .IP 2. 3 \fB/etc/hostname\fP is checked (non\-Windows only) .IP 3. 3 \fB/etc/hosts\fP (\fB%WINDIR%\esystem32\edrivers\eetc\ehosts\fP on Windows hosts) is checked for hostnames that map to anything within \fB127.0.0.0/8\fP\&. .UNINDENT .sp If none of the above are able to produce an id which is not \fBlocalhost\fP, then a sorted list of IP addresses on the minion (excluding any within \fB127.0.0.0/8\fP) is inspected. The first publicly\-routable IP address is used, if there is one. Otherwise, the first privately\-routable IP address is used. .sp If all else fails, then \fBlocalhost\fP is used as a fallback. .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 Overriding the \fBid\fP .sp The minion id can be manually specified using the \fBid\fP parameter in the minion config file. If this configuration value is specified, it will override all other sources for the \fBid\fP\&. .UNINDENT .UNINDENT .sp Now that the minion is started, it will generate cryptographic keys and attempt to connect to the master. The next step is to venture back to the master server and accept the new minion\(aqs public key. .SS Using salt\-key .sp Salt authenticates minions using public\-key encryption and authentication. For a minion to start accepting commands from the master, the minion keys need to be accepted by the master. .sp The \fBsalt\-key\fP command is used to manage all of the keys on the master. To list the keys that are on the master: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt\-key \-L .ft P .fi .UNINDENT .UNINDENT .sp The keys that have been rejected, accepted, and pending acceptance are listed. The easiest way to accept the minion key is to accept all pending keys: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt\-key \-A .ft P .fi .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 Keys should be verified! Print the master key fingerprint by running \fBsalt\-key \-F master\fP on the Salt master. Copy the \fBmaster.pub\fP fingerprint from the Local Keys section, and then set this value as the \fBmaster_finger\fP in the minion configuration file. Restart the Salt minion. .sp On the master, run \fBsalt\-key \-f minion\-id\fP to print the fingerprint of the minion\(aqs public key that was received by the master. On the minion, run \fBsalt\-call key.finger \-\-local\fP to print the fingerprint of the minion key. .sp On the master: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C # salt\-key \-f foo.domain.com Unaccepted Keys: foo.domain.com: 39:f9:e4:8a:aa:74:8d:52:1a:ec:92:03:82:09:c8:f9 .ft P .fi .UNINDENT .UNINDENT .sp On the minion: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C # salt\-call key.finger \-\-local local: 39:f9:e4:8a:aa:74:8d:52:1a:ec:92:03:82:09:c8:f9 .ft P .fi .UNINDENT .UNINDENT .sp If they match, approve the key with \fBsalt\-key \-a foo.domain.com\fP\&. .UNINDENT .UNINDENT .SS Sending the First Commands .sp Now that the minion is connected to the master and authenticated, the master can start to command the minion. .sp Salt commands allow for a vast set of functions to be executed and for specific minions and groups of minions to be targeted for execution. .sp The \fBsalt\fP command is comprised of command options, target specification, the function to execute, and arguments to the function. .sp A simple command to start with looks like this: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq test.version .ft P .fi .UNINDENT .UNINDENT .sp The \fB*\fP is the target, which specifies all minions. .sp \fBtest.version\fP tells the minion to run the \fBtest.version\fP function. .sp In the case of \fBtest.version\fP, \fBtest\fP refers to a execution module\&. \fBversion\fP refers to the \fBversion\fP function contained in the aforementioned \fBtest\fP module. .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 Execution modules are the workhorses of Salt. They do the work on the system to perform various tasks, such as manipulating files and restarting services. .UNINDENT .UNINDENT .sp The result of running this command will be the master instructing all of the minions to execute \fBtest.version\fP in parallel and return the result. Using \fBtest.version\fP is a good way of confirming that a minion is connected, and reaffirm to the user the salt version(s) they have installed on the minions. .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 Each minion registers itself with a unique minion ID. This ID defaults to the minion\(aqs hostname, but can be explicitly defined in the minion config as well by using the \fBid\fP parameter. .UNINDENT .UNINDENT .sp Of course, there are hundreds of other modules that can be called just as \fBtest.version\fP can. For example, the following would return disk usage on all targeted minions: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq disk.usage .ft P .fi .UNINDENT .UNINDENT .SS Getting to Know the Functions .sp Salt comes with a vast library of functions available for execution, and Salt functions are self\-documenting. To see what functions are available on the minions execute the \fBsys.doc\fP function: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq sys.doc .ft P .fi .UNINDENT .UNINDENT .sp This will display a very large list of available functions and documentation on them. .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 Module documentation is also available on the web\&. .UNINDENT .UNINDENT .sp These functions cover everything from shelling out to package management to manipulating database servers. They comprise a powerful system management API which is the backbone to Salt configuration management and many other aspects of Salt. .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 Salt comes with many plugin systems. The functions that are available via the \fBsalt\fP command are called Execution Modules\&. .UNINDENT .UNINDENT .SS Helpful Functions to Know .sp The \fBcmd\fP module contains functions to shell out on minions, such as \fBcmd.run\fP and \fBcmd.run_all\fP: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq cmd.run \(aqls \-l /etc\(aq .ft P .fi .UNINDENT .UNINDENT .sp The \fBpkg\fP functions automatically map local system package managers to the same salt functions. This means that \fBpkg.install\fP will install packages via \fByum\fP on Red Hat based systems, \fBapt\fP on Debian systems, etc.: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.install vim .ft P .fi .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 Some custom Linux spins and derivatives of other distributions are not properly detected by Salt. If the above command returns an error message saying that \fBpkg.install\fP is not available, then you may need to override the pkg provider. This process is explained here\&. .UNINDENT .UNINDENT .sp The \fBnetwork.interfaces\fP function will list all interfaces on a minion, along with their IP addresses, netmasks, MAC addresses, etc: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq network.interfaces .ft P .fi .UNINDENT .UNINDENT .SS Changing the Output Format .sp The default output format used for most Salt commands is called the \fBnested\fP outputter, but there are several other outputters that can be used to change the way the output is displayed. For instance, the \fBpprint\fP outputter can be used to display the return data using Python\(aqs \fBpprint\fP module: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C root@saltmaster:~# salt myminion grains.item pythonpath \-\-out=pprint {\(aqmyminion\(aq: {\(aqpythonpath\(aq: [\(aq/usr/lib64/python2.7\(aq, \(aq/usr/lib/python2.7/plat\-linux2\(aq, \(aq/usr/lib64/python2.7/lib\-tk\(aq, \(aq/usr/lib/python2.7/lib\-tk\(aq, \(aq/usr/lib/python2.7/site\-packages\(aq, \(aq/usr/lib/python2.7/site\-packages/gst\-0.10\(aq, \(aq/usr/lib/python2.7/site\-packages/gtk\-2.0\(aq]}} .ft P .fi .UNINDENT .UNINDENT .sp The full list of Salt outputters, as well as example output, can be found here\&. .SS \fBsalt\-call\fP .sp The examples so far have described running commands from the Master using the \fBsalt\fP command, but when troubleshooting it can be more beneficial to login to the minion directly and use \fBsalt\-call\fP\&. .sp Doing so allows you to see the minion log messages specific to the command you are running (which are \fInot\fP part of the return data you see when running the command from the Master using \fBsalt\fP), making it unnecessary to tail the minion log. More information on \fBsalt\-call\fP and how to use it can be found here\&. .SS Grains .sp Salt uses a system called Grains to build up static data about minions. This data includes information about the operating system that is running, CPU architecture and much more. The grains system is used throughout Salt to deliver platform data to many components and to users. .sp Grains can also be statically set, this makes it easy to assign values to minions for grouping and managing. .sp A common practice is to assign grains to minions to specify what the role or roles a minion might be. These static grains can be set in the minion configuration file or via the \fBgrains.setval\fP function. .SS Targeting .sp Salt allows for minions to be targeted based on a wide range of criteria. The default targeting system uses globular expressions to match minions, hence if there are minions named \fBlarry1\fP, \fBlarry2\fP, \fBcurly1\fP, and \fBcurly2\fP, a glob of \fBlarry*\fP will match \fBlarry1\fP and \fBlarry2\fP, and a glob of \fB*1\fP will match \fBlarry1\fP and \fBcurly1\fP\&. .sp Many other targeting systems can be used other than globs, these systems include: .INDENT 0.0 .TP .B Regular Expressions Target using PCRE\-compliant regular expressions .TP .B Grains Target based on grains data: Targeting with Grains .TP .B Pillar Target based on pillar data: Targeting with Pillar .TP .B IP Target based on IP address/subnet/range .TP .B Compound Create logic to target based on multiple targets: Targeting with Compound .TP .B Nodegroup Target with nodegroups: Targeting with Nodegroup .UNINDENT .sp The concepts of targets are used on the command line with Salt, but also function in many other areas as well, including the state system and the systems used for ACLs and user permissions. .SS Passing in Arguments .sp Many of the functions available accept arguments which can be passed in on the command line: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.install vim .ft P .fi .UNINDENT .UNINDENT .sp This example passes the argument \fBvim\fP to the pkg.install function. Since many functions can accept more complex input than just a string, the arguments are parsed through YAML, allowing for more complex data to be sent on the command line: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq test.echo \(aqfoo: bar\(aq .ft P .fi .UNINDENT .UNINDENT .sp In this case Salt translates the string \(aqfoo: bar\(aq into the dictionary "{\(aqfoo\(aq: \(aqbar\(aq}" .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 Any line that contains a newline will not be parsed by YAML. .UNINDENT .UNINDENT .SS Salt States .sp Now that the basics are covered the time has come to evaluate \fBStates\fP\&. Salt \fBStates\fP, or the \fBState System\fP is the component of Salt made for configuration management. .sp The state system is already available with a basic Salt setup, no additional configuration is required. States can be set up immediately. .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 Before diving into the state system, a brief overview of how states are constructed will make many of the concepts clearer. Salt states are based on data modeling and build on a low level data structure that is used to execute each state function. Then more logical layers are built on top of each other. .sp The high layers of the state system which this tutorial will cover consists of everything that needs to be known to use states, the two high layers covered here are the \fIsls\fP layer and the highest layer \fIhighstate\fP\&. .sp Understanding the layers of data management in the State System will help with understanding states, but they never need to be used. Just as understanding how a compiler functions assists when learning a programming language, understanding what is going on under the hood of a configuration management system will also prove to be a valuable asset. .UNINDENT .UNINDENT .SS The First SLS Formula .sp The state system is built on SLS (SaLt State) formulas. These formulas are built out in files on Salt\(aqs file server. To make a very basic SLS formula open up a file under /srv/salt named vim.sls. The following state ensures that vim is installed on a system to which that state has been applied. .sp \fB/srv/salt/vim.sls:\fP .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C vim: pkg.installed .ft P .fi .UNINDENT .UNINDENT .sp Now install vim on the minions by calling the SLS directly: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq state.apply vim .ft P .fi .UNINDENT .UNINDENT .sp This command will invoke the state system and run the \fBvim\fP SLS. .sp Now, to beef up the vim SLS formula, a \fBvimrc\fP can be added: .sp \fB/srv/salt/vim.sls:\fP .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C vim: pkg.installed: [] /etc/vimrc: file.managed: \- source: salt://vimrc \- mode: 644 \- user: root \- group: root .ft P .fi .UNINDENT .UNINDENT .sp Now the desired \fBvimrc\fP needs to be copied into the Salt file server to \fB/srv/salt/vimrc\fP\&. In Salt, everything is a file, so no path redirection needs to be accounted for. The \fBvimrc\fP file is placed right next to the \fBvim.sls\fP file. The same command as above can be executed to all the vim SLS formulas and now include managing the file. .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 Salt does not need to be restarted/reloaded or have the master manipulated in any way when changing SLS formulas. They are instantly available. .UNINDENT .UNINDENT .SS Adding Some Depth .sp Obviously maintaining SLS formulas right in a single directory at the root of the file server will not scale out to reasonably sized deployments. This is why more depth is required. Start by making an nginx formula a better way, make an nginx subdirectory and add an init.sls file: .sp \fB/srv/salt/nginx/init.sls:\fP .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C nginx: pkg.installed: [] service.running: \- require: \- pkg: nginx .ft P .fi .UNINDENT .UNINDENT .sp A few concepts are introduced in this SLS formula. .sp First is the service statement which ensures that the \fBnginx\fP service is running. .sp Of course, the nginx service can\(aqt be started unless the package is installed \-\- hence the \fBrequire\fP statement which sets up a dependency between the two. .sp The \fBrequire\fP statement makes sure that the required component is executed before and that it results in success. .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 The \fIrequire\fP option belongs to a family of options called \fIrequisites\fP\&. Requisites are a powerful component of Salt States, for more information on how requisites work and what is available see: Requisites .sp Also evaluation ordering is available in Salt as well: Ordering States .UNINDENT .UNINDENT .sp This new sls formula has a special name \-\- \fBinit.sls\fP\&. When an SLS formula is named \fBinit.sls\fP it inherits the name of the directory path that contains it. This formula can be referenced via the following command: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq state.apply nginx .ft P .fi .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 \fBstate.apply\fP is just another remote execution function, just like \fBtest.version\fP or \fBdisk.usage\fP\&. It simply takes the name of an SLS file as an argument. .UNINDENT .UNINDENT .sp Now that subdirectories can be used, the \fBvim.sls\fP formula can be cleaned up. To make things more flexible, move the \fBvim.sls\fP and vimrc into a new subdirectory called \fBedit\fP and change the \fBvim.sls\fP file to reflect the change: .sp \fB/srv/salt/edit/vim.sls:\fP .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C vim: pkg.installed /etc/vimrc: file.managed: \- source: salt://edit/vimrc \- mode: 644 \- user: root \- group: root .ft P .fi .UNINDENT .UNINDENT .sp Only the source path to the vimrc file has changed. Now the formula is referenced as \fBedit.vim\fP because it resides in the edit subdirectory. Now the edit subdirectory can contain formulas for emacs, nano, joe or any other editor that may need to be deployed. .SS Next Reading .sp Two walk\-throughs are specifically recommended at this point. First, a deeper run through States, followed by an explanation of Pillar. .INDENT 0.0 .IP 1. 3 Starting States .IP 2. 3 Pillar Walkthrough .UNINDENT .sp An understanding of Pillar is extremely helpful in using States. .SS Getting Deeper Into States .sp Two more in\-depth States tutorials exist, which delve much more deeply into States functionality. .INDENT 0.0 .IP 1. 3 How Do I Use Salt States?, covers much more to get off the ground with States. .IP 2. 3 The States Tutorial also provides a fantastic introduction. .UNINDENT .sp These tutorials include much more in\-depth information including templating SLS formulas etc. .SS So Much More! .sp This concludes the initial Salt walk\-through, but there are many more things still to learn! These documents will cover important core aspects of Salt: .INDENT 0.0 .IP \(bu 2 Pillar .IP \(bu 2 Job Management .UNINDENT .sp A few more tutorials are also available: .INDENT 0.0 .IP \(bu 2 Remote Execution Tutorial .IP \(bu 2 Standalone Minion .UNINDENT .sp This still is only scratching the surface, many components such as the reactor and event systems, extending Salt, modular components and more are not covered here. For an overview of all Salt features and documentation, look at the Table of Contents\&. .SS Salt\(aqs Test Suite: An Introduction .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 This tutorial makes a couple of assumptions. The first assumption is that you have a basic knowledge of Salt. To get up to speed, check out the Salt Walkthrough\&. .sp The second assumption is that your Salt development environment is already configured and that you have a basic understanding of contributing to the Salt codebase. If you\(aqre unfamiliar with either of these topics, please refer to the Installing Salt for Development and the Contributing pages, respectively. .UNINDENT .UNINDENT .sp Salt comes with a powerful integration and unit test suite. The test suite allows for the fully automated run of integration and/or unit tests from a single interface. .sp Salt\(aqs test suite is located under the \fBtests\fP directory in the root of Salt\(aqs code base and is divided into two main types of tests: \fI\%unit tests and integration tests\fP\&. The \fBunit\fP and \fBintegration\fP sub\-test\-suites are located in the \fBtests\fP directory, which is where the majority of Salt\(aqs test cases are housed. .SS Getting Set Up For Tests .sp First of all you will need to ensure you install \fBnox\fP\&. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C pip install nox .ft P .fi .UNINDENT .UNINDENT .SS Test Directory Structure .sp As noted in the introduction to this tutorial, Salt\(aqs test suite is located in the \fBtests\fP directory in the root of Salt\(aqs code base. From there, the tests are divided into two groups \fBintegration\fP and \fBunit\fP\&. Within each of these directories, the directory structure roughly mirrors the directory structure of Salt\(aqs own codebase. For example, the files inside \fBtests/integration/modules\fP contains tests for the files located within \fBsalt/modules\fP\&. .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 \fBtests/integration\fP and \fBtests/unit\fP are the only directories discussed in this tutorial. With the exception of the \fBtests/runtests.py\fP file, which is used below in the \fI\%Running the Test Suite\fP section, the other directories and files located in \fBtests\fP are outside the scope of this tutorial. .UNINDENT .UNINDENT .SS Integration vs. Unit .sp Given that Salt\(aqs test suite contains two powerful, though very different, testing approaches, when should you write integration tests and when should you write unit tests? .sp Integration tests use Salt masters, minions, and a syndic to test salt functionality directly and focus on testing the interaction of these components. Salt\(aqs integration test runner includes functionality to run Salt execution modules, runners, states, shell commands, salt\-ssh commands, salt\-api commands, and more. This provides a tremendous ability to use Salt to test itself and makes writing such tests a breeze. Integration tests are the preferred method of testing Salt functionality when possible. .sp Unit tests do not spin up any Salt daemons, but instead find their value in testing singular implementations of individual functions. Instead of testing against specific interactions, unit tests should be used to test a function\(aqs logic. Unit tests should be used to test a function\(aqs exit point(s) such as any \fBreturn\fP or \fBraises\fP statements. .sp Unit tests are also useful in cases where writing an integration test might not be possible. While the integration test suite is extremely powerful, unfortunately at this time, it does not cover all functional areas of Salt\(aqs ecosystem. For example, at the time of this writing, there is not a way to write integration tests for Proxy Minions. Since the test runner will need to be adjusted to account for Proxy Minion processes, unit tests can still provide some testing support in the interim by testing the logic contained inside Proxy Minion functions. .SS Running the Test Suite .sp Once all of the \fI\%requirements\fP are installed, the \fBnox\fP command is used to instantiate Salt\(aqs test suite: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C nox \-e \(aqpytest\-zeromq\-3(coverage=False)\(aq .ft P .fi .UNINDENT .UNINDENT .sp The command above, if executed without any options, will run the entire suite of integration and unit tests. Some tests require certain flags to run, such as destructive tests. If these flags are not included, then the test suite will only perform the tests that don\(aqt require special attention. .sp At the end of the test run, you will see a summary output of the tests that passed, failed, or were skipped. .sp You can pass any pytest options after the nox command like so: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C nox \-e \(aqpytest\-zeromq\-3(coverage=False)\(aq \-\- tests/unit/modules/test_ps.py .ft P .fi .UNINDENT .UNINDENT .sp The above command will run the \fBtest_ps.py\fP test with the zeromq transport, python3, and pytest. The option after \fB\-\-\fP can include any pytest options. .SS Running Integration Tests .sp Salt\(aqs set of integration tests use Salt to test itself. The integration portion of the test suite includes some built\-in Salt daemons that will spin up in preparation of the test run. This list of Salt daemon processes includes: .INDENT 0.0 .IP \(bu 2 2 Salt Masters .IP \(bu 2 2 Salt Minions .IP \(bu 2 1 Salt Syndic .UNINDENT .sp These various daemons are used to execute Salt commands and functionality within the test suite, allowing you to write tests to assert against expected or unexpected behaviors. .sp A simple example of a test utilizing a typical master/minion execution module command is the test for the \fBtest_ping\fP function in the \fBtests/integration/modules/test_test.py\fP file: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C def test_ping(self): """ test.ping """ self.assertTrue(self.run_function("test.ping")) .ft P .fi .UNINDENT .UNINDENT .sp The test above is a very simple example where the \fBtest.ping\fP function is executed by Salt\(aqs test suite runner and is asserting that the minion returned with a \fBTrue\fP response. .SS Test Selection Options .sp If you want to run only a subset of tests, this is easily done with pytest. You only need to point the test runner to the directory. For example if you want to run all integration module tests: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C nox \-e \(aqpytest\-zeromq\-3(coverage=False)\(aq \-\- tests/integration/modules/ .ft P .fi .UNINDENT .UNINDENT .SS Running Unit Tests .sp If you want to run only the unit tests, you can just pass the unit test directory as an option to the test runner. .sp The unit tests do not spin up any Salt testing daemons as the integration tests do and execute very quickly compared to the integration tests. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C nox \-e \(aqpytest\-zeromq\-3(coverage=False)\(aq \-\- tests/unit/ .ft P .fi .UNINDENT .UNINDENT .SS Running Specific Tests .sp There are times when a specific test file, test class, or even a single, individual test need to be executed, such as when writing new tests. In these situations, you should use the \fI\%pytest syntax\fP to select the specific tests. .sp For running a single test file, such as the pillar module test file in the integration test directory, you must provide the file path. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C nox \-e \(aqpytest\-zeromq\-3(coverage=False)\(aq \-\- tests/integration/modules/test_pillar.py .ft P .fi .UNINDENT .UNINDENT .sp Some test files contain only one test class while other test files contain multiple test classes. To run a specific test class within the file, append the name of the test class to the end of the file path: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C nox \-e \(aqpytest\-zeromq\-3(coverage=False)\(aq \-\- tests/integration/modules/test_pillar.py::PillarModuleTest .ft P .fi .UNINDENT .UNINDENT .sp To run a single test within a file, append both the name of the test class the individual test belongs to, as well as the name of the test itself: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C nox \-e \(aqpytest\-zeromq\-3(coverage=False)\(aq \-\- tests/integration/modules/test_pillar.py::PillarModuleTest::test_data .ft P .fi .UNINDENT .UNINDENT .sp The following command is an example of how to execute a single test found in the \fBtests/unit/modules/test_cp.py\fP file: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C nox \-e \(aqpytest\-zeromq\-3(coverage=False)\(aq \-\- tests/unit/modules/test_cp.py::CpTestCase::test_get_file_not_found .ft P .fi .UNINDENT .UNINDENT .SS Writing Tests for Salt .sp Once you\(aqre comfortable running tests, you can now start writing them! Be sure to review the \fI\%Integration vs. Unit\fP section of this tutorial to determine what type of test makes the most sense for the code you\(aqre testing. .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 There are many decorators, naming conventions, and code specifications required for Salt test files. We will not be covering all of the these specifics in this tutorial. Please refer to the testing documentation links listed below in the \fI\%Additional Testing Documentation\fP section to learn more about these requirements. .sp In the following sections, the test examples assume the "new" test is added to a test file that is already present and regularly running in the test suite and is written with the correct requirements. .UNINDENT .UNINDENT .SS Writing Integration Tests .sp Since integration tests validate against a running environment, as explained in the \fI\%Running Integration Tests\fP section of this tutorial, integration tests are very easy to write and are generally the preferred method of writing Salt tests. .sp The following integration test is an example taken from the \fBtest.py\fP file in the \fBtests/integration/modules\fP directory. This test uses the \fBrun_function\fP method to test the functionality of a traditional execution module command. .sp The \fBrun_function\fP method uses the integration test daemons to execute a \fBmodule.function\fP command as you would with Salt. The minion runs the function and returns. The test also uses \fI\%Python\(aqs Assert Functions\fP to test that the minion\(aqs return is expected. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C def test_ping(self): """ test.ping """ self.assertTrue(self.run_function("test.ping")) .ft P .fi .UNINDENT .UNINDENT .sp Args can be passed in to the \fBrun_function\fP method as well: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C def test_echo(self): """ test.echo """ self.assertEqual(self.run_function("test.echo", ["text"]), "text") .ft P .fi .UNINDENT .UNINDENT .sp The next example is taken from the \fBtests/integration/modules/test_aliases.py\fP file and demonstrates how to pass kwargs to the \fBrun_function\fP call. Also note that this test uses another salt function to ensure the correct data is present (via the \fBaliases.set_target\fP call) before attempting to assert what the \fBaliases.get_target\fP call should return. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C def test_set_target(self): """ aliases.set_target and aliases.get_target """ set_ret = self.run_function("aliases.set_target", alias="fred", target="bob") self.assertTrue(set_ret) tgt_ret = self.run_function("aliases.get_target", alias="fred") self.assertEqual(tgt_ret, "bob") .ft P .fi .UNINDENT .UNINDENT .sp Using multiple Salt commands in this manner provides two useful benefits. The first is that it provides some additional coverage for the \fBaliases.set_target\fP function. The second benefit is the call to \fBaliases.get_target\fP is not dependent on the presence of any aliases set outside of this test. Tests should not be dependent on the previous execution, success, or failure of other tests. They should be isolated from other tests as much as possible. .sp While it might be tempting to build out a test file where tests depend on one another before running, this should be avoided. SaltStack recommends that each test should test a single functionality and not rely on other tests. Therefore, when possible, individual tests should also be broken up into singular pieces. These are not hard\-and\-fast rules, but serve more as recommendations to keep the test suite simple. This helps with debugging code and related tests when failures occur and problems are exposed. There may be instances where large tests use many asserts to set up a use case that protects against potential regressions. .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 The examples above all use the \fBrun_function\fP option to test execution module functions in a traditional master/minion environment. To see examples of how to test other common Salt components such as runners, salt\-api, and more, please refer to the Integration Test Class Examples documentation. .UNINDENT .UNINDENT .SS Destructive vs Non\-destructive Tests .sp Since Salt is used to change the settings and behavior of systems, often, the best approach to run tests is to make actual changes to an underlying system. This is where the concept of destructive integration tests comes into play. Tests can be written to alter the system they are running on. This capability is what fills in the gap needed to properly test aspects of system management like package installation. .sp To write a destructive test, import and use the \fBdestructiveTest\fP decorator for the test method: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C import integration from tests.support.helpers import destructiveTest class PkgTest(integration.ModuleCase): @destructiveTest def test_pkg_install(self): ret = self.run_function("pkg.install", name="finch") self.assertSaltTrueReturn(ret) ret = self.run_function("pkg.purge", name="finch") self.assertSaltTrueReturn(ret) .ft P .fi .UNINDENT .UNINDENT .SS Writing Unit Tests .sp As explained in the \fI\%Integration vs. Unit\fP section above, unit tests should be written to test the \fIlogic\fP of a function. This includes focusing on testing \fBreturn\fP and \fBraises\fP statements. Substantial effort should be made to mock external resources that are used in the code being tested. .sp External resources that should be mocked include, but are not limited to, APIs, function calls, external data either globally available or passed in through function arguments, file data, etc. This practice helps to isolate unit tests to test Salt logic. One handy way to think about writing unit tests is to "block all of the exits". More information about how to properly mock external resources can be found in Salt\(aqs Unit Test documentation. .sp Salt\(aqs unit tests utilize Python\(aqs mock class as well as \fI\%MagicMock\fP\&. The \fB@patch\fP decorator is also heavily used when "blocking all the exits". .sp A simple example of a unit test currently in use in Salt is the \fBtest_get_file_not_found\fP test in the \fBtests/unit/modules/test_cp.py\fP file. This test uses the \fB@patch\fP decorator and \fBMagicMock\fP to mock the return of the call to Salt\(aqs \fBcp.hash_file\fP execution module function. This ensures that we\(aqre testing the \fBcp.get_file\fP function directly, instead of inadvertently testing the call to \fBcp.hash_file\fP, which is used in \fBcp.get_file\fP\&. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C def test_get_file_not_found(self): """ Test if get_file can\(aqt find the file. """ with patch("salt.modules.cp.hash_file", MagicMock(return_value=False)): path = "salt://saltines" dest = "/srv/salt/cheese" ret = "" assert cp.get_file(path, dest) == ret .ft P .fi .UNINDENT .UNINDENT .sp Note that Salt\(aqs \fBcp\fP module is imported at the top of the file, along with all of the other necessary testing imports. The \fBget_file\fP function is then called directed in the testing function, instead of using the \fBrun_function\fP method as the integration test examples do above. .sp The call to \fBcp.get_file\fP returns an empty string when a \fBhash_file\fP isn\(aqt found. Therefore, the example above is a good illustration of a unit test "blocking the exits" via the \fB@patch\fP decorator, as well as testing logic via asserting against the \fBreturn\fP statement in the \fBif\fP clause. In this example we used the python \fBassert\fP to verify the return from \fBcp.get_file\fP\&. Pytest allows you to use these \fI\%asserts\fP when writing your tests and, in fact, plain \fI\%asserts\fP is the preferred way to assert anything in your tests. As Salt dives deeper into Pytest, the use of \fIunittest.TestClass\fP will be replaced by plain test functions, or test functions grouped in a class, which \fBdoes not\fP subclass \fIunittest.TestClass\fP, which, of course, doesn\(aqt work with unittest assert functions. .sp There are more examples of writing unit tests of varying complexities available in the following docs: .INDENT 0.0 .IP \(bu 2 Simple Unit Test Example .IP \(bu 2 Complete Unit Test Example .IP \(bu 2 Complex Unit Test Example .UNINDENT .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 Considerable care should be made to ensure that you\(aqre testing something useful in your test functions. It is very easy to fall into a situation where you have mocked so much of the original function that the test results in only asserting against the data you have provided. This results in a poor and fragile unit test. .UNINDENT .UNINDENT .SS Add a python module dependency to the test run .sp The test dependencies for python modules are managed under the \fBrequirements/static\fP directory. You will need to add your module to the appropriate file under \fBrequirements/static\fP\&. When \fBpre\-commit\fP is run it will create all of the needed requirement files under \fBrequirements/static/py3{5,6,7}\fP\&. Nox will then use these files to install the requirements for the tests. .SS Add a system dependency to the test run .sp If you need to add a system dependency for the test run, this will need to be added in the \fI\%salt jenkins\fP repo. This repo uses salt states to install system dependencies. You need to update the \fBstate\-tree/golden\-images\-provision.sls\fP file with your dependency to ensure it is installed. Once your PR is merged the core team will need to promote the new images with your new dependency installed. .SS Checking for Log Messages .sp To test to see if a given log message has been emitted, the following pattern can be used .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C # Import logging handler from tests.support.helpers import TstSuiteLoggingHandler # .. inside test with TstSuiteLoggingHandler() as handler: for message in handler.messages: if message.startswith("ERROR: This is the error message we seek"): break else: raise AssertionError("Did not find error message") .ft P .fi .UNINDENT .UNINDENT .SS Automated Test Runs .sp SaltStack maintains a Jenkins server which can be viewed at \fI\%https://jenkinsci.saltstack.com\fP\&. The tests executed from this Jenkins server create fresh virtual machines for each test run, then execute the destructive tests on the new, clean virtual machine. This allows for the execution of tests across supported platforms. .SS Additional Testing Documentation .sp In addition to this tutorial, there are some other helpful resources and documentation that go into more depth on Salt\(aqs test runner, writing tests for Salt code, and general Python testing documentation. Please see the follow references for more information: .INDENT 0.0 .IP \(bu 2 Salt\(aqs Test Suite Documentation .IP \(bu 2 Integration Tests .IP \(bu 2 Unit Tests .IP \(bu 2 \fI\%MagicMock\fP .IP \(bu 2 \fI\%Python Unittest\fP .IP \(bu 2 \fI\%Python\(aqs Assert Functions\fP .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 master 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 Make sure you have yappi installed. .sp Results can then be analyzed with \fI\%kcachegrind\fP or similar tool. .sp Make sure you have yappi installed. .sp On Windows, in the absence of kcachegrind, a simple file\-based workflow to create profiling graphs could use \fI\%gprof2dot\fP, \fI\%graphviz\fP and this batch file: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C :: :: Converts callgrind* profiler output to *.pdf, via *.dot :: @echo off del *.dot.pdf for /r %%f in (callgrind*) do ( echo "%%f" gprof2dot.exe \-f callgrind \-\-show\-samples "%%f" \-o "%%f.dot" dot.exe "%%f.dot" \-Tpdf \-O del "%%f.dot" ) .ft P .fi .UNINDENT .UNINDENT .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. .sp If a \fBstate.apply\fP run takes too long, you can find a bottleneck by adding the \fB\-\-out=profile\fP option. .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 states 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 .sp If a \fBstate.apply\fP run takes too long, you can find a bottleneck by adding the \fB\-\-out=profile\fP option. .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 dictionaries 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 Multi\-line Strings .sp Similarly, when a multi\-line string is nested within a list item (such as when using the \fBcontents\fP argument for a \fBfile.managed\fP state), the indentation must be doubled. Take for example the following state: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C /tmp/foo.txt: file.managed: \- contents: | foo bar baz .ft P .fi .UNINDENT .UNINDENT .sp This is invalid YAML, and will result in a rather cryptic error when you try to run the state: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C myminion: Data failed to compile: \-\-\-\-\-\-\-\-\-\- Rendering SLS \(aqbase:test\(aq failed: could not find expected \(aq:\(aq; line 5 \-\-\- /tmp/foo.txt: file.managed: \- contents: | foo bar <====================== baz \-\-\- .ft P .fi .UNINDENT .UNINDENT .sp The correct indentation would be as follows: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C /tmp/foo.txt: file.managed: \- contents: | foo bar baz .ft P .fi .UNINDENT .UNINDENT .SS True/False, Yes/No, On/Off .sp PyYAML will load these values as boolean \fBTrue\fP or \fBFalse\fP\&. Un\-capitalized versions will also be loaded as booleans (\fBtrue\fP, \fBfalse\fP, \fByes\fP, \fBno\fP, \fBon\fP, and \fBoff\fP). This can be especially problematic when constructing Pillar data. Make sure that your Pillars which need to use the string versions of these values are enclosed in quotes. Pillars will be parsed twice by salt, so you\(aqll need to wrap your values in multiple quotes, including double quotation marks (\fB" "\fP) and single quotation marks (\fB\(aq \(aq\fP). Note that spaces are included in the quotation type examples for clarity. .sp Multiple quoting examples looks like this: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C \- \(aq"false"\(aq \- "\(aqTrue\(aq" \- "\(aqYES\(aq" \- \(aq"No"\(aq .ft P .fi .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 When using multiple quotes in this manner, they must be different. Using \fB"" ""\fP or \fB\(aq\(aq \(aq\(aq\fP won\(aqt work in this case (spaces are included in examples for clarity). .UNINDENT .UNINDENT .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 Time Expressions .sp PyYAML will load a time expression as the integer value of that, assuming \fBHH:MM\fP\&. So for example, \fB12:00\fP is loaded by PyYAML as \fB720\fP\&. An excellent explanation for why can be found \fI\%here\fP\&. .sp To keep time expressions like this from being loaded as integers, always quote them. .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 When using a jinja \fBload_yaml\fP map, items must be quoted twice. For example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C {% load_yaml as wsus_schedule %} FRI_10: time: \(aq"23:00"\(aq day: 6 \- Every Friday SAT_10: time: \(aq"06:00"\(aq day: 7 \- Every Saturday SAT_20: time: \(aq"14:00"\(aq day: 7 \- Every Saturday SAT_30: time: \(aq"22:00"\(aq day: 7 \- Every Saturday SUN_10: time: \(aq"06:00"\(aq day: 1 \- Every Sunday {% endload %} .ft P .fi .UNINDENT .UNINDENT .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 supports 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 by the \fI\%YAML Spec\fP to a single line, and cannot be longer that 1024 characters. PyYAML enforces these limitations (see \fI\%here\fP), and therefore anything parsed as YAML in Salt is subject to them. .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 Minion daemon using Salt after upgrade?\fP .INDENT 2.0 .IP \(bu 2 \fI\%Upgrade without automatic restart\fP .IP \(bu 2 \fI\%Restart using states\fP .IP \(bu 2 \fI\%Restart using remote executions\fP .IP \(bu 2 \fI\%Waiting for minions to come back online\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. .sp Similarly, custom states are synced to Minions when \fBsaltutil.sync_states\fP, or \fBsaltutil.sync_all\fP is run. .sp They are both also synced when a highstate is triggered. .sp As of the 2019.2.0 release, as well as 2017.7.7 and 2018.3.2 in their respective release cycles, the \fBsync\fP argument to \fBstate.apply\fP/\fBstate.sls\fP can be used to sync custom types when running individual SLS files. .sp Other custom types (renderers, outputters, etc.) have similar behavior, see the documentation for the \fBsaltutil\fP module for more information. .sp This reactor example can be used to automatically sync custom types when the minion connects to the master, to help with this chicken\-and\-egg issue. .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 Minion daemon using Salt after upgrade? .sp Updating the \fBsalt\-minion\fP package requires a restart of the \fBsalt\-minion\fP 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. A common way to workaround that is to schedule restarting the Minion service in the background by issuing a \fBsalt\-call\fP command calling \fBservice.restart\fP function. This prevents the Minion being disconnected from the Master immediately. Otherwise you would get \fBMinion did not return. [Not connected]\fP message as the result of a state run. .SS Upgrade without automatic restart .sp Doing the Minion upgrade seems to be a simplest state in your SLS file at first. But the operating systems such as Debian GNU/Linux, Ubuntu and their derivatives start the service after the package installation by default. To prevent this, we need to create policy layer which will prevent the Minion service to restart right after the upgrade: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C {%\- if grains[\(aqos_family\(aq] == \(aqDebian\(aq %} Disable starting services: file.managed: \- name: /usr/sbin/policy\-rc.d \- user: root \- group: root \- mode: 0755 \- contents: \- \(aq#!/bin/sh\(aq \- exit 101 # do not touch if already exists \- replace: False \- prereq: \- pkg: Upgrade Salt Minion {%\- endif %} Upgrade Salt Minion: pkg.installed: \- name: salt\-minion \- version: 2016.11.3{% if grains[\(aqos_family\(aq] == \(aqDebian\(aq %}+ds\-1{% endif %} \- order: last Enable Salt Minion: service.enabled: \- name: salt\-minion \- require: \- pkg: Upgrade Salt Minion {%\- if grains[\(aqos_family\(aq] == \(aqDebian\(aq %} Enable starting services: file.absent: \- name: /usr/sbin/policy\-rc.d \- onchanges: \- pkg: Upgrade Salt Minion {%\- endif %} .ft P .fi .UNINDENT .UNINDENT .SS Restart using states .sp Now we can apply the workaround to restart the Minion in reliable way. The following example works on UNIX\-like operating systems: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C {%\- if grains[\(aqos\(aq] != \(aqWindows\(aq %} Restart Salt Minion: cmd.run: \- name: \(aqsalt\-call service.restart salt\-minion\(aq \- bg: True \- onchanges: \- pkg: Upgrade Salt Minion {%\- endif %} .ft P .fi .UNINDENT .UNINDENT .sp Note that restarting the \fBsalt\-minion\fP service on Windows operating systems is not always necessary when performing an upgrade. The installer stops the \fBsalt\-minion\fP service, removes it, deletes the contents of the \fB\esalt\ebin\fP directory, installs the new code, re\-creates the \fBsalt\-minion\fP service, and starts it (by default). The restart step \fBwould\fP be necessary during the upgrade process, however, if the minion config was edited after the upgrade or installation. If a minion restart is necessary, the state above can be edited as follows: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C Restart Salt Minion: cmd.run: {%\- if grains[\(aqkernel\(aq] == \(aqWindows\(aq %} \- name: \(aqC:\esalt\esalt\-call.bat service.restart salt\-minion\(aq {%\- else %} \- name: \(aqsalt\-call service.restart salt\-minion\(aq {%\- endif %} \- bg: True \- onchanges: \- pkg: Upgrade Salt Minion .ft P .fi .UNINDENT .UNINDENT .sp However, it requires more advanced tricks to upgrade from legacy version of Salt (before \fB2016.3.0\fP) on UNIX\-like operating systems, where executing commands in the background is not supported. You also may need to schedule restarting the Minion service using masterless mode after all other states have been applied for Salt versions earlier than \fB2016.11.0\fP\&. This allows the Minion to keep the connection to the Master alive for being able to report the final results back to the Master, while the service is restarting in the background. This state should run last or watch for the \fBpkg\fP state changes: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C Restart Salt Minion: cmd.run: {%\- if grains[\(aqkernel\(aq] == \(aqWindows\(aq %} \- name: \(aqstart powershell "Restart\-Service \-Name salt\-minion"\(aq {%\- else %} # fork and disown the process \- name: |\- exec 0>&\- # close stdin exec 1>&\- # close stdout exec 2>&\- # close stderr nohup salt\-call \-\-local service.restart salt\-minion & {%\- endif %} .ft P .fi .UNINDENT .UNINDENT .SS Restart using remote executions .sp Restart the Minion from the command line: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt \-G kernel:Windows cmd.run_bg \(aqC:\esalt\esalt\-call.bat service.restart salt\-minion\(aq salt \-C \(aqnot G@kernel:Windows\(aq cmd.run_bg \(aqsalt\-call service.restart salt\-minion\(aq .ft P .fi .UNINDENT .UNINDENT .SS Waiting for minions to come back online .sp A common issue in performing automated restarts of a salt minion, for example during an orchestration run, is that it will break the orchestration since the next statement is likely to be attempted before the minion is back online. This can be remedied by inserting a blocking waiting state that only returns when the selected minions are back up (note: this will only work in orchestration states since \fImanage.up\fP needs to run on the master): .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C Wait for salt minion: loop.until_no_eval: \- name: saltutil.runner \- expected: \- my_minion \- args: \- manage.up \- kwargs: tgt: my_minion \- period: 3 \- init_wait: 3 .ft P .fi .UNINDENT .UNINDENT .sp This will, after an initial delay of 3 seconds, execute the \fImanage.up\fP\-runner targeted specifically for \fImy_minion\fP\&. It will do this every \fIperiod\fP seconds until the \fIexpected\fP data is returned. The default timeout is 60s but can be configured as well. .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 .sp Restarting the \fBsalt\-master\fP service using execution module or application of state could be done the same way as for the Salt minion described \fI\%above\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 The only grain which can be safely used is \fBgrains[\(aqid\(aq]\fP which contains the Minion ID. .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 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 env=\(aq{FIRST_NAME: "Joe"}\(aq .ft P .fi .UNINDENT .UNINDENT .sp Note: dictionaries must have curly braces around them (like the \fBenv\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 env=\(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\fP), unless environments are otherwise defined in the \fBfile_roots\fP config option, the \fB_modules/\fP directory would be located in \fB/srv/salt/_modules\fP on most systems. .sp Modules placed in \fB_modules/\fP will be synced to the minions when any of the following Salt functions are called: .INDENT 0.0 .IP \(bu 2 \fBstate.highstate\fP (or \fBstate.apply\fP with no state argument) .IP \(bu 2 \fBsaltutil.sync_modules\fP .IP \(bu 2 \fBsaltutil.sync_all\fP .UNINDENT .sp Modules placed in \fB_modules/\fP will be synced to masters when any of the following Salt runners are called: .INDENT 0.0 .IP \(bu 2 \fBsaltutil.sync_modules\fP .IP \(bu 2 \fBsaltutil.sync_all\fP .UNINDENT .sp Note that a module\(aqs default name is its filename (i.e. \fBfoo.py\fP becomes module \fBfoo\fP), but that its name can be overridden by using a \fI\%__virtual__ function\fP\&. .sp If a Salt module has errors and cannot be imported, the Salt minion will continue to load without issue and the module with errors will simply be omitted. .sp If adding a Cython module the file must be named \fB.pyx\fP so that the loader knows that the module needs to be imported as a Cython module. The compilation of the Cython module is automatic and happens when the minion starts, so only the \fB*.pyx\fP file is required. .SS 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): """ Checks whether a person is really a lumberjack """ 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__["cmd.run"](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\%Python dictionary\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 \fB__init__\fP Function .sp If you want your module to have different execution modes based on minion configuration, you can use the \fB__init__(opts)\fP function to perform initial module setup. The parameter \fBopts\fP is the complete minion configuration, as also available in the \fB__opts__\fP dict. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C """ Cheese module initialization example """ def __init__(opts): """ Allow foreign imports if configured to do so """ if opts.get("cheese.allow_foreign", False): _enable_foreign_products() .ft P .fi .UNINDENT .UNINDENT .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__ = {"run": "txt"} .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 unreliable as not all modules will be available at this point in time. The \fB__pillar__\fP and \fB__grains__\fP "dunder" dictionaries are available however. .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 """ Cheese execution (or returner/beacon/etc.) module """ try: import enzymes HAS_ENZYMES = True except ImportError: HAS_ENZYMES = False def __virtual__(): """ only load cheese if enzymes are available """ if HAS_ENZYMES: return "cheese" else: return ( False, "The cheese execution module cannot be loaded: enzymes unavailable.", ) def slice(): pass .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C """ Cheese state module. Note that this works in state modules because it is guaranteed that execution modules are loaded first """ def __virtual__(): """ only load cheese if enzymes are available """ # predicate loading of the cheese state on the corresponding execution module if "cheese.slice" in __salt__: return "cheese" else: return False, "The cheese state module cannot be loaded: enzymes unavailable." .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 Logging Restrictions .sp As a rule, logging should not be done anywhere in a Salt module before it is loaded. This rule apples to all code that would run before the \fB__virtual__()\fP function, as well as the code within the \fB__virtual__()\fP function itself. .sp If logging statements are made before the virtual function determines if the module should be loaded, then those logging statements will be called repeatedly. This clutters up log files unnecessarily. .sp Exceptions may be considered for logging statements made at the \fBtrace\fP level. However, it is better to provide the necessary information by another means. One method is to \fI\%return error information\fP in the \fB__virtual__()\fP function. .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__ = "pkg" def __virtual__(): """ Confine this module to Mac OS with Homebrew. """ if salt.utils.path.which("brew") and __grains__["os"] == "MacOS": return __virtualname__ return False .ft P .fi .UNINDENT .UNINDENT .sp The \fB__virtual__()\fP function can return a \fBTrue\fP or \fBFalse\fP boolean, a tuple, or a string. If it returns a \fBTrue\fP value, this \fB__virtualname__\fP module\-level attribute can be set as seen in the above example. This is the string that the module should be referred to as. .sp When \fB__virtual__()\fP returns a tuple, the first item should be a boolean and the second should be a string. This is typically done when the module should not load. The first value of the tuple is \fBFalse\fP and the second is the error message to display for why the module did not load. .sp For example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C def __virtual__(): """ Only load if git exists on the system """ if salt.utils.path.which("git") is None: return (False, "The git execution module cannot be loaded: git unavailable.") else: return True .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): """ A function to make some spam with eggs! CLI Example:: salt \(aq*\(aq test.spam eggs """ 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("Here is Some Information") log.warning("You Should Not Do That") log.error("It Is Busted") .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__ = { "set_": "set", "list_": "list", } .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("Failed to import dependency_that_sometimes_exists: {0}".format(e)) @depends("dependency_that_sometimes_exists") def foo(): """ Function with a dependency on the "dependency_that_sometimes_exists" module, if the "dependency_that_sometimes_exists" is missing this function will not exist """ return True def _fallback(): """ Fallback function for the depends decorator to replace a function with """ return \(aq"dependency_that_sometimes_exists" needs to be installed for this function to exist\(aq @depends("dependency_that_sometimes_exists", fallback_function=_fallback) def foo(): """ 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" """ 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 .SS Executors .sp Executors are used by minion to execute module functions. Executors can be used to modify the functions behavior, do any pre\-execution steps or execute in a specific way like sudo executor. .sp Executors could be passed as a list and they will be used one\-by\-one in the order. If an executor returns \fBNone\fP the next one will be called. If an executor returns non\-\fBNone\fP the execution sequence is terminated and the returned value is used as a result. It\(aqs a way executor could control modules execution working as a filter. Note that executor could actually not execute the function but just do something else and return \fBNone\fP like \fBsplay\fP executor does. In this case some other executor have to be used as a final executor that will actually execute the function. See examples below. .sp Executors list could be passed by minion config file in the following way: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C module_executors: \- splay \- direct_call splaytime: 30 .ft P .fi .UNINDENT .UNINDENT .sp The same could be done by command line: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt \-t 40 \-\-module\-executors=\(aq[splay, direct_call]\(aq \-\-executor\-opts=\(aq{splaytime: 30}\(aq \(aq*\(aq test.version .ft P .fi .UNINDENT .UNINDENT .sp And the same command called via netapi will look like this: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C curl \-sSk https://localhost:8000 \e \-H \(aqAccept: application/x\-yaml\(aq \e \-H \(aqX\-Auth\-Token: 697adbdc8fe971d09ae4c2a3add7248859c87079\(aq \e \-H \(aqContent\-type: application/json\(aq \e \-d \(aq[{ "client": "local", "tgt": "*", "fun": "test.version", "module_executors": ["splay", "direct_call"], "executor_opts": {"splaytime": 10} }]\(aq .ft P .fi .UNINDENT .UNINDENT .sp \fBSEE ALSO:\fP .INDENT 0.0 .INDENT 3.5 The full list of executors .UNINDENT .UNINDENT .SS Writing Salt Executors .sp A Salt executor is written in a similar manner to a Salt execution module. Executor is a python module placed into the \fBexecutors\fP folder and containing the \fBexecute\fP function with the following signature: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C def execute(opts, data, func, args, kwargs): ... .ft P .fi .UNINDENT .UNINDENT .sp Where the args are: .INDENT 0.0 .TP .B \fBopts\fP: Dictionary containing the minion configuration options .TP .B \fBdata\fP: Dictionary containing the load data including \fBexecutor_opts\fP passed via cmdline/API. .TP .B \fBfunc\fP, \fBargs\fP, \fBkwargs\fP: Execution module function to be executed and its arguments. For instance the simplest \fBdirect_call\fP executor just runs it as \fBfunc(*args, **kwargs)\fP\&. .TP .B \fBReturns\fP: \fBNone\fP if the execution sequence must be continued with the next executor. Error string or execution result if the job is done and execution must be stopped. .UNINDENT .sp Specific options could be passed to the executor via minion config or via \fBexecutor_opts\fP argument. For instance to access \fBsplaytime\fP option set by minion config executor should access \fBopts.get(\(aqsplaytime\(aq)\fP\&. To access the option set by commandline or API \fBdata.get(\(aqexecutor_opts\(aq, {}).get(\(aqsplaytime\(aq)\fP should be used. So if an option is safe and must be accessible by user executor should check it in both places, but if an option is unsafe it should be read from the only config ignoring the passed request data. .sp There is also a function named \fBall_missing_func\fP which the name of the \fBfunc\fP is passed, which can be used to verify if the command should still be run, even if it is not loaded in minion_mods. .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: \- name: user.rename \- 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 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): """ 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 """ pkgs = [] # What functions should we aggregate? agg_enabled = [ "installed", "latest", "removed", "purged", ] # The \(galow\(ga data is just a dict with the state, function (fun) and # arguments passed in from the sls if low.get("fun") 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 = __utils__["state.gen_tag"](chunk) if tag in running: # Already ran the pkg state, skip aggregation continue if chunk.get("state") == "pkg": if "__agg__" in chunk: continue # Check for the same function if chunk.get("fun") != low.get("fun"): continue # Pull out the pkg names! if "pkgs" in chunk: pkgs.extend(chunk["pkgs"]) chunk["__agg__"] = True elif "name" in chunk: pkgs.append(chunk["name"]) chunk["__agg__"] = True if pkgs: if "pkgs" in low: low["pkgs"].extend(pkgs) else: low["pkgs"] = 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 it 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. It is possible to override a Global Failhard (see below) by explicitly setting it to \fBFalse\fP in the state. .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 \fBfailhard\fP to \fBTrue\fP 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 its 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. This 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 executed. .sp This ordering system can be disabled in preference of lexicographic (classic) ordering by setting the \fBstate_auto_order\fP option to \fBFalse\fP in the master configuration file. Otherwise, \fBstate_auto_order\fP defaults to \fBTrue\fP\&. .sp How compiler ordering is managed is described further in compiler\-ordering\&. .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 Running States in Parallel .sp Introduced in Salt version \fB2017.7.0\fP it is now possible to run select states in parallel. This is accomplished very easily by adding the \fBparallel: True\fP option to your state declaration: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C nginx: service.running: \- parallel: True .ft P .fi .UNINDENT .UNINDENT .sp Now \fBnginx\fP will be started in a separate process from the normal state run and will therefore not block additional states. .SS Parallel States and Requisites .sp Parallel States still honor requisites. If a given state requires another state that has been run in parallel then the state runtime will wait for the required state to finish. .sp Given this example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C sleep 10: cmd.run: \- parallel: True nginx: service.running: \- parallel: True \- require: \- cmd: sleep 10 sleep 5: cmd.run: \- parallel: True .ft P .fi .UNINDENT .UNINDENT .sp The \fBsleep 10\fP will be started first, then the state system will block on starting nginx until the \fBsleep 10\fP completes. Once nginx has been ensured to be running then the \fBsleep 5\fP will start. .sp This means that the order of evaluation of Salt States and requisites are still honored, and given that in the above case, \fBparallel: True\fP does not actually speed things up. .sp To run the above state much faster make sure that the \fBsleep 5\fP is evaluated before the \fBnginx\fP state .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C sleep 10: cmd.run: \- parallel: True sleep 5: cmd.run: \- parallel: True nginx: service.running: \- parallel: True \- require: \- cmd: sleep 10 .ft P .fi .UNINDENT .UNINDENT .sp Now both of the sleep calls will be started in parallel and \fBnginx\fP will still wait for the state it requires, but while it waits the \fBsleep 5\fP state will also complete. .SS Things to be Careful of .sp Parallel States do not prevent you from creating parallel conflicts on your system. This means that if you start multiple package installs using Salt then the package manager will block or fail. If you attempt to manage the same file with multiple states in parallel then the result can produce an unexpected file. .sp Make sure that the states you choose to run in parallel do not conflict, or else, like in any parallel programming environment, the outcome may not be what you expect. Doing things like just making all states run in parallel will almost certainly result in unexpected behavior. .sp With that said, running states in parallel should be safe the vast majority of the time and the most likely culprit for unexpected behavior is running multiple package installs in parallel. .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. This provides a method to easily define inter\-dependencies between states. These dependencies are expressed by declaring the relationships using state names and IDs or names. The generalized form of a requisite target is \fB: \fP\&. The specific form is defined as a Requisite Reference\&. .sp A common use\-case for requisites is ensuring a package has been installed before trying to ensure the service is running. In the following example, Salt will ensure nginx has been installed before trying to manage the service. If the package could not be installed, Salt will not try to manage the service. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C nginx: pkg.installed: \- name: nginx\-light service.running: \- enable: True \- require: \- pkg: nginx .ft P .fi .UNINDENT .UNINDENT .sp Without the requisite defined, salt would attempt to install the package and then attempt to manage the service even if the installation failed. .sp These requisites always form dependencies in a predictable single direction. Each requisite has an alternate \fI\%_in\fP form that can be used to establish a "reverse" dependency\-\-useful in for loops. .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 typically need two pieces of information for matching: .INDENT 0.0 .IP \(bu 2 The state module name (e.g. \fBpkg\fP or \fBservice\fP) .IP \(bu 2 The state identifier (e.g. \fBnginx\fP or \fB/etc/nginx/nginx.conf\fP) .UNINDENT .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C nginx: pkg.installed: [] file.managed: \- name: /etc/nginx/nginx.conf service.running: \- require: \- pkg: nginx \- file: /etc/nginx/nginx.conf .ft P .fi .UNINDENT .UNINDENT .SS Glob matching in requisites .sp New in version 0.9.8. .sp Glob matching is supported in requisites. This is mostly useful for file changes. In the example below, a change in \fB/etc/apache2/httpd.conf\fP or \fB/etc/apache2/sites\-available/default.conf\fP will reload/restart the service: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C apache2: service.running: \- watch: \- file: /etc/apache2/* .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 \fBDeploy server package\fP \fIor\fP \fB/usr/local/share/myapp.tar.xz\fP, so either of the following versions for "Extract server package" is correct: .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 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 Requisites Types .sp All requisite types have a corresponding \fI\%_in\fP form: .INDENT 0.0 .IP \(bu 2 \fI\%require\fP: Requires that a list of target states succeed before execution .IP \(bu 2 \fI\%onchanges\fP: Execute if any target states succeed with changes .IP \(bu 2 \fI\%watch\fP: Similar to \fBonchanges\fP; modifies state behavior using \fBmod_watch\fP .IP \(bu 2 \fI\%listen\fP: Similar to \fBonchanges\fP; delays execution to end of state run using \fBmod_wait\fP .IP \(bu 2 \fI\%prereq\fP: Execute prior to target state if target state expects to produce changes .IP \(bu 2 \fI\%onfail\fP: Execute only if a target state fails .IP \(bu 2 \fI\%use\fP: Copy arguments from another state .UNINDENT .sp Several requisite types have a corresponding \fI\%requisite_any\fP form: .INDENT 0.0 .IP \(bu 2 \fBrequire_any\fP .IP \(bu 2 \fBwatch_any\fP .IP \(bu 2 \fBonchanges_any\fP .IP \(bu 2 \fBonfail_any\fP .UNINDENT .sp Lastly, onfail has one special \fBonfail_all\fP form to account for when \fIAND\fP logic is desired instead of the default \fIOR\fP logic of onfail/onfail_any (which are equivalent). .sp All requisites define specific relationships and always work with the dependency logic defined \fI\%above\fP\&. .SS require .sp The use of \fBrequire\fP builds a dependency that prevents a state from executing until all required states execute successfully. If any required state fails, then the state will fail due to requisites. .sp In the following example, the \fBservice\fP state will not be checked unless both \fBfile\fP states execute without failure. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C nginx: service.running: \- require: \- file: /etc/nginx/nginx.conf \- file: /etc/nginx/conf.d/ssl.conf .ft P .fi .UNINDENT .UNINDENT .SS Require SLS File .sp As of Salt 0.16.0, it is possible to require an entire sls file. Do this by first 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 a \fBrequire\fP to all of the state declarations found in the given sls file. This means that \fBbar\fP will \fBrequire\fP every state within \fBfoo\fP\&. This makes it very easy to batch large groups of states easily in any requisite statement. .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 (does not fail). 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. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C myservice: file.managed: \- name: /etc/myservice/myservice.conf \- source: salt://myservice/files/myservice.conf cmd.run: \- name: /usr/local/sbin/run\-build \- onchanges: \- file: /etc/myservice/myservice.conf .ft P .fi .UNINDENT .UNINDENT .sp In the example above, \fBcmd.run\fP will run only if there are changes in the \fBfile.managed\fP state. .sp An easy mistake to make is using \fBonchanges_in\fP when \fBonchanges\fP is the correct choice, as seen in this next example. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C myservice: file.managed: \- name: /etc/myservice/myservice.conf \- source: salt://myservice/files/myservice.conf cmd.run: \- name: /usr/local/sbin/run\-build \- onchanges_in: # <\-\- broken logic \- 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 \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\&. .SS watch .sp A \fBwatch\fP requisite is used to add additional behavior when there are changes in other states. This is done using the \fBmod_watch\fP function available from the execution module and will execute any time a watched state changes. .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 \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 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 .sp Another useful example of \fBwatch\fP is using salt to ensure a configuration file is present and in a correct state, ensure the service is running, and trigger \fBservice nginx reload\fP instead of \fBservice nginx restart\fP in order to avoid dropping any connections. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C nginx: service.running: \- reload: True \- watch: \- file: nginx file.managed: \- name: /etc/nginx/conf.d/tls\-settings.conf \- source: salt://nginx/files/tls\-settings.conf .ft P .fi .UNINDENT .UNINDENT .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 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 } } } .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C { "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 If the watching state \fBchanges\fP key contains values, then \fBmod_watch\fP will not be called. If you\(aqre using \fBwatch\fP or \fBwatch_in\fP then it\(aqs a good idea to have a state that only enforces one attribute \- such as splitting out \fBservice.running\fP into its own state and have \fBservice.enabled\fP in another. .UNINDENT .UNINDENT .sp One common source of confusion is expecting \fBmod_watch\fP to be called for every necessary change. You might be tempted to write something like this: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C httpd: service.running: \- enable: True \- watch: \- file: httpd\-config httpd\-config: file.managed: \- name: /etc/httpd/conf/httpd.conf \- source: salt://httpd/files/apache.conf .ft P .fi .UNINDENT .UNINDENT .sp If your service is already running but not enabled, you might expect that Salt will be able to tell that since the config file changed your service needs to be restarted. This is not the case. Because the service needs to be enabled, that change will be made and \fBmod_watch\fP will never be triggered. In this case, changes to your \fBapache.conf\fP will fail to be loaded. If you want to ensure that your service always reloads the correct way to handle this is either ensure that your service is not running before applying your state, or simply make sure that \fBservice.running\fP is in a state on its own: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C enable\-httpd: service.enabled: \- name: httpd start\-httpd: service.running: \- name: httpd \- watch: \- file: httpd\-config httpd\-config: file.managed: \- name: /etc/httpd/conf/httpd.conf \- source: salt://httpd/files/apache.conf .ft P .fi .UNINDENT .UNINDENT .sp Now that \fBservice.running\fP is its own state, changes to \fBservice.enabled\fP will no longer prevent \fBmod_watch\fP from getting triggered, so your \fBhttpd\fP service will get restarted like you want. .SS listen .sp New in version 2014.7.0. .sp A \fBlisten\fP requisite is used to trigger the \fBmod_wait\fP function of an execution module. Rather than modifying execution order, the \fBmod_wait\fP state created by \fBlisten\fP will execute at the end of the state run. .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 restart 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 prereq .sp New in version 0.16.0. .sp The \fBprereq\fP requisite works similar to \fBonchanges\fP except that it uses the result from \fBtest=True\fP on the observed state to determine if it should run prior to the observed state being 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 shut down 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. .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 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. .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 sending a notification or attempting an alternate task or thread of tasks when an important state fails. .sp The \fBonfail\fP requisite is applied in the same way as \fBrequire\fP and \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 .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C build_site: cmd.run: \- name: /srv/web/app/build_site notify\-build_failure: hipchat.send_message: \- room_id: 123456 \- message: "Building website fail on {{ salt.grains.get(\(aqid\(aq) }}" .ft P .fi .UNINDENT .UNINDENT .sp The default behavior of the \fBonfail\fP when multiple requisites are listed is the opposite of other requisites in the salt state engine, it acts by default like \fBany()\fP instead of \fBall()\fP\&. This means that when you list multiple onfail requisites on a state, if \fIany\fP fail the requisite will be satisfied. If you instead need \fIall\fP logic to be applied, you can use \fBonfail_all\fP form: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C test_site_a: cmd.run: \- name: ping \-c1 10.0.0.1 test_site_b: cmd.run: \- name: ping \-c1 10.0.0.2 notify_site_down: hipchat.send_message: \- room_id: 123456 \- message: "Both primary and backup sites are down!" \- onfail_all: \- cmd: test_site_a \- cmd: test_site_b .ft P .fi .UNINDENT .UNINDENT .sp In this contrived example \fInotify_site_down\fP will run when both 10.0.0.1 and 10.0.0.2 fail to respond to ping. .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 Setting failhard (globally or in the failing state) to \fBTrue\fP will cause \fBonfail\fP, \fBonfail_in\fP and \fBonfail_any\fP requisites to be ignored. If you want to combine a global failhard set to True with \fBonfail\fP, \fBonfail_in\fP or \fBonfail_any\fP, you will have to explicitly set failhard to \fBFalse\fP (overriding the global setting) in the state that could fail. .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. Beginning in the \fBNeon\fP release of Salt, a new \fBonfail_all\fP requisite form is available if AND logic is desired. .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 version of requisites .sp Direct requisites form a dependency in a single direction. This makes it possible for Salt to detect cyclical dependencies and helps prevent faulty logic. In some cases, often in loops, it is desirable to establish a dependency in the opposite direction. .sp All direct requisites have an \fB_in\fP counterpart that behaves the same but forms the dependency in the opposite direction. The following sls examples will produce the exact same dependency mapping. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C httpd: pkg.installed: [] service.running: \- require: \- pkg: httpd .ft P .fi .UNINDENT .UNINDENT .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 In the following example, Salt will not try to manage the nginx service or any configuration files unless the nginx package is installed because of the \fBpkg: nginx\fP requisite. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C nginx: pkg.installed: [] service.running: \- enable: True \- reload: True \- require: \- pkg: nginx .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 both php and mod_python are first verified to be installed. Thus allowing for a requisite to be defined "after the fact". .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C {% for cfile in salt.pillar.get(\(aqnginx:config_files\(aq) %} /etc/nginx/conf.d/{{ cfile }}: file.managed: \- source: salt://nginx/configs/{{ cfile }} \- require: \- pkg: nginx \- listen_in: \- service: nginx {% endfor %} .ft P .fi .UNINDENT .UNINDENT .sp In this scenario, \fBlisten_in\fP is a better choice than \fBrequire_in\fP because the \fBlisten\fP requisite will trigger \fBmod_wait\fP behavior which will wait until the end of state execution and then reload the service. .SS The _any version of requisites .sp New in version 2018.3.0. .sp Some requisites have an \fB_any\fP counterpart that changes the requisite behavior from \fBall()\fP to \fBany()\fP\&. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C A: cmd.run: \- name: echo A \- require_any: \- cmd: B \- cmd: C B: cmd.run: \- name: echo B C: cmd.run: \- name: /bin/false .ft P .fi .UNINDENT .UNINDENT .sp In this example \fIA\fP will run because at least one of the requirements specified, \fIB\fP or \fIC\fP, will succeed. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C myservice: pkg.installed /etc/myservice/myservice.conf: file.managed: \- source: salt://myservice/files/myservice.conf /etc/yourservice/yourservice.conf: file.managed: \- source: salt://yourservice/files/yourservice.conf /usr/local/sbin/myservice/post\-changes\-hook.sh cmd.run: \- onchanges_any: \- file: /etc/myservice/myservice.conf \- file: /etc/your_service/yourservice.conf \- require: \- pkg: myservice .ft P .fi .UNINDENT .UNINDENT .sp In this example, \fIcmd.run\fP would be run only if either of the \fIfile.managed\fP states generated changes and at least one of the watched state\(aqs "result" is \fBTrue\fP\&. .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\&. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C grains_refresh: module.run: \- name: saltutil.refresh_grains \- reload_grains: true grains_read: module.run: \- name: grains.items .ft P .fi .UNINDENT .UNINDENT .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: some_check .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\&. .sp Changed in version 3000: The \fBunless\fP requisite can take a module as a dictionary field in unless. The dictionary must contain an argument \fBfun\fP which is the module that is being run, and everything else must be passed in under the args key or will be passed as individual kwargs to the module function. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C install apache on debian based distros: cmd.run: \- name: make install \- cwd: /path/to/dir/whatever\-2.1.5/ \- unless: \- fun: file.file_exists path: /usr/local/bin/whatever .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C set mysql root password: debconf.set: \- name: mysql\-server\-5.7 \- data: \(aqmysql\-server/root_password\(aq: {\(aqtype\(aq: \(aqpassword\(aq, \(aqvalue\(aq: {{pillar[\(aqmysql.pass\(aq]}} } \- unless: \- fun: pkg.version args: \- mysql\-server\-5.7 .ft P .fi .UNINDENT .UNINDENT .sp Changed in version sodium: For modules which return a deeper data structure, the \fBget_return\fP key can be used to access results. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C test: test.nop: \- name: foo \- unless: \- fun: consul.get consul_url: http://127.0.0.1:8500 key: not\-existing get_return: res .ft P .fi .UNINDENT .UNINDENT .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. .sp Changed in version 3000: The \fBonlyif\fP requisite can take a module as a dictionary field in onlyif. The dictionary must contain an argument \fBfun\fP which is the module that is being run, and everything else must be passed in under the args key or will be passed as individual kwargs to the module function. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C install apache on redhat based distros: pkg.latest: \- name: httpd \- onlyif: \- fun: match.grain tgt: \(aqos_family:RedHat\(aq install apache on debian based distros: pkg.latest: \- name: apache2 \- onlyif: \- fun: match.grain tgt: \(aqos_family:Debian\(aq .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C arbitrary file example: file.touch: \- name: /path/to/file \- onlyif: \- fun: file.search args: \- /etc/crontab \- \(aqentry1\(aq .ft P .fi .UNINDENT .UNINDENT .sp Changed in version sodium: For modules which return a deeper data structure, the \fBget_return\fP key can be used to access results. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C test: test.nop: \- name: foo \- onlyif: \- fun: consul.get consul_url: http://127.0.0.1:8500 key: does\-exist get_return: res .ft P .fi .UNINDENT .UNINDENT .SS Creates .sp New in version 3001. .sp The \fBcreates\fP requisite specifies that a state should only run when any of the specified files do not already exist. Like \fBunless\fP, \fBcreates\fP requisite operates as NAND and is useful in giving more granular control over when a state should execute. This was previously used by the \fBcmd\fP and \fBdocker_container\fP states. .INDENT 0.0 .INDENT 3.5 .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C contrived creates example: file.touch: \- name: /path/to/file \- creates: /path/to/file .ft P .fi .UNINDENT .UNINDENT .UNINDENT .UNINDENT .sp \fBcreates\fP also accepts a list of files, in which case this state will run if \fBany\fP of the files do not exist: .INDENT 0.0 .INDENT 3.5 .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C creates list: file.cmd: \- name: /path/to/command \- creates: \- /path/file \- /path/file2 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .UNINDENT .SS runas .sp New in version 2017.7.0. .sp The \fBrunas\fP global option is used to set the user which will be used to run the command in the \fBcmd.run\fP module. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C django: pip.installed: \- name: django >= 1.6, <= 1.7 \- runas: daniel \- require: \- pkg: python\-pip .ft P .fi .UNINDENT .UNINDENT .sp In the above state, the pip command run by \fBcmd.run\fP will be run by the daniel user. .SS runas_password .sp New in version 2017.7.2. .sp The \fBrunas_password\fP global option is used to set the password used by the runas global option. This is required by \fBcmd.run\fP on Windows when \fBrunas\fP is specified. It will be set when \fBrunas_password\fP is defined in the state. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C run_script: cmd.run: \- name: Powershell \-NonInteractive \-ExecutionPolicy Bypass \-File C:\e\eTemp\e\escript.ps1 \- runas: frank \- runas_password: supersecret .ft P .fi .UNINDENT .UNINDENT .sp In the above state, the Powershell script run by \fBcmd.run\fP will be run by the frank user with the password \fBsupersecret\fP\&. .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: \(aq^enabled=0\(aq \- 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 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 Retrying States .sp New in version 2017.7.0. .sp The retry option in a state allows it to be executed multiple times until a desired result is obtained or the maximum number of attempts have been made. .sp The retry option can be configured by the \fBattempts\fP, \fBuntil\fP, \fBinterval\fP, and \fBsplay\fP parameters. .sp The \fBattempts\fP parameter controls the maximum number of times the state will be run. If not specified or if an invalid value is specified, \fBattempts\fP will default to \fB2\fP\&. .sp The \fBuntil\fP parameter defines the result that is required to stop retrying the state. If not specified or if an invalid value is specified, \fBuntil\fP will default to \fBTrue\fP .sp The \fBinterval\fP parameter defines the amount of time, in seconds, that the system will wait between attempts. If not specified or if an invalid value is specified, \fBinterval\fP will default to \fB30\fP\&. .sp The \fBsplay\fP parameter allows the \fBinterval\fP to be additionally spread out. If not specified or if an invalid value is specified, \fBsplay\fP defaults to \fB0\fP (i.e. no splaying will occur). .sp The following example will run the pkg.installed state until it returns \fBTrue\fP or it has been run \fB5\fP times. Each attempt will be \fB60\fP seconds apart and the interval will be splayed up to an additional \fB10\fP seconds: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C my_retried_state: pkg.installed: \- name: nano \- retry: attempts: 5 until: True interval: 60 splay: 10 .ft P .fi .UNINDENT .UNINDENT .sp The following example will run the pkg.installed state with all the defaults for \fBretry\fP\&. The state will run up to \fB2\fP times, each attempt being \fB30\fP seconds apart, or until it returns \fBTrue\fP\&. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C install_nano: pkg.installed: \- name: nano \- retry: True .ft P .fi .UNINDENT .UNINDENT .sp The following example will run the file.exists state every \fB30\fP seconds up to \fB15\fP times or until the file exists (i.e. the state returns \fBTrue\fP). .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C wait_for_file: file.exists: \- name: /path/to/file \- retry: attempts: 15 interval: 30 .ft P .fi .UNINDENT .UNINDENT .SS Return data from a retried state .sp When a state is retried, the returned output is as follows: .sp The \fBresult\fP return value is the \fBresult\fP from the final run. For example, imagine a state set to \fBretry\fP up to three times or \fBuntil\fP \fBTrue\fP\&. If the state returns \fBFalse\fP on the first run and then \fBTrue\fP on the second, the \fBresult\fP of the state will be \fBTrue\fP\&. .sp The \fBstarted\fP return value is the \fBstarted\fP from the first run. .sp The \fBduration\fP return value is the total duration of all attempts plus the retry intervals. .sp The \fBcomment\fP return value will include the result and comment from all previous attempts. .sp For example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C wait_for_file: file.exists: \- name: /path/to/file \- retry: attempts: 10 interval: 2 splay: 5 .ft P .fi .UNINDENT .UNINDENT .sp Would return similar to the following. The state result in this case is \fBFalse\fP (file.exist was run 10 times with a 2 second interval, but the file specified did not exist on any run). .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C ID: wait_for_file Function: file.exists Result: False Comment: Attempt 1: Returned a result of "False", with the following comment: "Specified path /path/to/file does not exist" Attempt 2: Returned a result of "False", with the following comment: "Specified path /path/to/file does not exist" Attempt 3: Returned a result of "False", with the following comment: "Specified path /path/to/file does not exist" Attempt 4: Returned a result of "False", with the following comment: "Specified path /path/to/file does not exist" Attempt 5: Returned a result of "False", with the following comment: "Specified path /path/to/file does not exist" Attempt 6: Returned a result of "False", with the following comment: "Specified path /path/to/file does not exist" Attempt 7: Returned a result of "False", with the following comment: "Specified path /path/to/file does not exist" Attempt 8: Returned a result of "False", with the following comment: "Specified path /path/to/file does not exist" Attempt 9: Returned a result of "False", with the following comment: "Specified path /path/to/file does not exist" Specified path /path/to/file does not exist Started: 09:08:12.903000 Duration: 47000.0 ms Changes: .ft P .fi .UNINDENT .UNINDENT .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 file 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, target expressions are defined to map minions 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 the examples above, notice that all of the target expressions are globs. The default match type in top files (since version 2014.7.0) is actually the compound matcher, not the glob matcher as in the CLI. .sp A single glob, when passed through the compound matcher, acts the same way as matching by glob, so in most cases the two are indistinguishable. However, there is an edge case in which a minion ID contains whitespace. While it is not recommended to include spaces in a minion ID, Salt will not stop you from doing so. However, since compound expressions are parsed word\-by\-word, if a minion ID contains spaces it will fail to match. In this edge case, it will be necessary to explicitly use the \fBglob\fP matcher: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C base: \(aqminion 1\(aq: \- match: glob \- foo .ft P .fi .UNINDENT .UNINDENT .sp The available match types which can be set for a target expression in the top file are: .TS center; |l|l|. _ T{ Match Type T} T{ Description T} _ T{ glob T} T{ Full minion ID or glob expression to match multiple minions (e.g. \fBminion123\fP or \fBminion*\fP) T} _ T{ pcre T} T{ Perl\-compatible regular expression (PCRE) matching a minion ID (e.g. \fBweb[0\-3].domain.com\fP) T} _ T{ grain T} T{ Match a grain, optionally using globbing (e.g. \fBkernel:Linux\fP or \fBkernel:*BSD\fP) T} _ T{ grain_pcre T} T{ Match a grain using PCRE (e.g. \fBkernel:(Free|Open)BSD\fP) T} _ T{ list T} T{ Comma\-separated list of minions (e.g. \fBminion1,minion2,minion3\fP) T} _ T{ pillar T} T{ Pillar match, optionally using globbing (e.g. \fBrole:webserver\fP or \fBrole:web*\fP) T} _ T{ pillar_pcre T} T{ Pillar match using PCRE (e.g. \fBrole:web(server|proxy)\fP T} _ T{ pillar_exact T} T{ Pillar match with no globbing or PCRE (e.g. \fBrole:webserver\fP) T} _ T{ ipcidr T} T{ Subnet or IP address (e.g. \fB172.17.0.0/16\fP or \fB10.2.9.80\fP) T} _ T{ data T} T{ Match values kept in the minion\(aqs datastore (created using the \fBdata\fP execution module) T} _ T{ range T} T{ Range cluster T} _ T{ compound T} T{ Complex expression combining multiple match types (see here) T} _ T{ nodegroup T} T{ Pre\-defined compound expressions in the master config file (see here) T} _ .TE .sp Below is a slightly more complex top file example, showing some of the above match types: .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 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: \- nagios.server # 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 .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_saltenv_whitelist\fP and \fBgitfs_saltenv_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 \fBWARNING:\fP .INDENT 0.0 .INDENT 3.5 In the 3002 release \fBsls_path\fP, \fBtplfile\fP, and \fBtpldir\fP have had some significant improvements which have the potential to break states that rely on old and broken functionality. These fixes can be enabled by setting the \fBenable_slsvars_fixes\fP feature flag to \fBTrue\fP in your minion\(aqs config file. This functionality will become the default in the 3005 release. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C features: enable_slsvars_fixes: True .ft P .fi .UNINDENT .UNINDENT .UNINDENT .UNINDENT .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 Only Variables .sp The following are only available when processing sls files. If you need these in other templates, you can usually pass them in as template context. .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 directory of 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 directory of the file. For salt includes \fIslspath\fP is the path to the directory of the included file. If current sls file is in root of the file roots, this will return "" .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C {{ slspath }} .ft P .fi .UNINDENT .UNINDENT .SS sls_path .sp A version of \fIslspath\fP with underscores as path separators instead of slashes. So, if \fIslspath\fP is \fIpath/to/state\fP then \fIsls_path\fP is \fIpath_to_state\fP .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C {{ sls_path }} .ft P .fi .UNINDENT .UNINDENT .SS slsdotpath .sp A version of \fIslspath\fP with dots as path separators instead of slashes. So, if \fIslspath\fP is \fIpath/to/state\fP then \fIslsdotpath\fP is \fIpath.to.state\fP\&. This is same as \fIsls\fP if \fIsls\fP points to a directory instead if a file. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C {{ slsdotpath }} .ft P .fi .UNINDENT .UNINDENT .SS slscolonpath .sp A version of \fIslspath\fP with colons (\fI:\fP) as path separators instead of slashes. So, if \fIslspath\fP is \fIpath/to/state\fP then \fIslscolonpath\fP is \fIpath:to:state\fP\&. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C {{ slscolonpath }} .ft P .fi .UNINDENT .UNINDENT .SS tplpath .sp Full path to sls template file being process on local disk. This is usually pointing to a copy of the sls file in a cache directory. This will be in OS specific format (Windows vs POSIX). (It is probably best not to use this.) .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C {{ tplpath }} .ft P .fi .UNINDENT .UNINDENT .SS tplfile .sp Relative path to exact sls template file being processed relative to file roots. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C {{ tplfile }} .ft P .fi .UNINDENT .UNINDENT .SS tpldir .sp Directory, relative to file roots, of the current sls file. If current sls file is in root of the file roots, this will return ".". This is usually identical to \fIslspath\fP except in case of root\-level sls, where this will return a "\fI\&.\fP". .sp A Common use case for this variable is to generate relative salt urls like: \&.. code\-block:: jinja .INDENT 0.0 .INDENT 3.5 .INDENT 0.0 .TP .B my\-file: .INDENT 7.0 .TP .B file.managed: source: salt://{{ tpldir }}/files/my\-template .UNINDENT .UNINDENT .UNINDENT .UNINDENT .SS tpldot .sp A version of \fItpldir\fP with dots as path separators instead of slashes. So, if \fItpldir\fP is \fIpath/to/state\fP then \fItpldot\fP is \fIpath.to.state\fP\&. NOTE: if \fItpldir\fP is \fI\&.\fP, this will be set to "" .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C {{ tpldot }} .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", unless a "name" argument is specified below file.managed: # maps to . \- e.g. "managed" in https://github.com/saltstack/salt/tree/master/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 Best Practices .sp A well\-written state function will follow these steps: .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 This is an extremely simplified example. Feel free to browse the \fI\%source code\fP for Salt\(aqs state modules to see other examples. .UNINDENT .UNINDENT .INDENT 0.0 .IP 1. 3 Set up the return dictionary and perform any necessary input validation (type checking, looking for use of mutually\-exclusive arguments, etc.). .INDENT 3.0 .INDENT 3.5 .sp .nf .ft C def myfunc(): ret = {"name": name, "result": False, "changes": {}, "comment": ""} if foo and bar: ret["comment"] = "Only one of foo and bar is permitted" return ret .ft P .fi .UNINDENT .UNINDENT .IP 2. 3 Check if changes need to be made. This is best done with an information\-gathering function in an accompanying execution module\&. The state should be able to use the return from this function to tell whether or not the minion is already in the desired state. .INDENT 3.0 .INDENT 3.5 .sp .nf .ft C result = __salt__["modname.check"](name) .ft P .fi .UNINDENT .UNINDENT .IP 3. 3 If step 2 found that the minion is already in the desired state, then exit immediately with a \fBTrue\fP result and without making any changes. .INDENT 3.0 .INDENT 3.5 .sp .nf .ft C def myfunc(): if result: ret["result"] = True ret["comment"] = "{0} is already installed".format(name) return ret .ft P .fi .UNINDENT .UNINDENT .IP 4. 3 If step 2 found that changes \fIdo\fP need to be made, then check to see if the state was being run in test mode (i.e. with \fBtest=True\fP). If so, then exit with a \fBNone\fP result, a relevant comment, and (if possible) a \fBchanges\fP entry describing what changes would be made. .INDENT 3.0 .INDENT 3.5 .sp .nf .ft C def myfunc(): if __opts__["test"]: ret["result"] = None ret["comment"] = "{0} would be installed".format(name) ret["changes"] = result return ret .ft P .fi .UNINDENT .UNINDENT .IP 5. 3 Make the desired changes. This should again be done using a function from an accompanying execution module. If the result of that function is enough to tell you whether or not an error occurred, then you can exit with a \fBFalse\fP result and a relevant comment to explain what happened. .INDENT 3.0 .INDENT 3.5 .sp .nf .ft C result = __salt__["modname.install"](name) .ft P .fi .UNINDENT .UNINDENT .IP 6. 3 Perform the same check from step 2 again to confirm whether or not the minion is in the desired state. Just as in step 2, this function should be able to tell you by its return data whether or not changes need to be made. .INDENT 3.0 .INDENT 3.5 .sp .nf .ft C ret["changes"] = __salt__["modname.check"](name) .ft P .fi .UNINDENT .UNINDENT .sp As you can see here, we are setting the \fBchanges\fP key in the return dictionary to the result of the \fBmodname.check\fP function (just as we did in step 4). The assumption here is that the information\-gathering function will return a dictionary explaining what changes need to be made. This may or may not fit your use case. .IP 7. 3 Set the return data and return! .INDENT 3.0 .INDENT 3.5 .sp .nf .ft C def myfunc(): if ret["changes"]: ret["comment"] = "{0} failed to install".format(name) else: ret["result"] = True ret["comment"] = "{0} was installed".format(name) return ret .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS Using Custom State Modules .sp Before the state module can be used, it must be distributed to minions. This can be done by placing them into \fBsalt://_states/\fP\&. They can then be distributed manually to minions by running \fBsaltutil.sync_states\fP or \fBsaltutil.sync_all\fP\&. Alternatively, when running a highstate custom types will automatically be synced. .sp NOTE: Writing state modules with hyphens in the filename will cause issues with !pyobjects routines. Best practice to stick to underscores. .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 module\(aqs name defaults to one based on its filename (i.e. \fBfoo.py\fP becomes state module \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__["file.managed"](name="/tmp/myfile", source="salt://myfile") .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["changes"].update({"my_pkg_name": {"old": "", "new": "my_pkg_name\-1.0"}}) .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{ \fBFalse\fP or \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, and hence the result for pending changes is usually \fBNone\fP\&. .sp However, if a state is going to fail and this can be determined in test mode without applying the change, \fBFalse\fP can be returned. .UNINDENT .UNINDENT .IP \(bu 2 \fBcomment:\fP A list of strings or a single string summarizing the result. Note that support for lists of strings is available as of Salt 2018.3.0. Lists of strings will be joined with newlines to form the final comment; this is useful to allow multiple comments from subparts of a state. Prefer to keep line lengths short (use multiple lines as needed), and end with punctuation (e.g. a period) to delimit multiple comments. .UNINDENT .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 States should not return data which cannot be serialized such as frozensets. .UNINDENT .UNINDENT .SS Sub State Runs .sp Some states can return multiple state runs from an external engine. State modules that extend tools like Puppet, Chef, Ansible, and idem can run multiple external states and then return their results individually in the "sub_state_run" portion of their return as long as their individual state runs are formatted like salt states with low and high data. .sp For example, the idem state module can execute multiple idem states via it\(aqs runtime and report the status of all those runs by attaching them to "sub_state_run" in it\(aqs state return. These sub_state_runs will be formatted and printed alongside other salt states. .sp Example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C state_return = { "name": None, # The parent state name "result": None, # The overall status of the external state engine run "comment": None, # Comments on the overall external state engine run "changes": {}, # An empty dictionary, each sub state run has it\(aqs own changes to report "sub_state_run": [ { "changes": {}, # A dictionary describing the changes made in the external state run "result": None, # The external state run name "comment": None, # Comment on the external state run "duration": None, # Optional, the duration in seconds of the external state run "start_time": None, # Optional, the timestamp of the external state run\(aqs start time "low": { "name": None, # The name of the state from the external state run "state": None, # Name of the external state run "__id__": None, # ID of the external state run "fun": None, # The Function name from the external state run }, } ], } .ft P .fi .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 def myfunc(): # Return comment of changes if test. if __opts__["test"]: ret["result"] = None ret["comment"] = "State Foo will execute with param {0}".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): """ Refresh the package database here so that it only needs to happen once """ if low["fun"] == "installed" or low["fun"] == "latest": rtag = __gen_rtag() if not os.path.exists(rtag): open(rtag, "w+").write("") 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("Here is Some Information") log.warning("You Should Not Do That") log.error("It Is Busted") .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): """ 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 """ ret = { "name": name, "changes": {}, "result": False, "comment": "", } # Start with basic error\-checking. Do all the passed parameters make sense # and agree with each\-other? if bar == True and foo.startswith("Foo"): 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__["my_custom_module.current_state"](name) if current_state == foo: ret["result"] = True ret["comment"] = "System already in the correct state" 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__["test"] == True: ret["comment"] = \(aqThe state of "{0}" will be changed.\(aq.format(name) ret["changes"] = { "old": current_state, "new": "Description, diff, whatever of the new state", } # Return \(ga\(gaNone\(ga\(ga when running with \(ga\(gatest=true\(ga\(ga. ret["result"] = None return ret # Finally, make the actual change and return the result. new_state = __salt__["my_custom_module.change_state"](name, foo) ret["comment"] = \(aqThe state of "{0}" was changed!\(aq.format(name) ret["changes"] = { "old": current_state, "new": new_state, } ret["result"] = 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 the 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 target expressions to match minions. Finally, each target expression contains a list 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 target expressions. The first one matches all minions, and the SLS files below it apply to all minions. .sp The second expression is a regular expression that will match all minions with an ID matching \fBsaltmaster.*\fP and specifies that for those minions, the salt.master state should be applied. .sp \fBIMPORTANT:\fP .INDENT 0.0 .INDENT 3.5 Since version 2014.7.0, the default matcher (when one is not explicitly defined as in the second expression in the above example) is the compound matcher. Since this matcher parses individual words in the expression, minion IDs containing spaces will not match properly using this matcher. Therefore, if your target expression is designed to match a minion ID containing spaces, it will be necessary to specify a different match type (such as \fBglob\fP). For example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C base: \(aqtest minion\(aq: \- match: glob \- foo \- bar \- baz .ft P .fi .UNINDENT .UNINDENT .UNINDENT .UNINDENT .sp A full table of match types available in the top file can be found here\&. .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 RETURN CODES .sp When the \fBsalt\fP or \fBsalt\-call\fP CLI commands result in an error, the command will exit with a return code of \fB1\fP\&. Error cases consist of the following: .INDENT 0.0 .IP 1. 3 Errors are encountered while running States, or any state returns a \fBFalse\fP result .IP 2. 3 Any exception is raised .IP 3. 3 In the case of remote\-execution functions, when the return data is a \fI\%Python dictionary\fP with a key named either \fBresult\fP or \fBsuccess\fP, which has a value of \fBFalse\fP .UNINDENT .SS Retcode Passthrough .sp In addition to the cases listed above, if a state or remote\-execution function sets a nonzero value in the \fBretcode\fP key of the __context__ dictionary, the command will exit with a return code of \fB1\fP\&. For those developing custom states and execution modules, using \fB__context__[\(aqretcode\(aq]\fP can be a useful way of signaling that an error has occurred: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C if something_went_wrong: __context__["retcode"] = 42 .ft P .fi .UNINDENT .UNINDENT .sp This is actually how states signal that they have failed. Different cases result in different codes being set in the __context__ dictionary: .INDENT 0.0 .IP \(bu 2 \fB1\fP is set when any error is encountered in the state compiler (missing SLS file, etc.) .IP \(bu 2 \fB2\fP is set when any state returns a \fBFalse\fP result .IP \(bu 2 \fB5\fP is set when Pillar data fails to be compiled before running the state(s) .UNINDENT .sp When the \fB\-\-retcode\-passthrough\fP flag is used with \fBsalt\-call\fP, then \fBsalt\-call\fP will exit with whichever retcode was set in the __context__ dictionary, rather than the default behavior which simply exits with \fB1\fP for any error condition. .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 \-*\- """ My utils module \-\-\-\-\-\-\-\-\-\-\-\-\-\-\- This module contains common functions for use in my other custom types. """ def bar(): return "baz" .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 \-*\- """ My awesome execution module \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- """ def observe_the_awesomeness(): """ Prints information from my utility module CLI Example: .. code\-block:: bash salt \(aq*\(aq mymodule.observe_the_awesomeness """ return __utils__["foo.bar"]() .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 \-*\- """ My utils module \-\-\-\-\-\-\-\-\-\-\-\-\-\-\- This module contains common functions for use in my other custom types. """ def __virtual__(): """ Load as a different name """ return "foo" def bar(): return "baz" .ft P .fi .UNINDENT .UNINDENT .sp New in version 2018.3.0: Instantiating objects from classes declared in util modules works with Master side modules, such as Runners, Outputters, etc. .sp Also you could even write your utility modules in object oriented fashion: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C # \-*\- coding: utf\-8 \-*\- """ My OOP\-style utils module \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- This module contains common functions for use in my other custom types. """ class Foo(object): def __init__(self): pass def bar(self): return "baz" .ft P .fi .UNINDENT .UNINDENT .sp And import them into other custom modules: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C # \-*\- coding: utf\-8 \-*\- """ My awesome execution module \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- """ import mymodule def observe_the_awesomeness(): """ Prints information from my utility module CLI Example: .. code\-block:: bash salt \(aq*\(aq mymodule.observe_the_awesomeness """ foo = mymodule.Foo() return foo.bar() .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 utility 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 a highstate is run, as well as when any of the following Salt functions are called: .INDENT 0.0 .IP \(bu 2 \fBsaltutil.sync_utils\fP .IP \(bu 2 \fBsaltutil.sync_all\fP .UNINDENT .sp As of the 2019.2.0 release, as well as 2017.7.7 and 2018.3.2 in their respective release cycles, the \fBsync\fP argument to \fBstate.apply\fP/\fBstate.sls\fP can be used to sync custom types when running individual SLS files. .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. The event system uses a publish\-subscribe pattern, otherwise know as pub/sub. .SS Event Bus .sp The event system is comprised of a two primary components, which make up the concept of an Event Bus: .INDENT 0.0 .IP \(bu 2 The event sockets, which publish events .IP \(bu 2 The event library, which can listen to events and send events into the salt system .UNINDENT .sp Events are published onto the event bus and event bus subscribers listen for the published events. .sp The event bus is used for both inter\-process communication as well as network transport in Salt. Inter\-process communication is provided through UNIX domain sockets (UDX). .sp The Salt Master and each Salt Minion has their own event bus. .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.version\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.version\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 a \fBtgt_type\fP value which shows what kind of match (\fBglob\fP, \fBpcre\fP, etc.) was used. This value was named \fBexpr_form\fP in the 2016.11 release cycle but has been renamed to \fBtgt_type\fP in 2017.7.0 for consistency with other events. .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 system 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("/etc/salt/master") event = salt.utils.event.get_event( "master", sock_dir=opts["sock_dir"], transport=opts["transport"], 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="salt/auth") .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="salt/job", full=True) tag, data = evdata["tag"], evdata["data"] .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="salt/auth"): 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("/etc/salt/master") sevent = salt.utils.event.get_event( "master", sock_dir=opts["sock_dir"], transport=opts["transport"], opts=opts ) while True: ret = sevent.get_event(full=True) if ret is None: continue if fnmatch.fnmatch(ret["tag"], "salt/job/*/ret/*"): do_something_with_job_return(ret["data"]) .ft P .fi .UNINDENT .UNINDENT .SS Firing Events .sp It is possible to fire events on either the minion\(aqs local bus or to fire events intended for the master. .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. An example of listening local events on a minion on a non\-Windows system: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C # Job on minion import salt.utils.event opts = salt.config.minion_config("/etc/salt/minion") event = salt.utils.event.MinionEvent(opts) for evdata in event.iter_events(match_type="regex", tag="custom/.*"): # do your processing here... ... .ft P .fi .UNINDENT .UNINDENT .sp And an example of listening local events on a Windows system: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C # Job on minion import salt.utils.event opts = salt.config.minion_config(salt.minion.DEFAULT_MINION_OPTS) event = salt.utils.event.MinionEvent(opts) for evdata in event.iter_events(match_type="regex", tag="custom/.*"): # 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(): """ Do something and fire an event to the master when finished CLI Example:: salt \(aq*\(aq my_custom_module:do_something """ # do something! __salt__["event.send"]( "myco/my_custom_module/finished", {"finished": True, "message": "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() ret = caller.cmd( "event.send", "myco/event/success", {"success": True, "message": "It works!"} ) if not ret: # the event could not be sent, process the error here ... .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 or add it to pillars for that minion: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C beacons: inotify: \- files: /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 .sp All beacon configuration is done using list based configuration. .sp New in version Neon. .sp Multiple copies of a particular Salt beacon can be configured by including the \fBbeacon_module\fP parameter in the beacon configuration. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C beacons: watch_importand_file: \- files: /etc/important_file: {} \- beacon_module: inotify watch_another_file: \- files: /etc/another_file: {} \- beacon_module: inotify .ft P .fi .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: \- files: /etc/important_file: {} /opt: {} \- interval: 5 \- disable_during_state_run: True load: \- averages: 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: \- files: /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: \- files: /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 { "_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\(aq] }}\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 here 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 \fBvalidate\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 [{"changes": ["/foo/bar"], "tag": "foo"}, {"changes": ["/foo/baz"], "tag": "bar"}] .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 via the standard methods, see Modular Systems\&. .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 dictionary, 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. Click \fI\%here\fP for more detailed information on the variables available in Jinja templating. .sp Here is the SLS for a simple reaction: .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, which performs a highstate\&. Similarly, a runner can be called: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C {% if data[\(aqdata\(aq][\(aqcustom_var\(aq] == \(aqrunit\(aq %} call_runit_orch: runner.state.orchestrate: \- args: \- mods: orchestrate.runit {% endif %} .ft P .fi .UNINDENT .UNINDENT .sp This example will execute the state.orchestrate runner and intiate an execution of the \fBrunit\fP orchestrator located at \fB/srv/salt/orchestrate/runit.sls\fP\&. .SS Types of Reactions .TS center; |l|l|. _ T{ Name T} T{ Description T} _ T{ \fI\%local\fP T} T{ Runs a remote\-execution function on targeted minions T} _ T{ \fI\%runner\fP T} T{ Executes a runner function T} _ T{ \fI\%wheel\fP T} T{ Executes a wheel function on the master T} _ T{ \fI\%caller\fP T} T{ Runs a remote\-execution function on a masterless minion T} _ .TE .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 The \fBlocal\fP and \fBcaller\fP reaction types will likely be renamed in a future release. These reaction types were named after Salt\(aqs internal client interfaces, and are not intuitively named. Both \fBlocal\fP and \fBcaller\fP will continue to work in Reactor SLS files, however. .UNINDENT .UNINDENT .SS Where to Put Reactor SLS Files .sp Reactor SLS files can come both from files local to the master, and from any of backends enabled via the \fBfileserver_backend\fP config option. Files placed in the Salt fileserver can be referenced using a \fBsalt://\fP URL, just like they can in State SLS files. .sp It is recommended to place reactor and orchestrator SLS files in their own uniquely\-named subdirectories such as \fBorch/\fP, \fBorchestrate/\fP, \fBreact/\fP, \fBreactor/\fP, etc., to keep them organized. .SS Writing Reactor SLS .sp The different reaction types were developed separately and have historically had different methods for passing arguments. For the 2017.7.2 release a new, unified configuration schema has been introduced, which applies to all reaction types. .sp The old config schema will continue to be supported, and there is no plan to deprecate it at this time. .SS Local Reactions .sp A \fBlocal\fP reaction runs a remote\-execution function on the targeted minions. .sp The old config schema required the positional and keyword arguments to be manually separated by the user under \fBarg\fP and \fBkwarg\fP parameters. However, this is not very user\-friendly, as it forces the user to distinguish which type of argument is which, and make sure that positional arguments are ordered properly. Therefore, the new config schema is recommended if the master is running a supported release. .sp The below two examples are equivalent: .TS center; |l|l|. _ T{ Supported in 2017.7.2 and later T} T{ Supported in all releases T} _ T{ .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C install_zsh: local.state.single: \- tgt: \(aqkernel:Linux\(aq \- tgt_type: grain \- args: \- fun: pkg.installed \- name: zsh \- fromrepo: updates .ft P .fi .UNINDENT .UNINDENT T} T{ .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C install_zsh: local.state.single: \- tgt: \(aqkernel:Linux\(aq \- tgt_type: grain \- arg: \- pkg.installed \- zsh \- kwarg: fromrepo: updates .ft P .fi .UNINDENT .UNINDENT T} _ .TE .sp This reaction would be equivalent to running the following Salt command: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt \-G \(aqkernel:Linux\(aq state.single pkg.installed name=zsh fromrepo=updates .ft P .fi .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 Any other parameters in the \fBLocalClient().cmd_async()\fP method can be passed at the same indentation level as \fBtgt\fP\&. .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 \fBtgt_type\fP is only required when the target expression defined in \fBtgt\fP uses a target type other than a minion ID glob. .sp The \fBtgt_type\fP argument was named \fBexpr_form\fP in releases prior to 2017.7.0. .UNINDENT .UNINDENT .SS Runner Reactions .sp Runner reactions execute runner functions locally on the master. .sp The old config schema called for passing arguments to the reaction directly under the name of the runner function. However, this can cause unpredictable interactions with the Reactor system\(aqs internal arguments. It is also possible to pass positional and keyword arguments under \fBarg\fP and \fBkwarg\fP like above in \fI\%local reactions\fP, but as noted above this is not very user\-friendly. Therefore, the new config schema is recommended if the master is running a supported release. .sp The below two examples are equivalent: .TS center; |l|l|. _ T{ Supported in 2017.7.2 and later T} T{ Supported in all releases T} _ T{ .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C deploy_app: runner.state.orchestrate: \- args: \- mods: orchestrate.deploy_app \- pillar: event_tag: {{ tag }} event_data: {{ data[\(aqdata\(aq]|json }} .ft P .fi .UNINDENT .UNINDENT T} T{ .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C deploy_app: runner.state.orchestrate: \- mods: orchestrate.deploy_app \- kwarg: pillar: event_tag: {{ tag }} event_data: {{ data[\(aqdata\(aq]|json }} .ft P .fi .UNINDENT .UNINDENT T} _ .TE .sp Assuming that the event tag is \fBfoo\fP, and the data passed to the event is \fB{\(aqbar\(aq: \(aqbaz\(aq}\fP, then this reaction is equivalent to running the following Salt command: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt\-run state.orchestrate mods=orchestrate.deploy_app pillar=\(aq{"event_tag": "foo", "event_data": {"bar": "baz"}}\(aq .ft P .fi .UNINDENT .UNINDENT .SS Wheel Reactions .sp Wheel reactions run wheel functions locally on the master. .sp Like \fI\%runner reactions\fP, the old config schema called for wheel reactions to have arguments passed directly under the name of the wheel function (or in \fBarg\fP or \fBkwarg\fP parameters). .sp The below two examples are equivalent: .TS center; |l|l|. _ T{ Supported in 2017.7.2 and later T} T{ Supported in all releases T} _ T{ .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C remove_key: wheel.key.delete: \- args: \- match: {{ data[\(aqid\(aq] }} .ft P .fi .UNINDENT .UNINDENT T} T{ .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C remove_key: wheel.key.delete: \- match: {{ data[\(aqid\(aq] }} .ft P .fi .UNINDENT .UNINDENT T} _ .TE .SS Caller Reactions .sp Caller reactions run remote\-execution functions on a minion daemon\(aqs Reactor system. To run a Reactor on the minion, it is necessary to configure the \fBReactor Engine\fP in the minion config file, and then setup your watched events in a \fBreactor\fP section in the minion config file as well. .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 .sp Both the old and new config schemas involve passing arguments under an \fBargs\fP parameter. However, the old config schema only supports positional arguments. Therefore, the new config schema is recommended if the masterless minion is running a supported release. .sp The below two examples are equivalent: .TS center; |l|l|. _ T{ Supported in 2017.7.2 and later T} T{ Supported in all releases T} _ T{ .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C touch_file: caller.file.touch: \- args: \- name: /tmp/foo .ft P .fi .UNINDENT .UNINDENT T} T{ .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C touch_file: caller.file.touch: \- args: \- /tmp/foo .ft P .fi .UNINDENT .UNINDENT T} _ .TE .sp This reaction is equivalent to running the following Salt command: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt\-call file.touch name=/tmp/foo .ft P .fi .UNINDENT .UNINDENT .SS Best Practices for Writing Reactor SLS Files .sp The Reactor works as follows: .INDENT 0.0 .IP 1. 3 The Salt Reactor watches Salt\(aqs event bus for new events. .IP 2. 3 Each event\(aqs tag is matched against the list of event tags configured 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. For that reason, reactor SLS files should contain few individual reactions (one, if at all possible). Also, keep in mind that reactions are fired asynchronously (with the exception of \fI\%caller\fP) and do \fInot\fP support requisites\&. .sp Complex Jinja templating that calls out to slow remote\-execution or runner functions 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 like orchestration jobs. .sp Therefore, when complex tasks are in order, orchestration is a natural fit. Orchestration SLS files can be more complex, and use requisites. Performing a complex task using orchestration lets the Reactor system fire off the orchestration job and proceed with processing other reactions. .SS Jinja Context .sp Reactor SLS files only have access to a minimal Jinja context. \fBgrains\fP and \fBpillar\fP are \fInot\fP available. The \fBsalt\fP object is available for calling remote\-execution or runner functions, but it should be used sparingly and only for quick tasks for the reasons mentioned above. .sp In addition to the \fBsalt\fP object, the following variables are available in the Jinja context: .INDENT 0.0 .IP \(bu 2 \fBtag\fP \- the tag from the event that triggered execution of the Reactor SLS file .IP \(bu 2 \fBdata\fP \- the event\(aqs data dictionary .UNINDENT .sp The \fBdata\fP dict will contain an \fBid\fP key containing the minion ID, if the event was fired from a minion, and a \fBdata\fP key containing the data passed to the event. .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: \- my/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: \- args: \- mods: orchestrate.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/orchestrate/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 \- kwarg: 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 Similarly, the data dictionary attached to the event would be located in \fB{{ data[\(aqdata\(aq][\(aqdata\(aq] }}\fP instead of \fB{{ data[\(aqdata\(aq] }}\fP\&. .sp See the beacon documentation for examples. .SS Manually Firing an Event .SS From the Master .sp Use the \fBevent.send\fP runner: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt\-run event.send foo \(aq{orchestrate: refresh}\(aq .ft P .fi .UNINDENT .UNINDENT .SS From the Minion .sp To fire an event to the master from a minion, call \fBevent.send\fP: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt\-call event.send foo \(aq{orchestrate: refresh}\(aq .ft P .fi .UNINDENT .UNINDENT .sp To fire an event to the minion\(aqs local event bus, call \fBevent.fire\fP: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt\-call event.fire \(aq{orchestrate: refresh}\(aq foo .ft P .fi .UNINDENT .UNINDENT .SS Referencing Data Passed in Events .sp Assuming any of the above examples, any reactor SLS files triggered by watching the event tag \fBfoo\fP will execute with \fB{{ data[\(aqdata\(aq][\(aqorchestrate\(aq] }}\fP equal to \fB\(aqrefresh\(aq\fP\&. .SS Getting Information About Events .sp The best way to see exactly what events have been 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 Passing Event Data to Minions or Orchestration as Pillar .sp An interesting trick to pass data from the Reactor SLS file 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 \- args: \- mods: haproxy.refresh_pool \- 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 pillar=\(aq{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: \- args: \- mods: orchestrate.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 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: \- args: \- match: {{ data[\(aqid\(aq] }} minion_rejoin: local.cmd.run: \- tgt: salt\-master.domain.tld \- args: \- cmd: 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: \- args: \- 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 \fBsalt/minion/*/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: \- \(aqsalt/minion/*/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. .sp Also, if it is not desirable that \fIevery\fP minion syncs on startup, the \fB*\fP can be replaced with a different glob to narrow down the set of minions which will match that reactor (e.g. \fBsalt/minion/appsrv*/start\fP, which would only match minion IDs beginning with \fBappsrv\fP). .SS Reactor Tuning for Large\-Scale Installations .sp The reactor uses a thread pool implementation that\(aqs contained inside \fBsalt.utils.process.ThreadPool\fP\&. It uses Python\(aqs stdlib Queue to enqueue jobs which are picked up by standard Python threads. If the queue is full, \fBFalse\fP is simply returned by the firing method on the thread pool. .sp As such, there are a few things to say about the selection of proper values for the reactor. .sp For situations where it is expected that many long\-running jobs might be executed by the reactor, \fBreactor_worker_hwm\fP should be increased or even set to \fB0\fP to bound it only by available memory. If set to zero, a close eye should be kept on memory consumption. .sp If many long\-running jobs are expected and execution concurrency and performance are a concern, you may also increase the value for \fBreactor_worker_threads\fP\&. This will control the number of concurrent threads which are pulling jobs from the queue and executing them. Obviously, this bears a relationship to the speed at which the queue itself will fill up. The price to pay for this value is that each thread will contain a copy of Salt code needed to perform the requested action. .SH ORCHESTRATION .SS Orchestrate Runner .sp Executing states or highstate on a minion is perfect when you want to ensure that minion configured and running the way you want. Sometimes however you want to configure a set of minions all at once. .sp For example, if you want to set up a load balancer in front of a cluster of web servers you can ensure the load balancer is set up first, and then the same matching configuration is applied consistently across the whole cluster. .sp Orchestration is the way to do this. .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 replaced the OverState system in 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 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 Writing SLS Files .sp Orchestrate SLS files are stored in the same location as State SLS files. This means that both \fBfile_roots\fP and \fBgitfs_remotes\fP impact what SLS files are available to the reactor and orchestrator. .sp It is recommended to keep reactor and orchestrator SLS files in their own uniquely named subdirectories such as \fB_orch/\fP, \fBorch/\fP, \fB_orchestrate/\fP, \fBreact/\fP, \fB_reactor/\fP, etc. This will avoid duplicate naming and will help prevent confusion. .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 Fail Functions .sp When running a remote execution function in orchestration, certain return values for those functions may indicate failure, while the function itself doesn\(aqt set a return code. For those circumstances, using a "fail function" allows for a more flexible means of assessing success or failure. .sp A fail function can be written as part of a custom execution module\&. The function should accept one argument, and return a boolean result. For example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C def check_func_result(retval): if some_condition: return True else: return False .ft P .fi .UNINDENT .UNINDENT .sp The function can then be referenced in orchestration SLS like so: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C do_stuff: salt.function: \- name: modname.funcname \- tgt: \(aq*\(aq \- fail_function: mymod.check_func_result .ft P .fi .UNINDENT .UNINDENT .sp \fBIMPORTANT:\fP .INDENT 0.0 .INDENT 3.5 Fail functions run \fIon the master\fP, so they must be synced using \fBsalt\-run saltutil.sync_modules\fP\&. .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 Runner .sp To execute another runner, use \fBsalt.runner\fP\&. For example to use the \fBcloud.profile\fP runner in your orchestration state additional options to replace values in the configured profile, use this: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C # /srv/salt/orch/deploy.sls create_instance: salt.runner: \- name: cloud.profile \- prof: cloud\-centos \- provider: cloud \- instances: \- server1 \- opts: minion: master: master1 .ft P .fi .UNINDENT .UNINDENT .sp To get a more dynamic state, use jinja variables together with \fBinline pillar data\fP\&. Using the same example but passing on pillar data, the state would be like this. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C # /srv/salt/orch/deploy.sls {% set servers = salt[\(aqpillar.get\(aq](\(aqservers\(aq, \(aqtest\(aq) %} {% set master = salt[\(aqpillar.get\(aq](\(aqmaster\(aq, \(aqsalt\(aq) %} create_instance: salt.runner: \- name: cloud.profile \- prof: cloud\-centos \- provider: cloud \- instances: \- {{ servers }} \- opts: minion: master: {{ master }} .ft P .fi .UNINDENT .UNINDENT .sp To execute with pillar data. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt\-run state.orch orch.deploy pillar=\(aq{"servers": "newsystem1", "master": "mymaster"}\(aq .ft P .fi .UNINDENT .UNINDENT .SS Return Codes in Runner/Wheel Jobs .sp New in version 2018.3.0. .sp State (\fBsalt.state\fP) jobs are able to report failure via the state return dictionary\&. Remote execution (\fBsalt.function\fP) jobs are able to report failure by setting a \fBretcode\fP key in the \fB__context__\fP dictionary. However, runner (\fBsalt.runner\fP) and wheel (\fBsalt.wheel\fP) jobs would only report a \fBFalse\fP result when the runner/wheel function raised an exception. As of the 2018.3.0 release, it is now possible to set a retcode in runner and wheel functions just as you can do in remote execution functions. Here is some example pseudocode: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C def myrunner(): ... # do stuff ... if some_error_condition: __context__["retcode"] = 1 return result .ft P .fi .UNINDENT .UNINDENT .sp This allows a custom runner/wheel function to report its failure so that requisites can accurately tell that a job has failed. .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 \fIalways\fP executed on the master. .UNINDENT .UNINDENT .SS Parsing Results Programmatically .sp Orchestration jobs return output in a specific data structure. That data structure is represented differently depending on the outputter used. With the default outputter for orchestration, you get a nice human\-readable output. Assume the following orchestration SLS: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C good_state: salt.state: \- tgt: myminion \- sls: \- succeed_with_changes bad_state: salt.state: \- tgt: myminion \- sls: \- fail_with_changes mymod.myfunc: salt.function: \- tgt: myminion mymod.myfunc_false_result: salt.function: \- tgt: myminion .ft P .fi .UNINDENT .UNINDENT .sp Running this using the default outputter would produce output which looks like this: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C fa5944a73aa8_master: \-\-\-\-\-\-\-\-\-\- ID: good_state Function: salt.state Result: True Comment: States ran successfully. Updating myminion. Started: 21:08:02.681604 Duration: 265.565 ms Changes: myminion: \-\-\-\-\-\-\-\-\-\- ID: test succeed with changes Function: test.succeed_with_changes Result: True Comment: Success! Started: 21:08:02.835893 Duration: 0.375 ms Changes: \-\-\-\-\-\-\-\-\-\- testing: \-\-\-\-\-\-\-\-\-\- new: Something pretended to change old: Unchanged Summary for myminion \-\-\-\-\-\-\-\-\-\-\-\- Succeeded: 1 (changed=1) Failed: 0 \-\-\-\-\-\-\-\-\-\-\-\- Total states run: 1 Total run time: 0.375 ms \-\-\-\-\-\-\-\-\-\- ID: bad_state Function: salt.state Result: False Comment: Run failed on minions: myminion Started: 21:08:02.947702 Duration: 177.01 ms Changes: myminion: \-\-\-\-\-\-\-\-\-\- ID: test fail with changes Function: test.fail_with_changes Result: False Comment: Failure! Started: 21:08:03.116634 Duration: 0.502 ms Changes: \-\-\-\-\-\-\-\-\-\- testing: \-\-\-\-\-\-\-\-\-\- new: Something pretended to change old: Unchanged Summary for myminion \-\-\-\-\-\-\-\-\-\-\-\- Succeeded: 0 (changed=1) Failed: 1 \-\-\-\-\-\-\-\-\-\-\-\- Total states run: 1 Total run time: 0.502 ms \-\-\-\-\-\-\-\-\-\- ID: mymod.myfunc Function: salt.function Result: True Comment: Function ran successfully. Function mymod.myfunc ran on myminion. Started: 21:08:03.125011 Duration: 159.488 ms Changes: myminion: True \-\-\-\-\-\-\-\-\-\- ID: mymod.myfunc_false_result Function: salt.function Result: False Comment: Running function mymod.myfunc_false_result failed on minions: myminion. Function mymod.myfunc_false_result ran on myminion. Started: 21:08:03.285148 Duration: 176.787 ms Changes: myminion: False Summary for fa5944a73aa8_master \-\-\-\-\-\-\-\-\-\-\-\- Succeeded: 2 (changed=4) Failed: 2 \-\-\-\-\-\-\-\-\-\-\-\- Total states run: 4 Total run time: 778.850 ms .ft P .fi .UNINDENT .UNINDENT .sp However, using the \fBjson\fP outputter, you can get the output in an easily loadable and parsable format: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt\-run state.orchestrate test \-\-out=json .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C { "outputter": "highstate", "data": { "fa5944a73aa8_master": { "salt_|\-good_state_|\-good_state_|\-state": { "comment": "States ran successfully. Updating myminion.", "name": "good_state", "start_time": "21:35:16.868345", "result": true, "duration": 267.299, "__run_num__": 0, "__jid__": "20171130213516897392", "__sls__": "test", "changes": { "ret": { "myminion": { "test_|\-test succeed with changes_|\-test succeed with changes_|\-succeed_with_changes": { "comment": "Success!", "name": "test succeed with changes", "start_time": "21:35:17.022592", "result": true, "duration": 0.362, "__run_num__": 0, "__sls__": "succeed_with_changes", "changes": { "testing": { "new": "Something pretended to change", "old": "Unchanged" } }, "__id__": "test succeed with changes" } } }, "out": "highstate" }, "__id__": "good_state" }, "salt_|\-bad_state_|\-bad_state_|\-state": { "comment": "Run failed on minions: test", "name": "bad_state", "start_time": "21:35:17.136511", "result": false, "duration": 197.635, "__run_num__": 1, "__jid__": "20171130213517202203", "__sls__": "test", "changes": { "ret": { "myminion": { "test_|\-test fail with changes_|\-test fail with changes_|\-fail_with_changes": { "comment": "Failure!", "name": "test fail with changes", "start_time": "21:35:17.326268", "result": false, "duration": 0.509, "__run_num__": 0, "__sls__": "fail_with_changes", "changes": { "testing": { "new": "Something pretended to change", "old": "Unchanged" } }, "__id__": "test fail with changes" } } }, "out": "highstate" }, "__id__": "bad_state" }, "salt_|\-mymod.myfunc_|\-mymod.myfunc_|\-function": { "comment": "Function ran successfully. Function mymod.myfunc ran on myminion.", "name": "mymod.myfunc", "start_time": "21:35:17.334373", "result": true, "duration": 151.716, "__run_num__": 2, "__jid__": "20171130213517361706", "__sls__": "test", "changes": { "ret": { "myminion": true }, "out": "highstate" }, "__id__": "mymod.myfunc" }, "salt_|\-mymod.myfunc_false_result\-mymod.myfunc_false_result\-function": { "comment": "Running function mymod.myfunc_false_result failed on minions: myminion. Function mymod.myfunc_false_result ran on myminion.", "name": "mymod.myfunc_false_result", "start_time": "21:35:17.486625", "result": false, "duration": 174.241, "__run_num__": 3, "__jid__": "20171130213517536270", "__sls__": "test", "changes": { "ret": { "myminion": false }, "out": "highstate" }, "__id__": "mymod.myfunc_false_result" } } }, "retcode": 1 } .ft P .fi .UNINDENT .UNINDENT .sp The 2018.3.0 release includes a couple fixes to make parsing this data easier and more accurate. The first is the ability to set a \fI\%return code\fP in a custom runner or wheel function, as noted above. The second is a change to how failures are included in the return data. Prior to the 2018.3.0 release, minions that failed a \fBsalt.state\fP orchestration job would show up in the \fBcomment\fP field of the return data, in a human\-readable string that was not easily parsed. They are now included in the \fBchanges\fP dictionary alongside the minions that succeeded. In addition, \fBsalt.function\fP jobs which failed because the \fI\%fail function\fP returned \fBFalse\fP used to handle their failures in the same way \fBsalt.state\fP jobs did, and this has likewise been corrected. .SS Running States on the Master without a Minion .sp The orchestrate runner can be used to execute states on the master without using a minion. For example, assume that \fBsalt://foo.sls\fP contains the following SLS: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C /etc/foo.conf: file.managed: \- source: salt://files/foo.conf \- mode: 0600 .ft P .fi .UNINDENT .UNINDENT .sp In this case, running \fBsalt\-run state.orchestrate foo\fP would be the equivalent of running a \fBstate.sls foo\fP, but it would execute on the master only, and would not require a minion daemon to be running on the master. .sp This is not technically orchestration, but it can be useful in certain use cases. .SS Limitations .sp Only one SLS target can be run at a time using this method, while using \fBstate.sls\fP allows for multiple SLS files to be passed in a comma\-separated list. .SH SOLARIS .sp This section contains details on Solaris specific quirks and workarounds. .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 Solaris refers to both Solaris 10 compatible platforms like Solaris 10, illumos, SmartOS, OmniOS, OpenIndiana,... and Oracle Solaris 11 platforms. .UNINDENT .UNINDENT .SS Solaris\-specific Behaviour .sp Salt is capable of managing Solaris systems, however due to various differences between the operating systems, there are some things you need to keep in mind. .sp This document will contain any quirks that apply across Salt or limitations in some modules. .SS FQDN/UQDN .sp On Solaris platforms the FQDN will not always be properly detected. If an IPv6 address is configured pythons \fB\(gasocket.getfqdn()\(ga\fP fails to return a FQDN and returns the nodename instead. For a full breakdown see the following issue on github: #37027 .SS Grains .sp Not all grains are available or some have empty or 0 as value. Mostly grains that are depenend on hardware discovery like: \- num_gpus \- gpus .sp Also some resolver related grains like: \- domain \- \fI\%dns:options\fP \- \fI\%dns:sortlist\fP .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). The python version requirement is the same as that for a standard Salt installation\&. .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 \fB/etc/salt/pki/master/ssh/salt\-ssh.rsa\fP\&. The key generation happens when you run \fBsalt\-ssh\fP for the first time. .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 target hosts without Python 3 .sp The \fBsalt\-ssh\fP command requires at least python 3, which is not installed by default on some target hosts. 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 \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 \fBsalt\-ssh\fP on systems with Python 3.x .sp Salt, before the 2017.7.0 release, does not support Python 3.x which is the default on for example the popular 16.04 LTS release of Ubuntu. An easy workaround for this scenario is to use the \fB\-r\fP option similar to the example above: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt\-ssh ubuntu\-1604\-minion \-r \(aqapt update ; apt install \-y python\-minimal\(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.version .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_log_file: salt\-ssh.log 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.version\fP you can call \fBsalt\-ssh \e* test.version\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 .sp At last you can create \fB~/.salt/Saltfile\fP and \fBsalt\-ssh\fP will automatically load it by default. .SS Advanced options with salt\-ssh .sp Salt\(aqs ability to allow users to have custom grains and custom modules is also applicable to using salt\-ssh. This is done through first packing the custom grains into the thin tarball before it is deployed on the system. .sp For this to happen, the \fBconfig\fP file must be explicit enough to indicate where the custom grains are located on the machine like so: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C file_client: local file_roots: base: \- /home/user/.salt \- /home/user/.salt/_states \- /home/user/.salt/_grains module_dirs: \- /home/user/.salt pillar_roots: base: \- /home/user/.salt/_pillar root_dir: /tmp/.salt\-root .ft P .fi .UNINDENT .UNINDENT .sp It\(aqs better to be explicit rather than implicit in this situation. This will allow urls all under \fIsalt://\fP to be resolved such as \fIsalt://_grains/custom_grain.py\fP\&. .sp One can confirm this action by executing a properly setup salt\-ssh minion with \fIsalt\-ssh minion grains.items\fP\&. During this process, a \fIsaltutil.sync_all\fP is ran to discover the thin tarball and then consumed. Output similar to this indicates a successful sync with custom grains. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C local: \-\-\-\-\-\-\-\-\-\- ... executors: grains: \- grains.custom_grain log_handlers: ... .ft P .fi .UNINDENT .UNINDENT .sp This is especially important when using a custom \fIfile_roots\fP that differ from \fI/etc/salt/\fP\&. .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 Please see \fI\%https://docs.saltstack.com/en/latest/topics/grains/\fP for more information on grains and custom grains. .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 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 priv_passwd: # Passphrase for ssh private key 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) ssh_pre_flight: # Path to a script that will run before all other salt\-ssh # commands. Will only run the first time when the thin dir # does not exist, unless \-\-pre\-flight is passed to salt\-ssh # command or ssh_run_pre_flight is set to true in the config # Added in 3001 Release. set_path: # Set the path environment variable, to ensure the expected python # binary is in the salt\-ssh path, when running the command. # Example: \(aq$PATH:/usr/local/bin/\(aq. Added in 3001 Release. ssh_options: # List of options (as \(aqoption=argument\(aq) to pass to ssh. .ft P .fi .UNINDENT .UNINDENT .SS ssh_pre_flight .sp A Salt\-SSH roster option \fIssh_pre_flight\fP was added in the 3001 release. This enables you to run a script before Salt\-SSH tries to run any commands. You can set this option in the roster for a specific minion or use the \fIroster_defaults\fP to set it for all minions. This script will only run if the thin dir is not currently on the minion. This means it will only run on the first run of salt\-ssh or if you have recently wiped out your thin dir. If you want to intentionally run the script again you have a couple of options: .INDENT 0.0 .IP \(bu 2 Wipe out your thin dir by using the \-w salt\-ssh arg. .IP \(bu 2 Set ssh_run_pre_flight to True in the config .IP \(bu 2 Run salt\-ssh with the \-\-pre\-flight arg. .UNINDENT .SS Target Defaults .sp The \fIroster_defaults\fP dictionary in the master config is used to set the default login variables for minions in the roster so that the same arguments do not need to be passed with commandline arguments. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C roster_defaults: user: daniel sudo: True priv: /root/.ssh/id_rsa tty: True .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. .SS SSH Ext Alternatives .sp In the 2019.2.0 release the \fBssh_ext_alternatives\fP feature was added. This allows salt\-ssh to work across different supported python versions. You will need to ensure you have the following: .INDENT 0.0 .INDENT 3.5 .INDENT 0.0 .IP \(bu 2 Salt is installed, with all required dependnecies for the Python version. .IP \(bu 2 Everything needs to be importable from the respective Python environment. .UNINDENT .UNINDENT .UNINDENT .sp To enable using this feature you will need to edit the master configuration similar to below: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C ssh_ext_alternatives: 2019.2: # Namespace, can be anything. py\-version: [2, 7] # Constraint to specific interpreter version path: /opt/2019.2/salt # Main Salt installation directory. dependencies: # List of dependencies and their installation paths jinja2: /opt/jinja2 yaml: /opt/yaml tornado: /opt/tornado msgpack: /opt/msgpack certifi: /opt/certifi singledispatch: /opt/singledispatch.py singledispatch_helpers: /opt/singledispatch_helpers.py markupsafe: /opt/markupsafe backports_abc: /opt/backports_abc.py .ft P .fi .UNINDENT .UNINDENT .sp \fBWARNING:\fP .INDENT 0.0 .INDENT 3.5 When using Salt versions >= 3001 and Python 2 is your \fBpy\-version\fP you need to use an older version of Salt that supports Python 2. For example, if using Salt\-SSH version 3001 and you do not want to install Python 3 on your target host you can use \fBssh_ext_alternatives\fP\(aqs \fBpath\fP option. This option needs to point to a 2019.2.3 Salt installation directory on your Salt\-SSH host, which still supports Python 2. .UNINDENT .UNINDENT .SS auto_detect .sp In the 3001 release the \fBauto_detect\fP feature was added for \fBssh_ext_alternatives\fP\&. This allows salt\-ssh to automatically detect the path to all of your dependencies and does not require you to define them under \fBdependencies\fP\&. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C ssh_ext_alternatives: 2019.2: # Namespace, can be anything. py\-version: [2, 7] # Constraint to specific interpreter version path: /opt/2019.2/salt # Main Salt installation directory. auto_detect: True # Auto detect dependencies py_bin: /usr/bin/python2.7 # Python binary path used to auto detect dependencies .ft P .fi .UNINDENT .UNINDENT .sp If \fBpy_bin\fP is not set alongside \fBauto_detect\fP, it will attempt to auto detect the dependnecies using the major version set in \fBpy\-version\fP\&. For example if you have \fB[2, 7]\fP set as your \fBpy\-version\fP, it will attempt to use the binary \fBpython2\fP\&. .sp You can also use \fBauto_detect\fP and \fBdependencies\fP together. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C ssh_ext_alternatives: 2019.2: # Namespace, can be anything. py\-version: [2, 7] # Constraint to specific interpreter version path: /opt/2019.2/salt # Main Salt installation directory. auto_detect: True # Auto detect dependencies py_bin: /usr/bin/python2.7 # Python binary path to auto detect dependencies dependencies: # List of dependencies and their installation paths jinja2: /opt/jinja2 .ft P .fi .UNINDENT .UNINDENT .sp If a dependency is defined in the \fBdependecies\fP list \fBssh_ext_alternatives\fP will use this dependency, instead of the path that \fBauto_detect\fP finds. For example, if you define \fB/opt/jinja2\fP under your \fBdependencies\fP for jinja2, it will not try to autodetect the file path to the jinja2 module, and will favor \fB/opt/jinja2\fP\&. .SS Different Python Versions .sp The 3001 release removed python 2 support in Salt. Even though this python 2 support is being dropped we have provided multiple ways to work around this with Salt\-SSH. You can use the following options: .INDENT 0.0 .INDENT 3.5 .INDENT 0.0 .IP \(bu 2 ssh_pre_flight .IP \(bu 2 Using the Salt\-SSH raw shell calls to install Python3. .IP \(bu 2 Use an older version of Salt on the target host that still supports Python 2 using the feature SSH ext alternatives .UNINDENT .UNINDENT .UNINDENT .SH THORIUM COMPLEX REACTOR .sp The original Salt Reactor is based on the idea of listening for a specific event and then reacting to it. This model comes with many logical limitations, for instance it is very difficult (and hacky) to fire a reaction based on aggregate data or based on multiple events. .sp The Thorium reactor is intended to alleviate this problem in a very elegant way. Instead of using extensive jinja routines or complex python sls files the aggregation of data and the determination of what should run becomes isolated to the sls data logic, makes the definitions much cleaner. .SS Starting the Thorium Engine .sp To enable the thorium engine add the following configuration to the engines section of your Salt Master or Minion configuration file and restart the daemon: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C engines: \- thorium: {} .ft P .fi .UNINDENT .UNINDENT .SS Thorium Modules .sp Because of its specialized nature, Thorium uses its own set of modules. However, many of these modules are designed to wrap the more commonly\-used Salt subsystems. These modules are: .INDENT 0.0 .IP \(bu 2 local: Execution modules .IP \(bu 2 runner: Runner modules .IP \(bu 2 wheel: Wheel modules .UNINDENT .sp There are other modules that ship with Thorium as well. Some of these will be highlighted later in this document. .SS Writing Thorium Formulas .sp Like some other Salt subsystems, Thorium uses its own directory structure. The default location for this structure is \fB/srv/thorium/\fP, but it can be changed using the \fBthorium_roots\fP setting in the \fBmaster\fP configuration file. .sp This would explicitly set the roots to the default: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C thorium_roots: base: \- /srv/thorium .ft P .fi .UNINDENT .UNINDENT .sp Example \fBthorium_roots\fP configuration: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C thorium_roots: base: \- /etc/salt/thorium .ft P .fi .UNINDENT .UNINDENT .sp It is also possible to use gitfs with Thorium, using the \fBthoriumenv\fP or \fBthorium_top\fP settings. .sp Example using \fBthorium_top\fP: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C thorium_top: salt://thorium/top.sls gitfs_provider: pygit2 gitfs_remotes: \- git@github.com:user/repo.git: \- name: salt\-backend \- root: salt \- base: master \- git@github.com:user/repo.git: \- name: thorium\-backend \- root: thorium \- base: master \- mountpoint: salt://thorium .ft P .fi .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 When using this method don\(aqt forget to prepend the mountpoint to files served by this repo, for example \fBtop.sls\fP: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C base: \(aq*\(aq: \- thorium.key_clean .ft P .fi .UNINDENT .UNINDENT .UNINDENT .UNINDENT .sp Example using \fBthoriumenv\fP: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C thoriumenv: thorium gitfs_provider: pygit2 gitfs_remotes: \- git@github.com:user/repo.git: \- name: salt\-backend \- root: salt \- base: master \- git@github.com:user/repo.git: \- name: thorium\-backend \- root: thorium \- saltenv: \- thorium: \- ref: master .ft P .fi .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 When using this method all state will run under the defined environment, for example \fBtop.sls\fP: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C thorium: \(aq*\(aq: \- key_clean .ft P .fi .UNINDENT .UNINDENT .UNINDENT .UNINDENT .SS The Thorium top.sls File .sp Thorium uses its own \fBtop.sls\fP file, which follows the same convention as is found in \fB/srv/salt/\fP: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C : : \- \- \- .ft P .fi .UNINDENT .UNINDENT .sp For instance, a \fBtop.sls\fP using a standard \fBbase\fP environment and a single Thorium formula called \fBkey_clean\fP, would look like: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C base: \(aq*\(aq: \- key_clean .ft P .fi .UNINDENT .UNINDENT .sp Take note that the target in a Thorium \fBtop.sls\fP is not used; it only exists to follow the same convention as other \fBtop.sls\fP files. Leave this set to \fB\(aq*\(aq\fP in your own Thorium \fBtop.sls\fP\&. .SS Thorium Formula Files .sp Thorium SLS files are processed by the same state compiler that processes Salt state files. This means that features like requisites, templates, and so on are available. .sp Let\(aqs take a look at an example, and then discuss each component of it. This formula uses Thorium to detect when a minion has disappeared and then deletes the key from the master when the minion has been gone for 60 seconds: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C statreg: status.reg keydel: key.timeout: \- delete: 60 \- require: \- status: statreg .ft P .fi .UNINDENT .UNINDENT .sp There are two stanzas in this formula, whose IDs are \fBstatreg\fP and \fBkeydel\fP\&. The first stanza, \fBstatreg\fP, tells Thorium to keep track of minion status beacons in its \fIregister\fP\&. We\(aqll talk more about the register in a moment. .sp The second stanza, \fBkeydel\fP, is the one that does the real work. It uses the \fBkey\fP module to apply an expiration (using the \fBtimeout\fP function) to a minion. Because \fBdelete\fP is set to \fB60\fP, this is a 60 second expiration. If a minion does not check in at least once every 60 seconds, its key will be deleted from the master. This particular function also allows you to use \fBreject\fP instead of \fBdelete\fP, allowing for a minion to be rejected instead of deleted if it does not check in within the specified time period. .sp There is also a \fBrequire\fP requisite in this stanza. It states that the \fBkey.timeout\fP function will not be called unless the \fBstatus.reg\fP function in the \fBstatreg\fP codeblock has been successfully called first. .SS Thorium Links to Beacons .sp The above example was added in the 2016.11.0 release of Salt and makes use of the \fBstatus\fP beacon also added in the 2016.11.0 release. For the above Thorium state to function properly you will also need to enable the \fBstatus\fP beacon in the \fBminion\fP configuration file: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C beacons: status: \- interval: 10 .ft P .fi .UNINDENT .UNINDENT .sp This will cause the minion to use the status beacon to check in with the master every 10 seconds. .SS The Thorium Register .sp In order to keep track of information, Thorium uses an in\-memory register (or rather, collection of registers) on the master. These registers are only populated when told to by a formula, and they normally will be erased when the master is restarted. It is possible to persist the registers to disk, but we\(aqll get to that in a moment. .sp The example above uses \fBstatus.reg\fP to populate a register for you, which is automatically used by the \fBkey.timeout\fP function. However, you can set your own register values as well, using the \fBreg\fP module. .sp Because Thorium watches the event bus, the \fBreg\fP module is designed to look for user\-specified tags, and then extract data from the payload of events that match those tags. For instance, the following stanza will look for an event with a tag of \fBmy/custom/event\fP: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C foo: reg.list: \- add: bar \- match: my/custom/event .ft P .fi .UNINDENT .UNINDENT .sp When such an event is found, the data found in the payload dictionary key of \fBbar\fP will be stored in a register called \fBfoo\fP\&. This register will store that data in a \fBlist\fP\&. You may also use \fBreg.set\fP to add data to a \fBset()\fP instead. .sp If you would like to see a copy of the register as it is stored in memory, you can use the \fBfile.save\fP function: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C myreg: file.save .ft P .fi .UNINDENT .UNINDENT .sp In this case, each time the register is updated, a copy will be saved in JSON format at \fB/var/cache/salt/master/thorium/saves/myreg\fP\&. If you would like to see when particular events are added to a list\-type register, you may add a \fBstamp\fP option to \fBreg.list\fP (but not \fBreg.set\fP). With the above two stanzas put together, this would look like: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C foo: reg.list: \- add: bar \- match: my/custom/event \- stamp: True myreg: file.save .ft P .fi .UNINDENT .UNINDENT .sp If you would like to only keep a certain number of the most recent register entries, you may also add a \fBprune\fP option to \fBreg.list\fP (but not \fBreg.set\fP): .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C foo: reg.list: \- add: bar \- match: my/custom/event \- stamp: True \- prune: 50 .ft P .fi .UNINDENT .UNINDENT .sp This example will only keep the 50 most recent entries in the \fBfoo\fP register. .SS Using Register Data .sp Putting data in a register is useless if you don\(aqt do anything with it. The \fBcheck\fP module is designed to examine register data and determine whether it matches the given parameters. For instance, the \fBcheck.contains\fP function will return \fBTrue\fP if the given \fBvalue\fP is contained in the specified register: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C foo: reg.list: \- add: bar \- match: my/custom/event \- stamp: True \- prune: 50 check.contains: \- value: somedata .ft P .fi .UNINDENT .UNINDENT .sp Used with a \fBrequire\fP requisite, we can call one of the wrapper modules and perform an operation. For example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C shell_test: local.cmd: \- tgt: dufresne \- func: cmd.run \- arg: \- echo \(aqthorium success\(aq > /tmp/thorium.txt \- require: \- check: foo .ft P .fi .UNINDENT .UNINDENT .sp This stanza will only run if the \fBcheck.contains\fP function under the \fBfoo\fP ID returns true (meaning the match was found). .sp There are a number of other functions in the \fBcheck\fP module which use different means of comparing values: .INDENT 0.0 .IP \(bu 2 \fBgt\fP: Check whether the register entry is greater than the given value .IP \(bu 2 \fBgte\fP: Check whether the register entry is greater than or equal to the given value .IP \(bu 2 \fBlt\fP: Check whether the register entry is less than the given value .IP \(bu 2 \fBlte\fP: Check whether the register entry is less than or equal to the given value .IP \(bu 2 \fBeq\fP: Check whether the register entry is equal to the given value .IP \(bu 2 \fBne\fP: Check whether the register entry is not equal to the given value .UNINDENT .sp There is also a function called \fBcheck.event\fP which does not examine the register. Instead, it looks directly at an event as it is coming in on the event bus, and returns \fBTrue\fP if that event\(aqs tag matches. For example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt/foo/*/bar: check.event run_remote_ex: local.cmd: \- tgt: \(aq*\(aq \- func: test.version \- require: \- check: salt/foo/*/bar .ft P .fi .UNINDENT .UNINDENT .sp This formula will look for an event whose tag is \fBsalt/foo//bar\fP and if it comes in, issue a \fBtest.version\fP to all minions. .SS Register Persistence .sp It is possible to persist the register data to disk when a master is stopped gracefully, and reload it from disk when the master starts up again. This functionality is provided by the returner subsystem, and is enabled whenever any returner containing a \fBload_reg\fP and a \fBsave_reg\fP function is used. .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 VM Profiles\&. .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 Alternatively, the \fB\-L\fP option can be passed to the \fI\%Salt Bootstrap\fP script when installing Salt. The \fB\-L\fP option will install \fBsalt\-cloud\fP and the required \fBlibcloud\fP package. .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 \fBdigitalocean\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, such as "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, such as "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, such as "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 \fBhighstate\fP, \fBjson\fP, \fBkey\fP, \fBoverstatestage\fP, \fBpprint\fP, \fBraw\fP, \fBtxt\fP, \fByaml\fP, and many others\&. .UNINDENT .UNINDENT .sp Some outputters are formatted only for data returned from specific functions. 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. .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 \-\-out\-file\-append, \-\-output\-file\-append Append 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 .INDENT 0.0 .TP .B \-\-state\-output=STATE_OUTPUT, \-\-state_output=STATE_OUTPUT Override the configured state_output value for minion output. One of \(aqfull\(aq, \(aqterse\(aq, \(aqmixed\(aq, \(aqchanges\(aq or \(aqfilter\(aq. Default: \(aqnone\(aq. .UNINDENT .INDENT 0.0 .TP .B \-\-state\-verbose=STATE_VERBOSE, \-\-state_verbose=STATE_VERBOSE Override the configured state_verbose value for minion output. Set to True or False. Default: none. .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 Any top level data element from your profile may be overridden in the map file: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C fedora_small: \- web1: size: t2.micro \- web2: size: t2.nano .ft P .fi .UNINDENT .UNINDENT .sp As of Salt 2017.7.0, nested elements are merged, and can can be specified individually without having to repeat the complete definition for each top level data element. In this example a separate MAC is assigned to each VMware instance while inheriting device parameters for for disk and network configuration: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C nyc\-vm: \- db1: devices: network: Network Adapter 1: mac: \(aq44:44:44:44:44:41\(aq \- db2: devices: network: Network Adapter 1: mac: \(aq44:44:44:44:44:42\(aq .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 Requiring Other Instances .sp The \fBrequires\fP directive can be used in map files to ensure that one instance is created and available before another is created. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C fedora_high: \- db1: size: m5.xlarge \- web1: size: m5.large requires: \- db1 .ft P .fi .UNINDENT .UNINDENT .sp This requisite is passed to the instance definition dicitonary in a map file and accepts a list of instance names as defined in the map. .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 Using Direct Map Data .sp When using modules that access the \fBCloudClient\fP directly (notably, the \fBcloud\fP execution and runner modules), it is possible to pass in the contents of a map file, rather than a path to the location of the map file. .sp Normally when using these modules, the path to the map file is passed in using: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt\-run cloud.map_run /path/to/cloud.map .ft P .fi .UNINDENT .UNINDENT .sp To pass in the actual map data, use the \fBmap_data\fP argument: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt\-run cloud.map_run map_data=\(aq{"centos7": [{"saltmaster": {"minion": \e {"transport": "tcp"}, "make_master": true, "master": {"transport": \e "tcp"}}}, {"minion001": {"minion": {"transport": "tcp"}}}]}\(aq .ft P .fi .UNINDENT .UNINDENT .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 an example list of actions currently supported by \fBsalt\-cloud\fP: .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 \fBsalt\-cloud\fP actions is the 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 \fBsalt\-cloud\fP 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, profile or map configuration files: .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 .sp When salt cloud creates a new minion, it can automatically add grain information to the minion configuration file identifying the sources originally used to define it. .sp The generated grain information will appear similar to: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C grains: salt\-cloud: driver: ec2 provider: my_ec2:ec2 profile: ec2\-web .ft P .fi .UNINDENT .UNINDENT .sp The generation of the salt\-cloud grain can be suppressed by the option \fBenable_cloud_grains: \(aqFalse\(aq\fP in the cloud configuration file. .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/\fP should not specify the \fBproviders\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, provider, and map 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 providers: my\-openstack: driver: openstack region_name: ORD cloud: mycloud profiles: ubuntu\-openstack: provider: my\-openstack size: ds512M image: CentOS 7 script_args: git develop maps: my\-dev\-map: ubuntu\-openstack: \- dev\-test01 \- dev\-test02 \- dev\-test03 \- dev\-test04 my\-prd\-map: ubuntu\-openstack: \- prd\-web01 \- prd\-web02 minion: id: custom\-minion\-id\-app1\-stack1\-frontend grains: roles: \- webserver deployment: datacenter4\-openstack \- prod\-db01 \- prod\-db02 .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 Using Salt for OpenStack uses the \fIshade \fP driver managed by the openstack\-infra team. .sp This driver can be configured using the \fB/etc/openstack/clouds.yml\fP file with \fIos\-client\-config \fP .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C myopenstack: driver: openstack region_name: RegionOne cloud: mycloud .ft P .fi .UNINDENT .UNINDENT .sp Or by just configuring the same auth block directly in the cloud provider config. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C myopenstack: driver: openstack region_name: RegionOne auth: username: \(aqdemo\(aq password: secret project_name: \(aqdemo\(aq auth_url: \(aqhttp://openstack/identity\(aq .ft P .fi .UNINDENT .UNINDENT .sp Both of these methods support using the \fIvendor \fP options. .sp For more information, look at \fBOpenstack Cloud Driver Docs\fP .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: digitalocean 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 Getting Started with Saltify documentation. .SS Vagrant .sp The Vagrant driver is a new, experimental driver for controlling a VagrantBox virtual machine, and installing Salt on it. The target host machine must be a working salt minion, which is controlled via the salt master using salt\-api. For more information, see Getting Started With Vagrant\&. .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 [ { "deploy": False, "image": "ami\-08d97e61", "profile": "Fedora\-17", "provider": "my\-ec2\-config", "securitygroup": ["default"], "size": "t1.micro", "ssh_username": "ec2_user", }, { "deploy": False, "image": "ami\-09b61d60", "profile": "CentOS\-5", "provider": "my\-aws\-config", "securitygroup": ["default"], "size": "t1.micro", "ssh_username": "ec2_user", }, { "deploy": False, "image": "ami\-54cf5c3d", "profile": "Amazon\-Linux\-AMI\-2012.09\-64bit", "provider": "my\-ec2\-config", "securitygroup": ["default"], "size": "t1.micro", "ssh_username": "ec2_user", }, { "deploy": False, "profile": "development\-instances", "provider": "my\-ec2\-config", "securitygroup": ["default"], "size": "t1.micro", "ssh_username": "ec2_user", }, ] .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 { "providers": { "my\-develop\-envs": [ { "availability_zone": "ap\-southeast\-1b", "id": "HJGRYCILJLKJYG", "key": "kdjgfsgm;woormgl/aserigjksjdhasdfgn", "keyname": "test", "location": "ap\-southeast\-1", "private_key": "/root/test.pem", "driver": "aws", "securitygroup": "quick\-start", }, { "location": "Raleigh", "password": "mypass", "driver": "ibmsce", "ssh_key_file": "/etc/salt/ibm/mykey.pem", "ssh_key_name": "mykey", "user": "myuser@mycorp.com", }, ], "my\-productions\-envs": [ { "availability_zone": "us\-east\-1", "location": "us\-east\-1", "password": "mypass", "driver": "ibmsce", "ssh_key_file": "/etc/salt/ibm/mykey.pem", "ssh_key_name": "mykey", "user": "my\-production\-user@mycorp.com", } ], } } .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 \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 Support \fBwinexe\fP and \fBimpacket\fP has been deprecated and will be removed in 3001. These dependencies are replaced by \fBpypsexec\fP and \fBsmbprotocol\fP respectivly. These are pure python alternatives that are compatible with all supported python versions. .UNINDENT .UNINDENT .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 .INDENT 0.0 .IP \(bu 2 \fI\%pypsexec project home\fP .UNINDENT .INDENT 0.0 .IP \(bu 2 \fI\%smbprotocol project home\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 Self Signed Certificates with WinRM .sp Salt\-Cloud can use versions of \fBpywinrm<=0.1.1\fP or \fBpywinrm>=0.2.1\fP\&. .sp For versions greater than \fI0.2.1\fP, \fBwinrm_verify_ssl\fP needs to be set to \fIFalse\fP if the certificate is self signed and not verifiable. .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 my\-ec2\-config: # Pass userdata to the instance to be created userdata_file: /etc/salt/windows\-firewall.ps1 .ft P .fi .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 From versions 2016.11.0 and 2016.11.3, this file was passed through the master\(aqs \fBrenderer\fP to template it. However, this caused issues with non\-YAML data, so templating is no longer performed by default. To template the userdata_file, add a \fBuserdata_template\fP option to the cloud profile: .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/windows\-firewall.ps1 userdata_template: jinja .ft P .fi .UNINDENT .UNINDENT .sp If no \fBuserdata_template\fP is set in the cloud profile, then the master configuration will be checked for a \fBuserdata_template\fP value. If this is not set, then no templating will be performed on the userdata_file. .sp To disable templating in a cloud profile when a \fBuserdata_template\fP has been set in the master configuration file, simply set \fBuserdata_template\fP to \fBFalse\fP in the cloud profile: .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/windows\-firewall.ps1 userdata_template: False .ft P .fi .UNINDENT .UNINDENT .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{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). And \fBwinrm_verify_ssl\fP can be set to \fIFalse\fP to use a self signed certificate. .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 .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.version .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 generation 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\%azure\fP >= 2.0.0rc6 .IP \(bu 2 \fI\%azure\-common\fP >= 1.1.4 .IP \(bu 2 \fI\%azure\-mgmt\fP >= 0.30.0rc6 .IP \(bu 2 \fI\%azure\-mgmt\-compute\fP >= 0.33.0 .IP \(bu 2 \fI\%azure\-mgmt\-network\fP >= 0.30.0rc6 .IP \(bu 2 \fI\%azure\-mgmt\-resource\fP >= 0.30.0 .IP \(bu 2 \fI\%azure\-mgmt\-storage\fP >= 0.30.0rc6 .IP \(bu 2 \fI\%azure\-mgmt\-web\fP >= 0.30.0rc6 .IP \(bu 2 \fI\%azure\-storage\fP >= 0.32.0 .IP \(bu 2 \fI\%msrestazure\fP >= 0.4.21 .IP \(bu 2 A Microsoft Azure account .IP \(bu 2 \fI\%Salt\fP .UNINDENT .SS Installation Tips .sp Because the \fBazure\fP library requires the \fBcryptography\fP library, which is compiled on\-the\-fly by \fBpip\fP, you may need to install the development tools for your operating system. .sp Before you install \fBazure\fP with \fBpip\fP, you should make sure that the required libraries are installed. .SS Debian .sp For Debian and Ubuntu, the following command will ensure that the required dependencies are installed: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C sudo apt\-get install build\-essential libssl\-dev libffi\-dev python\-dev .ft P .fi .UNINDENT .UNINDENT .SS Red Hat .sp For Fedora and RHEL\-derivatives, the following command will ensure that the required dependencies are installed: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C sudo yum install gcc libffi\-devel python\-devel openssl\-devel .ft P .fi .UNINDENT .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: salt.example.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 custom data\(aq expire_publisher_cache: 604800 # 7 days expire_offer_cache: 518400 # 6 days expire_sku_cache: 432000 # 5 days expire_version_cache: 345600 # 4 days expire_group_cache: 14400 # 4 hours expire_interface_cache: 3600 # 1 hour expire_network_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\-pass: 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\-ubuntu\-key: provider: my\-azure\-config image: Canonical|UbuntuServer|14.04.5\-LTS|14.04.201612050 size: Standard_D1_v2 location: eastus ssh_username: azureuser ssh_publickeyfile: /path/to/ssh_public_key.pub 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.version .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 or resource ID path 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 .sp or: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C /subscriptions/XXXXXXXX\-XXXX\-XXXX\-XXXX\-XXXXXXXXXXXX/resourceGroups/myRG/providers/Microsoft.Compute/images/myImage .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 admin user to add on the instance. It is also used to log into the newly\-created VM to install Salt. .SS ssh_keyfile .sp Required if using SSH key authentication. The path on the Salt master to the SSH private key used during the minion bootstrap process. .SS ssh_publickeyfile .sp Use either \fBssh_publickeyfile\fP or \fBssh_password\fP\&. The path on the Salt master to the SSH public key which will be pushed to the Linux VM. .SS ssh_password .sp Use either \fBssh_publickeyfile\fP or \fBssh_password\fP\&. The password for the admin user on the newly\-created Linux virtual machine. .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 win_installer .sp Required for Windows. The path to the Salt installer to be uploaded. .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 virtual network in this resource group, rather than the parent resource group of the instance. The VM interfaces and IPs will remain in the configured \fBresource_group\fP with the VM. .SS network .sp Required. The virtual network that the VM will be spun up in. .SS subnet .sp Optional. The subnet inside the virtual network that the VM will be spun up in. Default is \fBdefault\fP\&. .SS allocate_public_ip .sp Optional. Default is \fBFalse\fP\&. If set to \fBTrue\fP, a public IP will be created and assigned to the VM. .SS load_balancer .sp Optional. The load\-balancer for the VM\(aqs network interface to join. If specified the backend_pool option need to be set. .SS backend_pool .sp Optional. Required if the load_balancer option is set. The load\-balancer\(aqs Backend Pool the VM\(aqs network interface will join. .SS iface_name .sp Optional. The name to apply to the VM\(aqs network interface. If not supplied, the value will be set to \fB\-iface0\fP\&. .SS dns_servers .sp Optional. A \fBlist\fP of the DNS servers to configure for the network interface (will be set on the VM by the DHCP of the VNET). .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C my\-azurearm\-profile: provider: azurearm\-provider network: mynetwork dns_servers: \- 10.1.1.4 \- 10.1.1.5 .ft P .fi .UNINDENT .UNINDENT .SS availability_set .sp Optional. If set, the VM will be added to the specified availability set. .SS volumes .sp Optional. A list of dictionaries describing data disks to attach to the instance can be specified using this setting. The data disk dictionaries are passed entirely to the \fI\%Azure DataDisk object\fP, so ad\-hoc options can be handled as long as they are valid properties of the object. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C volumes: \- disk_size_gb: 50 caching: ReadWrite \- disk_size_gb: 100 caching: ReadWrite managed_disk: storage_account_type: Standard_LRS .ft P .fi .UNINDENT .UNINDENT .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 userdata .sp Optional. 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. This will be ignored if the \fBuserdata_file\fP is specified. .SS userdata_file .sp Optional. The path to a file to be read and submitted to Azure as user data. How this is used depends on the operating system that is being deployed. If used, any \fBuserdata\fP setting will be ignored. .SS userdata_sendkeys .sp Optional. Set to \fBTrue\fP in order to generate salt minion keys and provide them as variables to the userdata script when running it through the template renderer. The keys can be referenced as \fB{{opts[\(aqpriv_key\(aq]}}\fP and \fB{{opts[\(aqpub_key\(aq]}}\fP\&. .SS userdata_template .sp Optional. Enter the renderer, such as \fBjinja\fP, to be used for the userdata script template. .SS wait_for_ip_timeout .sp Optional. Default is \fB600\fP\&. When waiting for a VM to be created, Salt Cloud will attempt to connect to the VM\(aqs IP address until it starts responding. This setting specifies the maximum time to wait for a response. .SS wait_for_ip_interval .sp Optional. Default is \fB10\fP\&. How long to wait between attempts to connect to the VM\(aqs IP. .SS wait_for_ip_interval_multiplier .sp Optional. Default is \fB1\fP\&. Increase the interval by this multiplier after each request; helps with throttling. .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 \fB518400\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 \fB518400\fP seconds (6 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 \fB432000\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 \fB432000\fP seconds (5 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 \fB345600\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 \fB345600\fP seconds (4 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 \fB14400\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 \fB14400\fP seconds (4 hours). 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 Other Options .sp Other options relevant to Azure ARM. .SS storage_account .sp Required for actions involving an Azure storage account. .SS storage_key .sp Required for actions involving an Azure storage account. .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 CloudStack .sp CloudStack 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 CloudStack instances. .SS Dependencies .INDENT 0.0 .IP \(bu 2 Libcloud >= 0.13.2 .UNINDENT .SS Configuration .sp Using Salt for CloudStack, requires an \fBAPI key\fP and a \fBsecret key\fP along with the API address endpoint information. .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. exoscale: driver: cloudstack host: api.exoscale.com path: /compute apikey: EXOAPIKEY secretkey: EXOSECRETKEYINYOURACCOUNT .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 exoscale\-ubuntu: provider: exoscale\-config image: Linux Ubuntu 18.04 size: Small location: ch\-gva\-2 ssh_username: ubuntu .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 exoscale\-config exoscale: \-\-\-\-\-\-\-\-\-\- cloudstack: \-\-\-\-\-\-\-\-\-\- ch\-dk\-2: \-\-\-\-\-\-\-\-\-\- country: Unknown driver: id: 91e5e9e4\-c9ed\-4b76\-bee4\-427004b3baf9 name: ch\-dk\-2 ch\-gva\-2: \-\-\-\-\-\-\-\-\-\- country: Unknown driver: id: 1128bd56\-b4d9\-4ac6\-a7b9\-c715b187ce11 name: ch\-gva\-2 .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 exoscale exoscale: \-\-\-\-\-\-\-\-\-\- cloudstack: \-\-\-\-\-\-\-\-\-\- Extra\-large: \-\-\-\-\-\-\-\-\-\- bandwidth: 0 disk: 0 driver: extra: \-\-\-\-\-\-\-\-\-\- cpu: 4 get_uuid: id: 350dc5ea\-fe6d\-42ba\-b6c0\-efb8b75617ad name: Extra\-large price: 0 ram: 16384 uuid: edb4cd4ae14bbf152d451b30c4b417ab095a5bfe \&...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 exoscale exoscale: \-\-\-\-\-\-\-\-\-\- cloudstack: \-\-\-\-\-\-\-\-\-\- Linux CentOS 6.6 64\-bit: \-\-\-\-\-\-\-\-\-\- driver: extra: \-\-\-\-\-\-\-\-\-\- displaytext: Linux CentOS 6.6 64\-bit 10G Disk (2014\-12\-01\-bac8e0) format: QCOW2 hypervisor: KVM os: Other PV (64\-bit) size: 10737418240 get_uuid: id: aa69ae64\-1ea9\-40af\-8824\-c2c3344e8d7c name: Linux CentOS 6.6 64\-bit uuid: f26b4f54ec8591abdb6b5feb3b58f720aa438fee \&...SNIP... .ft P .fi .UNINDENT .UNINDENT .SS CloudStack specific settings .SS securitygroup .sp New in version 2017.7.0. .sp You can specify a list of security groups (by name or id) that should be assigned to the VM: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C exoscale: provider: cloudstack securitygroup: \- default \- salt\-master .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: digitalocean 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 userdata_file: /etc/salt/cloud.userdata.d/setup tags: \- tag1 \- tag2 \- tag3 .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: \-\-\-\-\-\-\-\-\-\- digitalocean: \-\-\-\-\-\-\-\-\-\- 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: \-\-\-\-\-\-\-\-\-\- digitalocean: \-\-\-\-\-\-\-\-\-\- 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: \-\-\-\-\-\-\-\-\-\- digitalocean: \-\-\-\-\-\-\-\-\-\- 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 DigitalOcean, 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 userdata_file .sp New in version 2016.11.6. .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 my\-openstack\-config: # Pass userdata to the instance to be created userdata_file: /etc/salt/cloud\-init/packages.yml .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C my\-do\-config: # Pass userdata to the instance to be created userdata_file: /etc/salt/cloud\-init/packages.yml userdata_template: jinja .ft P .fi .UNINDENT .UNINDENT .sp If no \fBuserdata_template\fP is set in the cloud profile, then the master configuration will be checked for a \fBuserdata_template\fP value. If this is not set, then no templating will be performed on the userdata_file. .sp To disable templating in a cloud profile when a \fBuserdata_template\fP has been set in the master configuration file, simply set \fBuserdata_template\fP to \fBFalse\fP in the cloud profile: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C my\-do\-config: # Pass userdata to the instance to be created userdata_file: /etc/salt/cloud\-init/packages.yml userdata_template: False .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 API , SaltStack provides a wrapper on top of this API with common methods with other IaaS solutions and Public cloud providers. Therefore, you can 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 In version 2015.8.0, 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 # If \(aqrole_arn\(aq is specified the above credentials are used to # to assume to the role. By default, role_arn is set to None. role_arn: arn:aws:iam::012345678910:role/SomeRoleName # Make sure this key is owned by corresponding user (default \(aqsalt\(aq) 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 # Debian \-> admin # 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_vols_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.version .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 \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 From versions 2016.11.0 and 2016.11.3, this file was passed through the master\(aqs \fBrenderer\fP to template it. However, this caused issues with non\-YAML data, so templating is no longer performed by default. To template the userdata_file, add a \fBuserdata_template\fP option to the cloud profile: .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 userdata_template: jinja .ft P .fi .UNINDENT .UNINDENT .sp If no \fBuserdata_template\fP is set in the cloud profile, then the master configuration will be checked for a \fBuserdata_template\fP value. If this is not set, then no templating will be performed on the userdata_file. .sp To disable templating in a cloud profile when a \fBuserdata_template\fP has been set in the master configuration file, simply set \fBuserdata_template\fP to \fBFalse\fP in the cloud profile: .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 userdata_template: False .ft P .fi .UNINDENT .UNINDENT .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 You can optionally specify tags to apply to the EC2 spot instance request. A spot instance request itself is an object in AWS. The following example will set two tags on the spot instance request. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C my\-ec2\-config: spot_config: spot_price: 0.10 tag: tag0: value tag1: value .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 you 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 Tagging of block devices can be set on a per device basis. For example, you may have multiple devices defined in your block_device_mappings structure. You have the option to set tags on any of one device or all of them as shown in 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 tag: tag0: myserver tag1: value \- DeviceName: /dev/sdb Ebs.VolumeType: gp2 Ebs.VolumeSize: 3001 tag: tagX: value tagY: value .ft P .fi .UNINDENT .UNINDENT .sp You can configure any AWS valid tag name as shown in the above example, including \(aqName\(aq. If you do not configure the tag \(aqName\(aq, it will be automatically created with a value set to the virtual machine name. If you configure the tag \(aqName\(aq, the value you configure will be used rather than defaulting to the virtual machine name as shown in 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 tag: Name: myserver tag0: value tag1: value \- DeviceName: /dev/sdb Ebs.VolumeType: gp2 Ebs.VolumeSize: 3001 tag: Name: customvalue tagX: value tagY: value .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 tags=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 .sp NOTE: If \fBimage\fP of a profile does not start with \fBami\-\fP, latest image with that name will be used. For example, to create a CentOS 7 profile, instead of using the AMI like \fBimage: ami\-1caef165\fP, we can use its name like \fBimage: \(aqCentOS Linux 7 x86_64 HVM EBS ENA 1803_01\(aq\fP\&. We can also use a pattern like below to get the latest CentOS 7: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C profile\-id: provider: provider\-name subnetid: subnet\-XXXXXXXX image: \(aqCentOS Linux 7 x86_64 HVM EBS *\(aq size: m1.medium ssh_username: centos securitygroupid: \- sg\-XXXXXXXX securitygroupname: \- AnotherSecurityGroup \- AndThirdSecurityGroup .ft P .fi .UNINDENT .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 together 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 \- DeviceIndex: 1 subnetname: XXXXXXXX\-Subnet securitygroupname: \- XXXXXXXX\-SecurityGroup \- YYYYYYYY\-SecurityGroup .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 >= 1.0.0 .UNINDENT .sp Changed in version 2017.7.0. .INDENT 0.0 .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 Empty strings as values for \fBservice_account_private_key\fP and \fBservice_account_email_address\fP can be used on GCE instances. This will result in the service account assigned to the GCE instance being used. .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 subnetwork: 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.version .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 subnetwork: 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 subnetwork .sp Use this setting to define the subnetwork an instance will be created in. This requires that the network your instance is created under has a mode of \(aqcustom\(aq or \(aqauto\(aq. Additionally, the subnetwork your instance is created under is associated with the location you provide. .sp New in version 2017.7.0. .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 subnetwork: 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 if they don\(aqt have a \(aqmode\(aq. Optionally, \(aqmode\(aq can be provided. Supported modes are \(aqauto\(aq, \(aqcustom\(aq, \(aqlegacy\(aq. Optionally, \(aqdescription\(aq can be provided to add an extra note to your network. 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 salt\-cloud \-f create_network gce name=mynet mode=auto description=some optional info. .ft P .fi .UNINDENT .UNINDENT .sp Changed in version 2017.7.0. .SS Destroy network .sp Destroy a network by specifying the name. If a resource is currently using the target network an exception will be raised. .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 subnetwork .sp New subnetworks require a name, region, and CIDR range. Optionally, \(aqdescription\(aq can be provided to add an extra note to your subnetwork. New instances can be created and added to this subnetwork by setting the subnetwork name during create. It is not possible to add/remove existing instances to a subnetwork. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-f create_subnetwork gce name=mynet network=mynet region=us\-central1 cidr=10.0.10.0/24 salt\-cloud \-f create_subnetwork gce name=mynet network=mynet region=us\-central1 cidr=10.10.10.0/24 description=some info about my subnet. .ft P .fi .UNINDENT .UNINDENT .sp New in version 2017.7.0. .SS Destroy subnetwork .sp Destroy a subnetwork by specifying the name and region. If a resource is currently using the target subnetwork an exception will be raised. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-f delete_subnetwork gce name=mynet region=us\-central1 .ft P .fi .UNINDENT .UNINDENT .sp New in version 2017.7.0. .SS Show subnetwork .sp Specify the subnetwork name to view information about the subnetwork. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-f show_subnetwork gce name=mynet .ft P .fi .UNINDENT .UNINDENT .sp New in version 2017.7.0. .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 configuration 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 Libvirt .sp Libvirt is a toolkit to interact with the virtualization capabilities of recent versions of Linux (and other OSes). This driver Salt cloud provider is currently geared towards libvirt with qemu\-kvm. .sp \fI\%https://libvirt.org/\fP .SS Host Dependencies .INDENT 0.0 .IP \(bu 2 libvirt >= 1.2.18 (older might work) .UNINDENT .SS Salt\-Cloud Dependencies .INDENT 0.0 .IP \(bu 2 libvirt\-python .UNINDENT .SS Provider Configuration .sp For every KVM host a provider needs to be set up. The provider currently maps to one libvirt daemon (e.g. one KVM host). .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 # Set up a provider with qemu+ssh protocol kvm\-via\-ssh: driver: libvirt url: qemu+ssh://user@kvm.company.com/system?socket=/var/run/libvirt/libvirt\-sock # Or connect to a local libvirt instance local\-kvm: driver: libvirt url: qemu:///system # work around flag for XML validation errors while cloning validate_xml: no .ft P .fi .UNINDENT .UNINDENT .SS Cloud Profiles .sp Virtual machines get cloned from so called Cloud Profiles. Profiles can be set up at \fB/etc/salt/cloud.profiles\fP or \fB/etc/salt/cloud.profiles.d/*.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 centos7: # points back at provider configuration provider: local\-kvm base_domain: base\-centos7\-64 ip_source: ip\-learning ssh_username: root password: my\-very\-secret\-password # /tmp is mounted noexec.. do workaround deploy_command: sh /tmp/.saltcloud/deploy.sh script_args: \-F # grains to add to the minion grains: clones\-are\-awesome: true # override minion settings minion: master: 192.168.16.1 master_port: 5506 .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 centos7 my\-centos7\-clone .ft P .fi .UNINDENT .UNINDENT .sp This will create an instance named \fBmy\-centos7\-clone\fP on the cloud host. Also the minion id will be set to \fBmy\-centos7\-clone\fP\&. .sp If the command was executed on the salt\-master, its Salt key will automatically be accepted 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\-centos7\-clone test.version .ft P .fi .UNINDENT .UNINDENT .SS Required Settings .sp The following settings are always required for libvirt: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C centos7: provider: local\-kvm # the domain to clone base_domain: base\-centos7\-64 .ft P .fi .UNINDENT .UNINDENT .SS SSH Key Authentication .sp Instead of specifying a password, an authorized key can be used for the minion setup. Ensure that the ssh user of your base image has the public key you want to use in ~/.ssh/authorized_keys. If you want to use a non\-root user you will likely want to configure salt\-cloud to use sudo. .sp An example using root: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C centos7: provider: local\-kvm # the domain to clone base_domain: base\-centos7\-64 ssh_username: root private_key: /path/to/private/key .ft P .fi .UNINDENT .UNINDENT .sp An example using a non\-root user: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C centos7: provider: local\-kvm # the domain to clone base_domain: base\-centos7\-64 ssh_username: centos private_key: /path/to/private/key sudo: True sudo_password: "\-\-redacted\-\-" .ft P .fi .UNINDENT .UNINDENT .SS Optional Settings .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C centos7: # ssh settings # use forwarded agent instead of a local key ssh_agent: True ssh_port: 4910 # credentials ssh_username: root # password will be used for sudo if defined, use sudo_password if using ssh keys password: my\-secret\-password private_key: /path/to/private/key sudo: True sudo_password: "\-\-redacted\-\-" # bootstrap options deploy_command: sh /tmp/.saltcloud/deploy.sh script_args: \-F # minion config grains: sushi: more tasty # point at the another master at another port minion: master: 192.168.16.1 master_port: 5506 # libvirt settings # clone_strategy: [ quick | full ] # default is full clone_strategy: quick # ip_source: [ ip\-learning | qemu\-agent ] # default is ip\-learning ip_source: qemu\-agent # validate_xml: [ false | true ] # default is true validate_xml: false .ft P .fi .UNINDENT .UNINDENT .sp The \fBclone_strategy\fP controls how the clone is done. In case of \fBfull\fP the disks are copied creating a standalone clone. If \fBquick\fP is used the disks of the base domain are used as backing disks for the clone. This results in nearly instantaneous clones at the expense of slower write performance. The quick strategy has a number of requirements: .INDENT 0.0 .IP \(bu 2 The disks must be of type qcow2 .IP \(bu 2 The base domain must be turned off .IP \(bu 2 The base domain must not change after creating the clone .UNINDENT .sp The \fBip_source\fP setting controls how the IP address of the cloned instance is determined. When using \fBip\-learning\fP the IP is requested from libvirt. This needs a recent libvirt version and may only work for NAT/routed networks where libvirt runs the dhcp server. Another option is to use \fBqemu\-agent\fP this requires that the qemu\-agent is installed and configured to run at startup in the base domain. .sp The \fBvalidate_xml\fP setting is available to disable xml validation by libvirt when cloning. .sp See also \fBsalt.cloud.clouds.libvirt\fP .SS Getting Started With Linode .sp Linode is a public cloud host with a focus on Linux instances. .SS Dependencies .sp This driver requires the Python \fBrequests\fP library to be installed. .SS Provider Configuration .SS Configuration Options .INDENT 0.0 .TP .B \fBapikey\fP \fB(Required)\fP The key to use to authenticate with the Linode API. .TP .B \fBpassword\fP \fB(Required)\fP The default password to set on new VMs. Must be 8 characters with at least one lowercase, uppercase, and numeric. .TP .B \fBapi_version\fP The version of the Linode API to interact with. Defaults to \fBv3\fP\&. .TP .B \fBpoll_interval\fP The rate of time in milliseconds to poll the Linode API for changes. Defaults to \fB500\fP\&. .TP .B \fBratelimit_sleep\fP The time in seconds to wait before retrying after a ratelimit has been enforced. Defaults to \fB0\fP\&. .UNINDENT .SS Example Configuration .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\-provider: driver: linode api_version: v4 apikey: f4ZsmwtB1c7f85Jdu43RgXVDFlNjuJaeIYV8QMftTqKScEB2vSosFSr... password: F00barbaz .ft P .fi .UNINDENT .UNINDENT .sp For use with APIv3 (deprecated): .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C my\-linode\-provider\-v3: driver: linode apikey: f4ZsmwtB1c7f85Jdu43RgXVDFlNjuJaeIYV8QMftTqKScEB2vSosFSr... password: F00barbaz .ft P .fi .UNINDENT .UNINDENT .SS Profile Configuration .SS Configuration Options .INDENT 0.0 .TP .B \fBimage\fP \fB(Required)\fP The image to deploy the boot disk from. This should be an image ID (e.g. \fBlinode/ubuntu16.04\fP); official images start with \fBlinode/\fP\&. For APIv3, this would be an image label (i.e. Ubuntu 16.04). See \fI\%listing images\fP for more options. .TP .B \fBlocation\fP \fB(Required)\fP The location of the VM. This should be a Linode region (e.g. \fBus\-east\fP). For APIv3, this would be a datacenter location (e.g. \fBNewark, NJ, USA\fP). See \fI\%listing locations\fP for more options. .TP .B \fBsize\fP \fB(Required)\fP The size of the VM. This should be a Linode instance type ID (e.g. \fBg6\-standard\-2\fP). For APIv3, this would be a plan ID (e.g. \fBLinode 2GB\fP). See \fI\%listing sizes\fP for more options. .TP .B \fBpassword\fP (overrides provider) \fB(*Required)\fP The default password for the VM. Must be provided at the profile or provider level. .TP .B \fBassign_private_ip\fP New in version 2016.3.0. .sp Whether or not to assign a private key to the VM. Defaults to \fBFalse\fP\&. .TP .B \fBcloneform\fP The name of the Linode to clone from. .TP .B \fBdisk_size\fP \fB(Deprecated)\fP The amount of disk space to allocate for the OS disk. This has no effect with APIv4; the size of the boot disk will be the remainder of disk space after the swap partition is allocated. .TP .B \fBssh_interface\fP New in version 2016.3.0. .sp The interface with which to connect over SSH. Valid options are \fBprivate_ips\fP or \fBpublic_ips\fP\&. Defaults to \fBpublic_ips\fP\&. .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. .TP .B \fBssh_pubkey\fP The public key to authorize for SSH with the VM. .TP .B \fBswap\fP The amount of disk space to allocate for the swap partition. Defaults to \fB256\fP\&. .UNINDENT .SS Example Configuration .sp Set up a profile configuration in \fB/etc/salt/cloud.profiles.d/\fP: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C my\-linode\-profile: provider: my\-linode\-provider size: g6\-standard\-1 image: linode/alpine3.12 location: us\-east .ft P .fi .UNINDENT .UNINDENT .sp The \fBmy\-linode\-profile\fP can be realized now with a salt command: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-p my\-linode\-profile my\-linode\-instance .ft P .fi .UNINDENT .UNINDENT .sp This will create a salt minion instance named \fBmy\-linode\-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 my\-linode\-instance test.version .ft P .fi .UNINDENT .UNINDENT .sp A more advanced configuration utlizing all of the configuration options might look like: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C my\-linode\-profile\-advanced: provider: my\-linode\-provider size: g6\-standard\-3 image: linode/alpine3.10 location: eu\-west password: bogus123X assign_private_ip: true ssh_interface: private_ips ssh_pubkey: ssh\-rsa AAAAB3NzaC1yc2EAAAADAQAB... swap_size: 512 .ft P .fi .UNINDENT .UNINDENT .sp A legacy configuration for use with APIv3 might look like: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C my\-linode\-profile\-v3: provider: my\-linode\-provider\-v3 size: Nanode 1GB image: Alpine 3.12 location: Fremont, CA, USA .ft P .fi .UNINDENT .UNINDENT .SS Migrating to APIv4 .sp Linode APIv3 has been deprecated and will be shutdown in the coming months. You can opt\-in to using APIv4 by setting the \fBapi_version\fP provider configuration option to \fBv4\fP\&. .sp When switching to APIv4, you will also need to generate a new token. See \fI\%here\fP for more information. .SS Notable Changes .sp \fBMove from label references to ID references.\fP The profile configuration parameters \fBlocation\fP, \fBsize\fP, and \fBimage\fP have moved from accepting label based references to IDs. See the \fI\%profile configuration\fP section for more details. .sp \fBThe \(ga\(gadisk_size\(ga\(ga profile configuration parameter has been deprecated.\fP The parameter will not be taken into account when creating new VMs while targeting APIv4. See the \fBdisk_size\fP description under the \fI\%profile configuration\fP section for more details. .sp \fBThe \(ga\(gaboot\(ga\(ga function no longer requires a \(ga\(gaconfig_id\(ga\(ga.\fP A config can be inferred by the API instead when booting. .sp \fBThe \(ga\(gaclone\(ga\(ga function has renamed parameters to match convention.\fP The old version of these parameters will not be supported when targeting APIv4. * \fBdatacenter_id\fP has been deprecated in favor of \fBlocation\fP\&. * \fBplan_id\fP has been deprecated in favor of \fBsize\fP\&. .sp \fBThe \(ga\(gaget_plan_id\(ga\(ga function has been deprecated and will not be supported by APIv4.\fP IDs are now the only way of referring to a "plan" (or type/size). .SS Query Utilities .SS Listing Sizes .sp Available sizes can be obtained by running one of: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-\-list\-sizes my\-linode\-provider salt\-cloud \-f avail_sizes my\-linode\-provider .ft P .fi .UNINDENT .UNINDENT .sp This will list all Linode sizes/types which can be referenced in VM profiles. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C my\-linode\-config: g6\-standard\-1: \-\-\-\-\-\-\-\-\-\- class: standard disk: 51200 gpus: 0 id: g6\-standard\-1 label: Linode 2GB memory: 2048 network_out: 2000 price: \-\-\-\-\-\-\-\-\-\- hourly: 0.015 monthly: 10.0 successor: None transfer: 2000 vcpus: 1 addons: \-\-\-\-\-\-\-\-\-\- backups: \-\-\-\-\-\-\-\-\-\- price: \-\-\-\-\-\-\-\-\-\- hourly: 0.004 monthly: 2.5 \&...SNIP... .ft P .fi .UNINDENT .UNINDENT .SS Listing Images .sp Available images can be obtained by running one of: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-\-list\-images my\-linode\-provider salt\-cloud \-f avail_images my\-linode\-provider .ft P .fi .UNINDENT .UNINDENT .sp This will list all Linode images which can be referenced in VM profiles. Official images are available under the \fBlinode\fP namespace. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C my\-linode\-config: \-\-\-\-\-\-\-\-\-\- linode: \-\-\-\-\-\-\-\-\-\- linode/alpine3.10: \-\-\-\-\-\-\-\-\-\- created: 2019\-06\-20T17:17:11 created_by: linode deprecated: False description: None eol: 2021\-05\-01T04:00:00 expiry: None id: linode/alpine3.10 is_public: True label: Alpine 3.10 size: 300 type: manual vendor: Alpine \&...SNIP... .ft P .fi .UNINDENT .UNINDENT .SS Listing Locations .sp Available locations can be obtained by running one of: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-\-list\-locations my\-linode\-provider salt\-cloud \-f avail_locations my\-linode\-provider .ft P .fi .UNINDENT .UNINDENT .sp This will list all Linode regions which can be referenced in VM profiles. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C my\-linode\-config: \-\-\-\-\-\-\-\-\-\- linode: \-\-\-\-\-\-\-\-\-\- us\-east: \-\-\-\-\-\-\-\-\-\- capabilities: \- Linodes \- NodeBalancers \- Block Storage \- Object Storage \- GPU Linodes \- Kubernetes country: us id: us\-east status: ok \&...SNIP... .ft P .fi .UNINDENT .UNINDENT .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 1and1 .sp 1&1 is one of the world’s leading Web hosting providers. 1&1 currently offers a wide range of Web hosting products, including email solutions and high\-end servers in 10 different countries including Germany, Spain, Great Britain and the United States. From domains to 1&1 MyWebsite to eBusiness solutions like Cloud Hosting and Web servers for complex tasks, 1&1 is well placed to deliver a high quality service to its customers. All 1&1 products are hosted in 1&1‘s high\-performance, green data centers in the USA and Europe. .SS Dependencies .INDENT 0.0 .IP \(bu 2 1and1 >= 1.2.0 .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/oneandone.conf\fP: .UNINDENT .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C my\-oneandone\-config: driver: oneandone # Set the location of the salt\-master # minion: master: saltmaster.example.com # Configure oneandone authentication credentials # api_token: ssh_private_key: /path/to/id_rsa ssh_public_key: /path/to/id_rsa.pub .ft P .fi .UNINDENT .UNINDENT .SS Authentication .sp The \fBapi_key\fP is used for API authorization. This token can be obtained from the CloudPanel in the Management section below Users. .SS Profiles .sp Here is an example of a profile: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C oneandone_fixed_size: provider: my\-oneandone\-config description: Small instance size server fixed_instance_size: S appliance_id: 8E3BAA98E3DFD37857810E0288DD8FBA oneandone_custom_size: provider: my\-oneandone\-config description: Custom size server vcore: 2 cores_per_processor: 2 ram: 8 appliance_id: 8E3BAA98E3DFD37857810E0288DD8FBA hdds: \- is_main: true size: 20 \- is_main: false size: 20 .ft P .fi .UNINDENT .UNINDENT .sp The following list explains some of the important properties. .INDENT 0.0 .TP .B fixed_instance_size_id When creating a server, either \fBfixed_instance_size_id\fP or custom hardware params containing \fBvcore\fP, \fBcores_per_processor\fP, \fBram\fP, and \fBhdds\fP must be provided. Can be one of the IDs listed among the output of the following command: .UNINDENT .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-\-list\-sizes oneandone .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .TP .B vcore Total amount of processors. .TP .B cores_per_processor Number of cores per processor. .TP .B ram RAM memory size in GB. .TP .B hdds Hard disks. .TP .B appliance_id ID of the image that will be installed on server. Can be one of the IDs listed in the output of the following command: .UNINDENT .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-\-list\-images oneandone .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .TP .B datacenter_id ID of the datacenter where the server will be created. Can be one of the IDs listed in the output of the following command: .UNINDENT .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-\-list\-locations oneandone .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .TP .B description Description of the server. .TP .B password Password of the server. Password must contain more than 8 characters using uppercase letters, numbers and other special symbols. .TP .B power_on Power on server after creation. Default is set to true. .TP .B firewall_policy_id Firewall policy ID. If it is not provided, the server will assign the best firewall policy, creating a new one if necessary. If the parameter is sent with a 0 value, the server will be created with all ports blocked. .TP .B ip_id IP address ID. .TP .B load_balancer_id Load balancer ID. .TP .B monitoring_policy_id Monitoring policy ID. .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. .TP .B public_key_ids List of public key IDs (ssh key). .UNINDENT .SS Functions .INDENT 0.0 .IP \(bu 2 Create an SSH key .UNINDENT .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C sudo salt\-cloud \-f create_ssh_key my\-oneandone\-config name=\(aqSaltTest\(aq description=\(aqSaltTestDescription\(aq .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .IP \(bu 2 Create a block storage .UNINDENT .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C sudo salt\-cloud \-f create_block_storage my\-oneandone\-config name=\(aqSaltTest2\(aq description=\(aqSaltTestDescription\(aq size=50 datacenter_id=\(aq5091F6D8CBFEF9C26ACE957C652D5D49\(aq .ft P .fi .UNINDENT .UNINDENT .sp For more information concerning cloud profiles, see here\&. .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.version .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 Change Disk Size .sp You can now change the size of a VM on creation by cloning an image and expanding the size. You can accomplish this by the following cloud profile settings below. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C my\-opennebula\-profile: provider: my\-opennebula\-provider image: Ubuntu\-14.04 disk: disk0: disk_type: clone size: 8096 image: centos7\-base\-image\-v2 disk1: disk_type: volatile type: swap size: 4096 disk2: disk_type: volatile size: 4096 type: fs format: ext3 .ft P .fi .UNINDENT .UNINDENT .sp There are currently two different disk_types a user can use: volatile and clone. Clone which is required when specifying devices will clone an image in open nebula and will expand it to the size specified in the profile settings. By default this will clone the image attached to the template specified in the profile but a user can add the \fIimage\fP argument under the disk definition. .sp For example the profile below will not use Ubuntu\-14.04 for the cloned disk image. It will use the centos7\-base\-image image: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C my\-opennebula\-profile: provider: my\-opennebula\-provider image: Ubuntu\-14.04 disk: disk0: disk_type: clone size: 8096 image: centos7\-base\-image .ft P .fi .UNINDENT .UNINDENT .sp If you want to use the image attached to the template set in the profile you can simply remove the image argument as show below. The profile below will clone the image Ubuntu\-14.04 and expand the disk to 8GB.: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C my\-opennebula\-profile: provider: my\-opennebula\-provider image: Ubuntu\-14.04 disk: disk0: disk_type: clone size: 8096 .ft P .fi .UNINDENT .UNINDENT .sp A user can also currently specify swap or fs disks. Below is an example of this profile setting: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C my\-opennebula\-profile: provider: my\-opennebula\-provider image: Ubuntu\-14.04 disk: disk0: disk_type: clone size: 8096 disk1: disk_type: volatile type: swap size: 4096 disk2: disk_type: volatile size: 4096 type: fs format: ext3 .ft P .fi .UNINDENT .UNINDENT .sp The example above will attach both a swap disk and a ext3 filesystem with a size of 4GB. To note if you define other disks you have to define the image disk to clone because the template will write over the entire \(aqDISK=[]\(aq template definition on creation. .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 See \fBsalt.cloud.clouds.openstack\fP .SS Getting Started With Parallels .sp Parallels Cloud Server is a product by Parallels that delivers a cloud hosting solution. The PARALLELS module for Salt Cloud enables you to manage instances hosted 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.version .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 >= 4.1.1 .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 # delete_volumes is forcing a deletion of all volumes attached to a server on a deletion of a server delete_volumes: true # 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 .sp A new data center can be created with the following command: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-f create_datacenter my\-profitbricks\-config name=example location=us/las description="my description" .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_alias: \(aqubuntu:latest\(aq # image or image_alias must be provided # 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 image_password: MyPassword1 disk_type: SSD disk_size: 40 cores: 8 cpu_family: INTEL_XEON ram: 32768 public_lan: 1 public_ips: \- 172.217.18.174 private_lan: 2 private_ips: \- 192.168.100.10 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 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\-profitbricks\-config .ft P .fi .UNINDENT .UNINDENT .sp Images 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\-images my\-profitbricks\-config .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\-profitbricks\-config .ft P .fi .UNINDENT .UNINDENT .sp Changed in version 2019.2.0: One or more public IP address can be reserved with the following command: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C # salt\-cloud \-f reserve_ipblock my\-profitbricks\-config location=\(aqus/ewr\(aq size=1 .ft P .fi .UNINDENT .UNINDENT .SS Profile Specifics: .sp The following list explains some of the important properties. .INDENT 0.0 .IP \(bu 2 \fBsize\fP \- Can be one of the options listed in the output of the following command: .INDENT 2.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-\-list\-sizes my\-profitbricks\-config .ft P .fi .UNINDENT .UNINDENT .IP \(bu 2 \fBimage\fP \- Can be one of the options listed in the output of the following command: .INDENT 2.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-\-list\-images my\-profitbricks\-config .ft P .fi .UNINDENT .UNINDENT .IP \(bu 2 \fBimage_alias\fP \- Can be one of the options listed in the output of the following command: .INDENT 2.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-f list_images my\-profitbricks\-config .ft P .fi .UNINDENT .UNINDENT .IP \(bu 2 \fBdisk_size\fP \- This option allows you to override the size of the disk as defined by the size. The disk size is set in gigabytes (GB). .IP \(bu 2 \fBdisk_type\fP \- This option allow the disk type to be set to HDD or SSD. The default is HDD. .sp New in version 2019.2.0. .IP \(bu 2 \fBimage_password\fP \- A password is set on the image for the "root" or "Administrator" account. This field may only be set during volume creation. Only valid with ProfitBricks supplied HDD (not ISO) images. The password must contain at least 8 and no more than 50 characters. Only these characters are allowed: [a\-z][A\-Z][0\-9] .IP \(bu 2 \fBcores\fP \- This option allows you to override the number of CPU cores as defined by the size. .IP \(bu 2 \fBram\fP \- 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. .IP \(bu 2 \fBpublic_lan\fP \- 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). .sp New in version 2019.2.0. .IP \(bu 2 \fBpublic_ips\fP \- Public IPs assigned to the NIC in the public LAN. .IP \(bu 2 \fBpublic_firewall_rules\fP \- This option allows for a list of firewall rules assigned to the public network interface. .INDENT 2.0 .INDENT 3.5 .sp .nf .ft C Firewall Rule Name: protocol: (TCP, UDP, ICMP) source_mac: source_ip: target_ip: port_range_start: port_range_end: icmp_type: icmp_code: .ft P .fi .UNINDENT .UNINDENT .IP \(bu 2 \fBprivate_lan\fP \- 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). .sp New in version 2019.2.0. .IP \(bu 2 \fBprivate_ips\fP \- Private IPs assigned in the private LAN. NAT setting is ignored when this setting is active. .IP \(bu 2 \fBprivate_firewall_rules\fP \- This option allows for a list of firewall rules assigned to the private network interface. .INDENT 2.0 .INDENT 3.5 .sp .nf .ft C Firewall Rule Name: protocol: (TCP, UDP, ICMP) source_mac: source_ip: target_ip: port_range_start: port_range_end: icmp_type: icmp_code: .ft P .fi .UNINDENT .UNINDENT .IP \(bu 2 \fBssh_private_key\fP \- Full path to the SSH private key file .IP \(bu 2 \fBssh_public_key\fP \- Full path to the SSH public key file .IP \(bu 2 \fBssh_interface\fP \- 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. .IP \(bu 2 \fBcpu_family\fP \- This option allow the CPU family to be set to AMD_OPTERON or INTEL_XEON. The default is AMD_OPTERON. .IP \(bu 2 \fBvolumes\fP \- 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. .IP \(bu 2 \fBdeploy\fP \- Set to \fBFalse\fP if Salt should not be installed on the node. .IP \(bu 2 \fBwait_for_timeout\fP \- 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\%https://www.proxmox.com\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.version .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 # Public key to add to /root/.ssh/authorized_keys. pubkey: \(aqssh\-rsa AAAAB3NzaC1yc2EAAAADAQABA...\(aq .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: True # 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: \fBsalt/cloud/clouds/proxmox.py\fP .sp An easy way to support more parameters for VM creation would be to add the names of the optional parameters in the \(aqcreate_nodes(vm_)\(aq function, under the \(aqqemu\(aq technology. But it requires you to dig into the code ... .UNINDENT .UNINDENT .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 scaleway\-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 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 can have 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 driver: saltify .ft P .fi .UNINDENT .UNINDENT .sp However, if you wish to use the more advanced capabilities of salt\-cloud, such as rebooting, listing, and disconnecting machines, then the salt master must fill the role usually performed by a vendor\(aqs cloud management system. The salt master must be running on the salt\-cloud machine, and created nodes must be connected to the master. .sp Additional information about which configuration options apply to which actions can be studied in the Saltify Module documentation and the Miscellaneous Salt Cloud Options document. .SS Profiles .sp Saltify requires a separate profile to be configured for each machine that needs Salt installed [1]\&. 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\&. .IP [1] 5 Unless you are using a map file to provide the unique parameters. .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 accepted by 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.version .ft P .fi .UNINDENT .UNINDENT .SS Destroy Options .sp New in version 2018.3.0. .sp For obvious reasons, the \fBdestroy\fP action does not actually vaporize hardware. If the salt master is connected, it can tear down parts of the client machines. It will remove the client\(aqs key from the salt master, and can execute the following options: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C \- remove_config_on_destroy: true # default: true # Deactivate salt\-minion on reboot and # delete the minion config and key files from its "/etc/salt" directory, # NOTE: If deactivation was unsuccessful (older Ubuntu machines) then when # salt\-minion restarts it will automatically create a new, unwanted, set # of key files. Use the "force_minion_config" option to replace them. \- shutdown_on_destroy: false # default: false # last of all, send a "shutdown" command to the client. .ft P .fi .UNINDENT .UNINDENT .SS Wake On LAN .sp New in version 2018.3.0. .sp In addition to connecting a hardware machine to a Salt master, you have the option of sending a wake\-on\-LAN \fI\%magic packet\fP to start that machine running. .sp The "magic packet" must be sent by an existing salt minion which is on the same network segment as the target machine. (Or your router must be set up especially to route WoL packets.) Your target machine must be set up to listen for WoL and to respond appropriately. .sp You must provide the Salt node id of the machine which will send the WoL packet (parameter \fBwol_sender_node\fP), and the hardware MAC address of the machine you intend to wake, (parameter \fBwake_on_lan_mac\fP). If both parameters are defined, the WoL will be sent. The cloud master will then sleep a while (parameter \fBwol_boot_wait\fP) to give the target machine time to boot up before we start probing its SSH port to begin deploying Salt to it. The default sleep time is 30 seconds. .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 wake_on_lan_mac: \(aq00:e0:4c:70:2a:b2\(aq # found with ifconfig wol_sender_node: bevymaster # its on this network segment wol_boot_wait: 45 # seconds to sleep .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 In this example, the names \fBmy\-instance\-0\fP and \fBmy\-instance\-1\fP will be the identifiers of the deployed minions. .sp Note: The \fBssh_host\fP directive is also used for Windows hosts, even though they do not typically run the SSH service. It indicates IP address or host name for the target system. .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.version .ft P .fi .UNINDENT .UNINDENT .SS Bulk Deployments .sp When deploying large numbers of Salt Minions using Saltify, it may be preferable to organize the configuration in a way that duplicates data as little as possible. For example, if a group of target systems have the same credentials, they can be specified in the profile, rather than in a map file. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C # /etc/salt/cloud.profiles.d/saltify.conf make_salty: provider: my\-saltify\-config ssh_username: root password: very\-bad\-password .ft P .fi .UNINDENT .UNINDENT .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 \- my\-instance\-1: ssh_host: 44.33.22.11 .ft P .fi .UNINDENT .UNINDENT .sp If \fBssh_host\fP is not provided, its default value will be the Minion identifier (\fBmy\-instance\-0\fP and \fBmy\-instance\-1\fP, in the example above). For deployments with working DNS resolution, this can save a lot of redundant data in the map. Here is an example map file using DNS names instead of IP addresses: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C # /etc/salt/saltify\-map make_salty: \- my\-instance\-0 \- my\-instance\-1 .ft P .fi .UNINDENT .UNINDENT .SS Credential Verification .sp Because the Saltify driver does not actually create VM\(aqs, unlike other salt\-cloud drivers, it has special behaviour when the \fBdeploy\fP option is set to \fBFalse\fP\&. When the cloud configuration specifies \fBdeploy: False\fP, the Saltify driver will attempt to authenticate to the target node(s) and return \fBTrue\fP for each one that succeeds. This can be useful to verify ports, protocols, services and credentials are correctly configured before a live deployment. .INDENT 0.0 .TP .B Return values: .INDENT 7.0 .IP \(bu 2 \fBTrue\fP: Credential verification succeeded .IP \(bu 2 \fBFalse\fP: Credential verification succeeded .IP \(bu 2 \fBNone\fP: Credential verification was not attempted. .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.org/project/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 # Use a dedicated host instead of cloud dedicated_host_id: 1234 # 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.version my\-vm.example.com: 2018.3.4 # # # 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. .sp If this setting is set to \fINone\fP, salt\-cloud will connect to the private ip of the server. .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 If this setting is not provided and the server is not built with a public vlan, \fIprivate_ssh\fP or \fIprivate_wds\fP will need to be set to make sure that salt\-cloud attempts to connect to the private ip. .UNINDENT .UNINDENT .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 or private_wds .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 or WinRM 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.version .ft P .fi .UNINDENT .UNINDENT .SS Dedicated Host .sp Soflayer allows the creation of new VMs in a dedicated host. This means that you can order and pay a fixed amount for a bare metal dedicated host and use it to provision as many VMs as you can fit in there. If you want your VMs to be launched in a dedicated host, instead of Sofltayer\(aqs cloud, set the \fBdedicated_host_id\fP parameter in your profile. .SS dedicated_host_id .sp The id of the dedicated host where the VMs should be created. If not set, VMs will be created in Softlayer\(aqs cloud instead. .SS Bare metal 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 Tencent Cloud .sp Tencent Cloud is a secure, reliable and high\-performance cloud compute service provided by Tencent. It is the 2nd largest Cloud Provider in China. .SS Dependencies .sp The Tencent Cloud driver for Salt Cloud requires the \fBtencentcloud\-sdk\-python\fP package, which is available at PyPI: .sp \fI\%https://pypi.org/project/tencentcloud\-sdk\-python/\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 tencentcloud\-sdk\-python # easy_install tencentcloud\-sdk\-python .ft P .fi .UNINDENT .UNINDENT .SS Provider Configuration .INDENT 0.0 .TP .B To use this module, set up the cloud configuration at \fB/etc/salt/cloud.providers\fP or \fB/etc/salt/cloud.providers.d/*.conf\fP: .UNINDENT .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C my\-tencentcloud\-config: driver: tencentcloud # Tencent Cloud Secret Id id: AKIDA64pOio9BMemkApzevX0HS169S4b750A # Tencent Cloud Secret Key key: 8r2xmPn0C5FDvRAlmcJimiTZKVRsk260 # Tencent Cloud Region location: ap\-guangzhou .ft P .fi .UNINDENT .UNINDENT .SS Configuration Parameters .SS driver .sp \fBRequired\fP\&. \fBtencentcloud\fP to use this module. .SS id .sp \fBRequired\fP\&. Your Tencent Cloud secret id. .SS key .sp \fBRequired\fP\&. Your Tencent Cloud secret key. .SS location .sp \fBOptional\fP\&. If this value is not specified, the default is \fBap\-guangzhou\fP\&. Available locations can be found using the \fB\-\-list\-locations\fP option: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C # salt\-cloud \-\-list\-location my\-tencentcloud\-config .ft P .fi .UNINDENT .UNINDENT .SS Profile Configuration .sp Tencent Cloud profiles require a \fBprovider\fP, \fBavailability_zone\fP, \fBimage\fP and \fBsize\fP\&. 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 tencentcloud\-guangzhou\-s1sm1: provider: my\-tencentcloud\-config availability_zone: ap\-guangzhou\-3 image: img\-31tjrtph size: S1.SMALL1 allocate_public_ip: True internet_max_bandwidth_out: 1 password: \(aq153e41ec96140152\(aq securitygroups: \- sg\-5e90804b .ft P .fi .UNINDENT .UNINDENT .SS Configuration Parameters .SS provider .sp \fBRequired\fP\&. Name of entry in \fBsalt/cloud.providers.d/???\fP file. .SS availability_zone .sp \fBRequired\fP\&. The availability zone that the instance is located in. Available zones can be found using the \fBlist_availability_zones\fP function: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C # salt\-cloud \-f list_availability_zones my\-tencentcloud\-config .ft P .fi .UNINDENT .UNINDENT .SS image .sp \fBRequired\fP\&. The image id to use for the instance. Available images 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\-tencentcloud\-config .ft P .fi .UNINDENT .UNINDENT .SS size .sp \fBRequired\fP\&. Instance type for instance can be found using the \fB\-\-list\-sizes\fP option. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C # salt\-cloud \-\-list\-sizes my\-tencentcloud\-config .ft P .fi .UNINDENT .UNINDENT .SS securitygroups .sp \fBOptional\fP\&. A list of security group ids to associate with. Available security group ids can be found using the \fBlist_securitygroups\fP function: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C # salt\-cloud \-f list_securitygroups my\-tencentcloud\-config .ft P .fi .UNINDENT .UNINDENT .sp Multiple security groups are supported: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C tencentcloud\-guangzhou\-s1sm1: securitygroups: \- sg\-5e90804b \- sg\-8kpynf2t .ft P .fi .UNINDENT .UNINDENT .SS hostname .sp \fBOptional\fP\&. The hostname of the instance. .SS instance_charge_type .sp \fBOptional\fP\&. The charge type of the instance. Valid values are \fBPREPAID\fP, \fBPOSTPAID_BY_HOUR\fP and \fBSPOTPAID\fP\&. The default is \fBPOSTPAID_BY_HOUR\fP\&. .SS instance_charge_type_prepaid_renew_flag .sp \fBOptional\fP\&. When enabled, the instance will be renew automatically when it reaches the end of the prepaid tenancy. Valid values are \fBNOTIFY_AND_AUTO_RENEW\fP, \fBNOTIFY_AND_MANUAL_RENEW\fP and \fBDISABLE_NOTIFY_AND_MANUAL_RENEW\fP\&. .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 This value is only used when \fBinstance_charge_type\fP is set to \fBPREPAID\fP\&. .UNINDENT .UNINDENT .SS instance_charge_type_prepaid_period .sp \fBOptional\fP\&. The tenancy time in months of the prepaid instance, Valid values are \fB1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 24, 36\fP\&. .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 This value is only used when \fBinstance_charge_type\fP is set to \fBPREPAID\fP\&. .UNINDENT .UNINDENT .SS allocate_public_ip .sp \fBOptional\fP\&. Associate a public ip address with an instance in a VPC or Classic. Boolean value, default is \fBfalse\fP\&. .SS internet_max_bandwidth_out .sp \fBOptional\fP\&. Maximum outgoing bandwidth to the public network, measured in Mbps (Mega bits per second). Value range: \fB[0, 100]\fP\&. If this value is not specified, the default is \fB0\fP Mbps. .SS internet_charge_type .sp \fBOptional\fP\&. Internet charge type of the instance. Valid values are \fBBANDWIDTH_PREPAID\fP, \fBTRAFFIC_POSTPAID_BY_HOUR\fP, \fBBANDWIDTH_POSTPAID_BY_HOUR\fP and \fBBANDWIDTH_PACKAGE\fP\&. The default is \fBTRAFFIC_POSTPAID_BY_HOUR\fP\&. .SS key_name .sp \fBOptional\fP\&. The key pair to use for the instance, for example \fBskey\-16jig7tx\fP\&. .SS password .sp \fBOptional\fP\&. Login password for the instance. .SS private_ip .sp \fBOptional\fP\&. The private ip to be assigned to this instance, must be in the provided subnet and available. .SS project_id .sp \fBOptional\fP\&. The project this instance belongs to, defaults to \fB0\fP\&. .SS vpc_id .sp \fBOptional\fP\&. The id of a VPC network. If you want to create instances in a VPC network, this parameter must be set. .SS subnet_id .sp \fBOptional\fP\&. The id of a VPC subnet. If you want to create instances in VPC network, this parameter must be set. .SS system_disk_size .sp \fBOptional\fP\&. Size of the system disk. Value range: \fB[50, 1000]\fP, and unit is \fBGB\fP\&. Default is \fB50\fP GB. .SS system_disk_type .sp \fBOptional\fP\&. Type of the system disk. Valid values are \fBCLOUD_BASIC\fP, \fBCLOUD_SSD\fP and \fBCLOUD_PREMIUM\fP, default value is \fBCLOUD_BASIC\fP\&. .SS Actions .sp The following actions are supported by the Tencent Cloud Salt Cloud driver. .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 show_disk .sp Return disk details about a specific instance. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C $ salt\-cloud \-a show_disk myinstance .ft P .fi .UNINDENT .UNINDENT .SS destroy .sp Destroy a Tencent Cloud instance. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C $ salt\-cloud \-a destroy myinstance .ft P .fi .UNINDENT .UNINDENT .SS start .sp Start a Tencent Cloud instance. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C $ salt\-cloud \-a start myinstance .ft P .fi .UNINDENT .UNINDENT .SS stop .sp Stop a Tencent Cloud instance. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C $ salt\-cloud \-a stop myinstance .ft P .fi .UNINDENT .UNINDENT .SS reboot .sp Reboot a Tencent Cloud instance. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C $ salt\-cloud \-a reboot myinstance .ft P .fi .UNINDENT .UNINDENT .SS Functions .sp The following functions are currently supported by the Tencent Cloud Salt Cloud driver. .SS list_securitygroups .sp Lists all Tencent Cloud security groups in current region. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C $ salt\-cloud \-f list_securitygroups my\-tencentcloud\-config .ft P .fi .UNINDENT .UNINDENT .SS list_availability_zones .sp Lists all Tencent Cloud availability zones in current region. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C $ salt\-cloud \-f list_availability_zones my\-tencentcloud\-config .ft P .fi .UNINDENT .UNINDENT .SS list_custom_images .sp Lists any custom images associated with the account. These images 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\-tencentcloud\-config .ft P .fi .UNINDENT .UNINDENT .SS show_image .sp Return details about a specific image. This image can be used to create a new instance. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C $ salt\-cloud \-f show_image tencentcloud image=img\-31tjrtph .ft P .fi .UNINDENT .UNINDENT .SS Getting Started With Vagrant .sp The Vagrant driver is a new, experimental driver for spinning up a VagrantBox virtual machine, and installing Salt on it. .SS Dependencies .sp The Vagrant driver itself has no external dependencies. .sp The machine which will host the VagrantBox must be an already existing minion of the cloud server\(aqs Salt master. It must have \fI\%Vagrant\fP installed, and a Vagrant\-compatible virtual machine engine, such as \fI\%VirtualBox\fP\&. (Note: The Vagrant driver does not depend on the salt\-cloud VirtualBox driver in any way.) .sp [Caution: The version of Vagrant packaged for \fBapt install\fP in Ubuntu 16.04 will not connect a bridged network adapter correctly. Use a version downloaded directly from the web site.] .sp Include the Vagrant guest editions plugin: \fBvagrant plugin install vagrant\-vbguest\fP\&. .SS Configuration .sp Configuration of the client virtual machine (using VirtualBox, VMware, etc) will be done by Vagrant as specified in the Vagrantfile on the host machine. .sp Salt\-cloud will push the commands to install and provision a salt minion on the virtual machine, so you need not (perhaps \fBshould\fP not) provision salt in your Vagrantfile, in most cases. .sp If, however, your cloud master cannot open an SSH connection to the child VM, you may \fBneed\fP to let Vagrant provision the VM with Salt, and use some other method (such as passing a pillar dictionary to the VM) to pass the master\(aqs IP address to the VM. The VM can then attempt to reach the salt master in the usual way for non\-cloud minions. Specify the profile configuration argument as \fBdeploy: False\fP to prevent the cloud master from trying. .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\-vagrant\-config: minion: master: 111.222.333.444 provider: vagrant .ft P .fi .UNINDENT .UNINDENT .sp Because the Vagrant driver needs a place to store the mapping between the node name you use for Salt commands and the Vagrantfile which controls the VM, you must configure your salt minion as a Salt smb server. (See \fI\%host provisioning example\fP below.) .SS Profiles .sp Vagrant 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. .sp Each profile requires a \fBvagrantfile\fP parameter. If the Vagrantfile has definitions for \fI\%multiple machines\fP then you need a \fBmachine\fP parameter, .sp Salt\-cloud uses SSH to provision the minion. There must be a routable path from the cloud master to the VM. Usually, you will want to use a bridged network adapter for SSH. The address may not be known until DHCP assigns it. If \fBssh_host\fP is not defined, and \fBtarget_network\fP is defined, the driver will attempt to read the address from the output of an \fBifconfig\fP command. Lacking either setting, the driver will try to use the value Vagrant returns as its \fBssh_host\fP, which will work only if the cloud master is running somewhere on the same host. .sp The \fBtarget_network\fP setting should be used to identify the IP network your bridged adapter is expected to appear on. Use CIDR notation, like \fBtarget_network: \(aq2001:DB8::/32\(aq\fP or \fBtarget_network: \(aq192.0.2.0/24\(aq\fP\&. .sp Profile configuration example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C # /etc/salt/cloud.profiles.d/vagrant.conf vagrant\-machine: host: my\-vhost # the Salt id of the virtual machine\(aqs host computer. provider: my\-vagrant\-config cwd: /srv/machines # the path to your Vagrantfile. vagrant_runas: my\-username # the username who defined the Vagrantbox on the host # vagrant_up_timeout: 300 # (seconds) timeout for cmd.run of the "vagrant up" command # vagrant_provider: \(aq\(aq # option for "vagrant up" like: "\-\-provider vmware_fusion" # ssh_host: None # "None" means try to find the routable IP address from "ifconfig" # ssh_username: \(aq\(aq # also required when ssh_host is used. # target_network: None # Expected CIDR address range of your bridged network # force_minion_config: false # Set "true" to re\-purpose an existing VM .ft P .fi .UNINDENT .UNINDENT .sp The machine can now be created and configured with the following command: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-p vagrant\-machine my\-id .ft P .fi .UNINDENT .UNINDENT .sp This will create the machine specified by the cloud profile \fBvagrant\-machine\fP, and will give the machine the minion id of \fBmy\-id\fP\&. If the cloud master is also the salt\-master, its Salt key will automatically be accepted 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\-id test.version .ft P .fi .UNINDENT .UNINDENT .SS Provisioning a Vagrant cloud host (example) .sp In order to query or control minions it created, each host minion needs to track the Salt node names associated with any guest virtual machines on it. It does that using a Salt sdb database. .sp The Salt sdb is not configured by default. The following example shows a simple installation. .sp This example assumes: .INDENT 0.0 .IP \(bu 2 you are on a large network using the 10.x.x.x IP address space .IP \(bu 2 your Salt master\(aqs Salt id is "bevymaster" .IP \(bu 2 it will also be your salt\-cloud controller .IP \(bu 2 it is at hardware address 10.124.30.7 .IP \(bu 2 it is running a recent Debian family Linux (raspbian) .IP \(bu 2 your workstation is a Salt minion of bevymaster .IP \(bu 2 your workstation\(aqs minion id is "my_laptop" .IP \(bu 2 VirtualBox has been installed on "my_laptop" (apt install is okay) .IP \(bu 2 Vagrant was installed from vagrantup.com. (not the 16.04 Ubuntu apt) .IP \(bu 2 "my_laptop" has done "vagrant plugin install vagrant\-vbguest" .IP \(bu 2 the VM you want to start is on "my_laptop" at "/home/my_username/Vagrantfile" .UNINDENT .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C # file /etc/salt/minion.d/vagrant_sdb.conf on host computer "my_laptop" # \-\- this sdb database is required by the Vagrant module \-\- vagrant_sdb_data: # The sdb database must have this name. driver: sqlite3 # Let\(aqs use SQLite to store the data ... database: /var/cache/salt/vagrant.sqlite # ... in this file ... table: sdb # ... using this table name. create_table: True # if not present .ft P .fi .UNINDENT .UNINDENT .sp Remember to re\-start your minion after changing its configuration files... .INDENT 0.0 .INDENT 3.5 \fBsudo systemctl restart salt\-minion\fP .UNINDENT .UNINDENT .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C # \-*\- mode: ruby \-*\- # file /home/my_username/Vagrantfile on host computer "my_laptop" BEVY = "bevy1" DOMAIN = BEVY + ".test" # .test is an ICANN reserved non\-public TLD # must supply a list of names to avoid Vagrant asking for interactive input def get_good_ifc() # try to find a working Ubuntu network adapter name addr_infos = Socket.getifaddrs addr_infos.each do |info| a = info.addr if a and a.ip? and not a.ip_address.start_with?("127.") return info.name end end return "eth0" # fall back to an old reliable name end Vagrant.configure(2) do |config| config.ssh.forward_agent = true # so you can use git ssh://... # add a bridged network interface. (try to detect name, then guess MacOS names, too) interface_guesses = [get_good_ifc(), \(aqen0: Ethernet\(aq, \(aqen1: Wi\-Fi (AirPort)\(aq] config.vm.network "public_network", bridge: interface_guesses if ARGV[0] == "up" puts "Trying bridge network using interfaces: #{interface_guesses}" end config.vm.provision "shell", inline: "ip address", run: "always" # make user feel good # . . . . . . . . . . . . Define machine QUAIL1 . . . . . . . . . . . . . . config.vm.define "quail1", primary: true do |quail_config| quail_config.vm.box = "boxesio/xenial64\-standard" # a public VMware & Virtualbox box quail_config.vm.hostname = "quail1." + DOMAIN # supply a name in our bevy quail_config.vm.provider "virtualbox" do |v| v.memory = 1024 # limit memory for the virtual box v.cpus = 1 v.linked_clone = true # make a soft copy of the base Vagrant box v.customize ["modifyvm", :id, "\-\-natnet1", "192.168.128.0/24"] # do not use 10.x network for NAT end end end .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C # file /etc/salt/cloud.profiles.d/my_vagrant_profiles.conf on bevymaster q1: host: my_laptop # the Salt id of your virtual machine host machine: quail1 # a machine name in the Vagrantfile (if not primary) vagrant_runas: my_username # owner of Vagrant box files on "my_laptop" cwd: \(aq/home/my_username\(aq # the path (on "my_laptop") of the Vagrantfile provider: my_vagrant_provider # name of entry in provider.conf file target_network: \(aq10.0.0.0/8\(aq # VM external address will be somewhere here .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C # file /etc/salt/cloud.providers.d/vagrant_provider.conf on bevymaster my_vagrant_provider: driver: vagrant minion: master: 10.124.30.7 # the hard address of the master .ft P .fi .UNINDENT .UNINDENT .SS Create and use your new Salt minion .INDENT 0.0 .IP \(bu 2 Typing on the Salt master computer \fBbevymaster\fP, tell it to create a new minion named \fBv1\fP using profile \fBq1\fP\&... .UNINDENT .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C sudo salt\-cloud \-p q1 v1 sudo salt v1 network.ip_addrs [ you get a list of IP addresses, including the bridged one ] .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .IP \(bu 2 logged in to your laptop (or some other computer known to GitHub)... .INDENT 2.0 .INDENT 3.5 [NOTE:] if you are using MacOS, you need to type \fBssh\-add \-K\fP after each boot, unless you use one of the methods in \fI\%this gist\fP\&. .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C ssh \-A vagrant@< the bridged network address > # [ or, if you are at /home/my_username/ on my_laptop ] vagrant ssh quail1 .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .IP \(bu 2 then typing on your new node "v1" (a.k.a. quail1.bevy1.test)... .UNINDENT .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C password: vagrant # [ stuff types out ... ] ls \-al /vagrant # [ should be shared /home/my_username from my_laptop ] # you can access other network facilities using the ssh authorization # as recorded in your ~.ssh/ directory on my_laptop ... sudo apt update sudo apt install git git clone ssh://git@github.com/yourID/your_project # etc... .ft P .fi .UNINDENT .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.version .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.org/project/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 datastore: smalldiskdatastore 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 mac: \(aq00:16:3e:e8:19:0f\(aq 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 annotation: Created by Salt\-Cloud 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 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 .sp New in version 2016.11.0. .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 eagerly_scrub Specifies whether the disk should be rewrite with zeros during thick provisioning or not. Default is \fBeagerly_scrub: False\fP\&. \&.. versionadded:: 2018.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. .TP .B datastore The name of a valid datastore should you wish the new disk to be in a datastore other than the default for the VM. .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. .TP .B mac Enter the MAC for this network adapter. If not specified an address will be selected automatically. .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 is created. If the IDE controller already exists, no further changes to it are made. The IDE controller specification is a dictionary. .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C ide: IDE 2: {} .ft P .fi .UNINDENT .UNINDENT .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 \fBannotation\fP User\-provided description of the virtual machine. This will store a message in the vSphere interface, under the annotations section in the Summary view of the virtual machine. .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 \fBwait_for_ip_timeout\fP When \fBdeploy: True\fP, this timeout determines the maximum time to wait for VMware tools to be installed on the virtual machine. If this timeout is reached, an attempt to determine the client\(aqs IP will be made by resolving the VM\(aqs name. By lowering this value a salt bootstrap can be fully automated for systems that are not built with VMware tools. Default is \fBwait_for_ip_timeout: 1200\fP\&. .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\%https://code.vmware.com/apis?pid=com.vmware.wssdk.apiref.doc&release=vsphere\-60&topic=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 .TP .B \fBwin_run_once\fP Specify a list of commands to run on first login to a windows minion .sp \fI\%https://www.vmware.com/support/developer/vc\-sdk/visdk25pubs/ReferenceGuide/vim.vm.customization.GuiRunOnce.html\fP .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 Getting Started With Xen .sp The Xen cloud driver works with Citrix XenServer. .sp It can be used with a single XenServer or a XenServer resource pool. .SS Setup Dependencies .sp This driver requires a copy of the freely available \fBXenAPI.py\fP Python module. .sp Information about the Xen API Python module in the XenServer SDK can be found at \fI\%https://pypi.org/project/XenAPI/\fP .sp Place a copy of this module on your system. For example, it can be placed in the \fIsite packages\fP location on your system. .sp The location of \fIsite packages\fP can be determined by running: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C python \-m site \-\-user\-site .ft P .fi .UNINDENT .UNINDENT .SS Provider Configuration .sp Xen requires login credentials to a XenServer. .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 # /etc/salt/cloud.providers.d/myxen.conf myxen: driver: xen url: https://10.0.0.120 user: root password: p@ssw0rd .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .TP .B url: The \fBurl\fP option supports both \fBhttp\fP and \fBhttps\fP uri prefixes. .TP .B user: A valid user id to login to the XenServer host. .TP .B password: The associated password for the user. .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 Xen profiles require a \fBprovider\fP and \fBimage\fP\&. .INDENT 0.0 .TP .B provider: This will be the name of your defined provider. .TP .B image: The name of the VM template used to clone or copy. .TP .B clone: The default behavior is to clone a template or VM. This is very fast, but requires the source template or VM to be in the same storage repository of the new target system. If the source and target are in different storage repositories then you must copy the source and not clone it by setting \fBclone: False\fP\&. .TP .B deploy: The provisioning process will attempt to install the Salt minion service on the new target system by default. This will require login credentials for Salt cloud to login via ssh to it. The \fBuser\fP and \fBpassword\fP options are required. If \fBdeploy\fP is set to \fBFalse\fP then these options are not needed. .TP .B resource_pool: The name of the resource pool used for this profile. .TP .B storage_repo: The name of the storage repository for the target system. .TP .B ipv4_cidr: If template is Windows, and running guest tools then a static ip address can be set. .TP .B ipv4_gw: If template is Windows, and running guest tools then a gateway can be set. .UNINDENT .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 # file: /etc/salt/cloud.profiles.d/xenprofiles.conf sles: provider: myxen deploy: False image: sles12sp2\-template suse: user: root password: p@ssw0rd provider: myxen image: opensuseleap42_2\-template storage_repo: \(aqLocal storage\(aq clone: False minion: master: 10.0.0.20 w2k12: provider: myxen image: w2k12svr\-template clone: True userdata_file: /srv/salt/win/files/windows\-firewall.ps1 win_installer: /srv/salt/win/files/Salt\-Minion\-2016.11.3\-AMD64\-Setup.exe win_username: Administrator win_password: p@ssw0rd use_winrm: False ipv4_cidr: 10.0.0.215/24 ipv4_gw: 10.0.0.1 minion: master: 10.0.0.21 .ft P .fi .UNINDENT .UNINDENT .sp The first example will create a clone of the sles12sp2\-template in the same storage repository without deploying the Salt minion. .sp The second example will make a copy of the image and deploy a new suse VM with the Salt minion installed. .sp The third example will create a clone of the Windows 2012 template and deploy the Salt minion. .sp The profile can be used with a salt command: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-p suse xenvm02 .ft P .fi .UNINDENT .UNINDENT .sp This will create an salt minion instance named \fBxenvm02\fP in Xen. 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 xenvm02 test.version .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 myxen .ft P .fi .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 Since size information is build in a template this command is not implemented. .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 myxen .ft P .fi .UNINDENT .UNINDENT .sp This command will return a list of templates with details. .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 myxen .ft P .fi .UNINDENT .UNINDENT .sp Returns a list of resource pools. .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: \(aq| head\(aq .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, syndics 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 \fBmake_master\fP 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 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 its 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 Running Pre\-Flight Commands .sp New in version 2018.3.0. .sp To execute specified preflight shell commands on a VM before the deploy script is run, use the \fBpreflight_cmds\fP option. These must be defined as a list in a cloud configuration file. For example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C my\-cloud\-profile: provider: linode\-config image: Ubuntu 16.04 LTS size: Linode 2048 preflight_cmds: \- whoami \- echo \(aqhello world!\(aq .ft P .fi .UNINDENT .UNINDENT .sp These commands will run in sequence \fBbefore\fP the bootstrap script is executed. .SS Force Minion Config .sp New in version 2018.3.0. .sp The \fBforce_minion_config\fP option requests the bootstrap process to overwrite an existing minion configuration file and public/private key files. Default: False .sp This might be important for drivers (such as \fBsaltify\fP) which are expected to take over a connection from a former salt master. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C my_saltify_provider: driver: saltify force_minion_config: true .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. .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/master/salt/cloud/clouds/msazure.py\fP .SS The get_configured_provider() Function .sp This function uses \fBconfig.is_provider_configured()\fP to determine whether 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/master/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 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 import salt.utils.functools .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 = salt.utils.functools.namespaced_function(get_size, globals()) get_image = salt.utils.functools.namespaced_function(get_image, globals()) avail_locations = salt.utils.functools.namespaced_function(avail_locations, globals()) avail_images = salt.utils.functools.namespaced_function(avail_images, globals()) avail_sizes = salt.utils.functools.namespaced_function(avail_sizes, globals()) script = salt.utils.functools.namespaced_function(script, globals()) destroy = salt.utils.functools.namespaced_function(destroy, globals()) list_nodes = salt.utils.functools.namespaced_function(list_nodes, globals()) list_nodes_full = salt.utils.functools.namespaced_function(list_nodes_full, globals()) list_nodes_select = salt.utils.functools.namespaced_function( list_nodes_select, globals() ) show_instance = salt.utils.functools.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/master/salt/cloud/clouds/digitalocean.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): """ Return a list of the VMs that are on the provider, with select fields """ return salt.utils.cloud.list_nodes_select( list_nodes_full("function"), __opts__["query.selection"], 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): """ Return a list of the VMs that are on the provider, with select fields """ if not conn: conn = get_conn() # pylint: disable=E0602 return salt.utils.cloud.list_nodes_select( list_nodes_full(conn, "function"), __opts__["query.selection"], 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): """ Show the details from EC2 concerning an AMI """ if call != "action": raise SaltCloudSystemExit( "The show_instance action must be called with \-a or \-\-action." ) 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): """ Show the details from EC2 concerning an AMI """ if call != "function": raise SaltCloudSystemExit( "The show_image action must be called with \-f or \-\-function." ) params = {"ImageId.1": kwargs["image"], "Action": "DescribeImages"} 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/blob/master/salt/cloud/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.version\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: \(aq| head\(aq .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: \- cloud_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("/etc/salt/cloud") 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|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{ Vagrant T} T{ Softlayer T} T{ Softlayer Hardware T} T{ Aliyun T} T{ Tencent Cloud 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{ [1] T} T{ [1] T} T{ Yes 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{ [1] T} T{ [1] T} T{ Yes 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{ [1] T} T{ [1] T} T{ Yes 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{ [2] T} T{ [2] T} T{ Yes 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{ Yes T} T{ Yes T} T{ Yes 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{ [2] T} T{ [2] T} T{ Yes 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{ [1] 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{ [1] T} T{ [1] T} T{ Yes T} T{ Yes T} T{ Yes T} T{ Yes T} _ .TE .sp [1] Yes, if salt\-api is enabled. .sp [2] Always returns \fI{}\fP\&. .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|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{ .INDENT 0.0 .TP .B Saltify& Vagrant .UNINDENT T} T{ Softlayer T} T{ Softlayer Hardware T} T{ Aliyun T} T{ Tencent Cloud 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{ 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{ 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{ 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{ 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{ 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{ 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{ 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{ 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{ 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{ 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{ 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{ 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{ 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{ 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{ 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{ 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{ 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} 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|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{ .INDENT 0.0 .TP .B Saltify& Vagrant .UNINDENT T} T{ Softlayer T} T{ Softlayer Hardware T} T{ Aliyun T} T{ Tencent Cloud 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{ 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{ 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{ 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{ 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{ 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{ 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{ 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{ 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{ 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{ 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{ 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{ 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{ 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{ 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{ 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{ 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{ 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{ 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{ 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{ 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{ 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{ 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{ Yes 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{ 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{ 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{ 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{ 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{ 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{ 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{ [1] T} T{ T} T{ T} T{ Yes 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{ 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{ 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{ 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{ 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{ 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{ T} _ T{ show_volume T} T{ T} T{ T} T{ T} T{ Yes T} T{ T} T{ T} T{ T} T{ T} T{ T} T{ T} T{ T} T{ T} T{ T} T{ T} T{ T} _ .TE .sp [1] Yes, if salt\-api is enabled. .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 Alternatively, the \fB\-L\fP option can be passed to the \fI\%Salt Bootstrap\fP script when installing Salt. The \fB\-L\fP option will install \fBsalt\-cloud\fP and the required \fBlibcloud\fP package. .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 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 {"name": "web1", "profile": "ec2\-centos", "provider": "ec2\-config:ec2"} .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 Filtering Events .sp When creating a VM, it is possible with certain tags to filter how much information is sent to the event bus. The tags that can be filtered on any provider are: .INDENT 0.0 .IP \(bu 2 \fBsalt/cloud//creating\fP .IP \(bu 2 \fBsalt/cloud//requesting\fP .IP \(bu 2 \fBsalt/cloud//created\fP .UNINDENT .sp Other providers may allow other tags to be filtered; when that is the case, the documentation for that provider will contain more details. .sp To filter information, create a section in your \fB/etc/salt/cloud\fP file called \fBfilter_events\fP\&. Create a section for each tag that you want to filter, using the last segment of the tag. For instance, use \fBcreating\fP to represent \fBsalt/cloud//creating\fP: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C filter_events: creating: keys: \- name \- profile \- provider .ft P .fi .UNINDENT .UNINDENT .sp Any keys listed here will be added to the default keys that are already set to be displayed for that provider. If you wish to start with a clean slate and only show the keys specified, add another option called \fBuse_defaults\fP and set it to \fBFalse\fP\&. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C filter_events: creating: keys: \- name \- profile \- provider use_defaults: False .ft P .fi .UNINDENT .UNINDENT .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 There are some proxy modules available, but if your device interface is not currently supported you will most likely have to write the interface yourself, because there are an infinite number of controllable devices. 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 2017.7.0 .sp The \fBproxy_merge_grains_in_module\fP configuration variable introduced in 2016.3, has been changed, defaulting to \fBTrue\fP\&. .sp The connection with the remote device is kept alive by default, when the module implements the \fBalive\fP function and \fBproxy_keep_alive\fP is set to \fBTrue\fP\&. The polling interval is set using the \fBproxy_keep_alive_interval\fP option which defaults to 1 minute. .sp The developers are also able to use the \fBproxy_always_alive\fP, when designing a proxy module flexible enough to open the connection with the remote device only when required. .SS New in 2016.11.0 .sp Proxy minions now support configuration files with names ending in \(aq*.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__(): """ Only work on proxy """ try: if ( salt.utils.platform.is_proxy() and __opts__["proxy"]["proxytype"] == "ssh_sample" ): 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): """ Ask the remote device what IP it has """ return {"ip": proxy["proxymodulename.get_ip"]()} .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 \fBTrue\fP in the \fB2017.7.0\fP release. .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. \fBNOTE: This function was renamed to salt.utils.platform.is_proxy() for the 2018.3.0 release\fP .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 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: net\-device1: \- net\-device1 net\-device2: \- net\-device2 net\-device3: \- net\-device3 i2c\-device4: \- i2c\-device4 i2c\-device5: \- i2c\-device5 433wireless\-device6: \- 433wireless\-device6 smsgate\-device7: \- device7 .ft P .fi .UNINDENT .UNINDENT .sp \fB/srv/pillar/net\-device1.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/net\-device2.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/net\-device3.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/i2c\-device4.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/i2c\-device5.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/433wireless\-device6.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/smsgate\-device7.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 net\-devices 1, 2, and 3 are network switches that have a management interface available at a particular IP address. .IP \(bu 2 i2c\-devices 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 433wireless\-device6 is a 433 MHz wireless transmitter, also physically connected to minioncontroller2 .IP \(bu 2 smsgate\-device7 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 \fBalive(opts)\fP: Another optional function, it is used together with the \fBproxy_keep_alive\fP option (default: \fBTrue\fP). This function should return a boolean value corresponding to the state of the connection. If the connection is down, will try to restart (\fBshutdown\fP followed by \fBinit\fP). The polling frequency is controlled using the \fBproxy_keep_alive_interval\fP option, in minutes. .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 \fBTrue\fP in the release code\-named \fI2017.7.0\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 \-*\- """ 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 """ 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__ = ["rest_sample"] # 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__(): """ Only return if all the modules are available """ log.debug("rest_sample proxy __virtual__() called...") return True def _complicated_function_that_determines_if_alive(): 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("rest_sample proxy init() called...") DETAILS["initialized"] = True # Save the REST URL DETAILS["url"] = opts["proxy"]["url"] # Make sure the REST URL ends with a \(aq/\(aq if not DETAILS["url"].endswith("/"): DETAILS["url"] += "/" def alive(opts): """ This function returns a flag with the connection state. It is very useful when the proxy minion establishes the communication via a channel that requires a more elaborated keep\-alive mechanism, e.g. NETCONF over SSH. """ log.debug("rest_sample proxy alive() called...") return _complicated_function_that_determines_if_alive() def initialized(): """ 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 """ return DETAILS.get("initialized", False) def grains(): """ Get the grains from the proxied device """ if not DETAILS.get("grains_cache", {}): r = salt.utils.http.query( DETAILS["url"] + "info", decode_type="json", decode=True ) DETAILS["grains_cache"] = r["dict"] return DETAILS["grains_cache"] def grains_refresh(): """ Refresh the grains from the proxied device """ DETAILS["grains_cache"] = None return grains() def fns(): return { "details": "This key is here because a function in " "grains/rest_sample.py called fns() here in the proxymodule." } def service_start(name): """ Start a "service" on the REST server """ r = salt.utils.http.query( DETAILS["url"] + "service/start/" + name, decode_type="json", decode=True ) return r["dict"] def service_stop(name): """ Stop a "service" on the REST server """ r = salt.utils.http.query( DETAILS["url"] + "service/stop/" + name, decode_type="json", decode=True ) return r["dict"] def service_restart(name): """ Restart a "service" on the REST server """ r = salt.utils.http.query( DETAILS["url"] + "service/restart/" + name, decode_type="json", decode=True ) return r["dict"] def service_list(): """ List "services" on the REST server """ r = salt.utils.http.query( DETAILS["url"] + "service/list", decode_type="json", decode=True ) return r["dict"] def service_status(name): """ Check if a service is running on the REST server """ r = salt.utils.http.query( DETAILS["url"] + "service/status/" + name, decode_type="json", decode=True ) return r["dict"] def package_list(): """ List "packages" installed on the REST server """ r = salt.utils.http.query( DETAILS["url"] + "package/list", decode_type="json", decode=True ) return r["dict"] def package_install(name, **kwargs): """ Install a "package" on the REST server """ cmd = DETAILS["url"] + "package/install/" + name if kwargs.get("version", False): cmd += "/" + kwargs["version"] else: cmd += "/1.0" r = salt.utils.http.query(cmd, decode_type="json", decode=True) return r["dict"] def fix_outage(): r = salt.utils.http.query(DETAILS["url"] + "fix_outage") return r def uptodate(name): """ Call the REST endpoint to see if the packages on the "server" are up to date. """ r = salt.utils.http.query( DETAILS["url"] + "package/remove/" + name, decode_type="json", decode=True ) return r["dict"] def package_remove(name): """ Remove a "package" on the REST server """ r = salt.utils.http.query( DETAILS["url"] + "package/remove/" + name, decode_type="json", decode=True ) return r["dict"] def package_status(name): """ Check the installation status of a package on the REST server """ r = salt.utils.http.query( DETAILS["url"] + "package/status/" + name, decode_type="json", decode=True ) return r["dict"] def ping(): """ Is the REST server up? """ r = salt.utils.http.query(DETAILS["url"] + "ping", decode_type="json", decode=True) try: return r["dict"].get("ret", False) except Exception: return False def shutdown(opts): """ For this proxy shutdown is a no\-op """ log.debug("rest_sample proxy shutdown() called...") .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 communicate 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 defaults to \fBTrue\fP in the release code\-named \fI2017.7.0\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 \-*\- """ Generate baseline proxy minion grains """ from __future__ import absolute_import import salt.utils.platform __proxyenabled__ = ["rest_sample"] __virtualname__ = "rest_sample" def __virtual__(): try: if ( salt.utils.platform.is_proxy() and __opts__["proxy"]["proxytype"] == "rest_sample" ): 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 \fB/srv/pillar/p8000.sls\fP (if you have not changed your default pillar_roots) .INDENT 0.0 .IP 3. 3 In the pillar root for your base environment, create the \fBp8000.sls\fP file with the following contents: .UNINDENT .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C 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.version .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 \-*\- """ 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. """ from __future__ import absolute_import # Import python libs import salt.utils.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__ = ["ssh_sample"] 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__(): """ Only return if all the modules are available """ log.info("ssh_sample proxy __virtual__() called...") return True def init(opts): """ Required. Can be used to initialize the server connection. """ try: DETAILS["server"] = SSHConnection( host=__opts__["proxy"]["host"], username=__opts__["proxy"]["username"], password=__opts__["proxy"]["password"], ) # connected to the SSH server out, err = DETAILS["server"].sendline("help") except TerminalException as e: log.error(e) return False def shutdown(opts): """ Disconnect """ DETAILS["server"].close_connection() def parse(out): """ Extract json from out. Parameter out: Type string. The data returned by the ssh command. """ jsonret = [] in_json = False for ln_ in out.split("\en"): if "{" in ln_: in_json = True if in_json: jsonret.append(ln_) if "}" in ln_: in_json = False return salt.utils.json.loads("\en".join(jsonret)) def package_list(): """ 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 """ # Send the command to execute out, err = DETAILS["server"].sendline("pkg_list") # "scrape" the output and return the right fields as a dict return parse(out) def package_install(name, **kwargs): """ Install a "package" on the REST server """ cmd = "pkg_install " + name if "version" in kwargs: cmd += "/" + kwargs["version"] else: cmd += "/1.0" # Send the command to execute out, err = DETAILS["server"].sendline(cmd) # "scrape" the output and return the right fields as a dict return parse(out) def package_remove(name): """ Remove a "package" on the REST server """ cmd = "pkg_remove " + name # Send the command to execute out, err = DETAILS["server"].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 \fB/srv/pillar/p8000.sls\fP (if you have not changed your default pillar_roots) .INDENT 0.0 .IP 3. 3 In the pillar root for your base environment, create the \fBp8000.sls\fP file with the following contents: .UNINDENT .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C 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 \fB/srv/pillar/p8000.sls\fP (if you have not changed your default pillar_roots) .INDENT 0.0 .IP 2. 3 In the pillar root for your base environment, create the \fBp8000.sls\fP file with the following contents: .UNINDENT .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C 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: \- proxies: p8000: {} p8001: {} .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 \fB/srv/pillar/p8000.sls\fP (if you have not changed your default pillar_roots) .INDENT 0.0 .IP 2. 3 In the pillar root for your base environment, create the \fBp8000.sls\fP file with the following contents: .UNINDENT .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C 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 .SH NETWORK AUTOMATION .sp Network automation is a continuous process of automating the configuration, management and operations of a computer network. Although the abstraction could be compared with the operations on the server side, there are many particular challenges, the most important being that a network device is traditionally closed hardware able to run proprietary software only. In other words, the user is not able to install the salt\-minion package directly on a traditional network device. For these reasons, most network devices can be controlled only remotely via proxy minions or using the Salt SSH\&. However, there are also vendors producing whitebox equipment (e.g. Arista, Cumulus) or others that have moved the operating system in the container (e.g. Cisco NX\-OS, Cisco IOS\-XR), allowing the salt\-minion to be installed directly on the platform. .SS New in Carbon (2016.11) .sp The methodologies for network automation have been introduced in 2016.11.0\&. Network automation support is based on proxy minions. .INDENT 0.0 .IP \(bu 2 \fBNAPALM proxy\fP .IP \(bu 2 \fBJunos proxy\fP .IP \(bu 2 \fBCisco NXOS\fP .IP \(bu 2 \fBCisco NOS\fP .UNINDENT .SS NAPALM .sp NAPALM (Network Automation and Programmability Abstraction Layer with Multivendor support) is an opensourced Python library that implements a set of functions to interact with different router vendor devices using a unified API. Being vendor\-agnostic simplifies operations, as the configuration and interaction with the network device does not rely on a particular vendor. [image] .sp Beginning with 2017.7.0, the NAPALM modules have been transformed so they can run in both proxy and regular minions. That means, if the operating system allows, the salt\-minion package can be installed directly on the network gear. The interface between the network operating system and Salt in that case would be the corresponding NAPALM sub\-package. .sp For example, if the user installs the salt\-minion on a Arista switch, the only requirement is \fI\%napalm\-eos\fP\&. .sp The following modules are available in 2017.7.0: .INDENT 0.0 .IP \(bu 2 \fBNAPALM grains\fP .IP \(bu 2 \fBNET execution module\fP \- Networking basic features .IP \(bu 2 \fBNTP execution module\fP .IP \(bu 2 \fBBGP execution module\fP .IP \(bu 2 \fBRoutes execution module\fP .IP \(bu 2 \fBSNMP execution module\fP .IP \(bu 2 \fBUsers execution module\fP .IP \(bu 2 \fBProbes execution module\fP .IP \(bu 2 \fBNTP peers management state\fP .IP \(bu 2 \fBSNMP configuration management state\fP .IP \(bu 2 \fBUsers management state\fP .IP \(bu 2 \fBNetconfig state module\fP \- Manage the configuration of network devices using arbitrary templates and the Salt\-specific advanced templating methodologies. .IP \(bu 2 \fBNetwork ACL execution module\fP \- Generate and load ACL (firewall) configuration on network devices. .IP \(bu 2 \fBNetwork ACL state\fP \- Manage the firewall configuration. It only requires writing the pillar structure correctly! .IP \(bu 2 \fBNAPALM YANG execution module\fP \- Parse, generate and load native device configuration in a standard way, using the OpenConfig/IETF models. This module contains also helpers for the states. .IP \(bu 2 \fBNAPALM YANG state module\fP \- Manage the network device configuration according to the YANG models (OpenConfig or IETF). .IP \(bu 2 \fBNET finder\fP \- Runner to find details easily and fast. It\(aqs smart enough to know what you are looking for. It will search in the details of the network interfaces, IP addresses, MAC address tables, ARP tables and LLDP neighbors. .IP \(bu 2 \fBBGP finder\fP \- Runner to search BGP neighbors details. .IP \(bu 2 \fBNAPALM syslog\fP \- Engine to import events from the napalm\-logs library into the Salt event bus. The events are based on the syslog messages from the network devices and structured following the OpenConfig/IETF YANG models. .IP \(bu 2 \fBNAPALM Helpers\fP \- Generic helpers for NAPALM\-related operations. For example, the \fBCompliance report\fP function can be used inside the state modules to compare the expected and the existing configuration. .UNINDENT .SS Getting started .sp Install NAPALM \- follow the \fI\%notes\fP and check the platform\-specific \fI\%dependencies\fP\&. .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 \fBpillar_roots\fP, or through an external pillar. External pillars afford the opportunity for interfacing with a configuration management system, database, or other knowledgeable system that may already contain all the details of proxy targets. To use static files in \fBpillar_roots\fP, pattern your files after the following examples: .sp \fB/etc/salt/pillar/top.sls\fP .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C base: router1: \- router1 router2: \- router2 switch1: \- switch1 switch2: \- switch2 cpe1: \- cpe1 .ft P .fi .UNINDENT .UNINDENT .sp \fB/etc/salt/pillar/router1.sls\fP .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C proxy: proxytype: napalm driver: junos host: r1.bbone.as1234.net username: my_username password: my_password .ft P .fi .UNINDENT .UNINDENT .sp \fB/etc/salt/pillar/router2.sls\fP .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C proxy: proxytype: napalm driver: iosxr host: r2.bbone.as1234.net username: my_username password: my_password optional_args: port: 22022 .ft P .fi .UNINDENT .UNINDENT .sp \fB/etc/salt/pillar/switch1.sls\fP .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C proxy: proxytype: napalm driver: eos host: sw1.bbone.as1234.net username: my_username password: my_password optional_args: enable_password: my_secret .ft P .fi .UNINDENT .UNINDENT .sp \fB/etc/salt/pillar/switch2.sls\fP .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C proxy: proxytype: napalm driver: nxos host: sw2.bbone.as1234.net username: my_username password: my_password .ft P .fi .UNINDENT .UNINDENT .sp \fB/etc/salt/pillar/cpe1.sls\fP .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C proxy: proxytype: napalm driver: ios host: cpe1.edge.as1234.net username: \(aq\(aq password: \(aq\(aq optional_args: use_keys: True auto_rollback_on_error: True .ft P .fi .UNINDENT .UNINDENT .SS CLI examples .sp Display the complete running configuration on \fBrouter1\fP: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C $ sudo salt \(aqrouter1\(aq net.config source=\(aqrunning\(aq .ft P .fi .UNINDENT .UNINDENT .sp Retrieve the NTP servers configured on all devices: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C $ sudo salt \(aq*\(aq ntp.servers router1: \-\-\-\-\-\-\-\-\-\- comment: out: \- 1.2.3.4 result: True cpe1: \-\-\-\-\-\-\-\-\-\- comment: out: \- 1.2.3.4 result: True switch2: \-\-\-\-\-\-\-\-\-\- comment: out: \- 1.2.3.4 result: True router2: \-\-\-\-\-\-\-\-\-\- comment: out: \- 1.2.3.4 result: True switch1: \-\-\-\-\-\-\-\-\-\- comment: out: \- 1.2.3.4 result: True .ft P .fi .UNINDENT .UNINDENT .sp Display the ARP tables on all Cisco devices running IOS\-XR 5.3.3: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C $ sudo salt \-G \(aqos:iosxr and version:5.3.3\(aq net.arp .ft P .fi .UNINDENT .UNINDENT .sp Return operational details for interfaces from Arista switches: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C $ sudo salt \-C \(aqsw* and os:eos\(aq net.interfaces .ft P .fi .UNINDENT .UNINDENT .sp Execute traceroute from the edge of the network: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C $ sudo salt \(aqrouter*\(aq net.traceroute 8.8.8.8 vrf=\(aqCUSTOMER1\-VRF\(aq .ft P .fi .UNINDENT .UNINDENT .sp Verbatim display from the CLI of Juniper routers: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C $ sudo salt \-C \(aqrouter* and G@os:junos\(aq net.cli \(aqshow version and haiku\(aq .ft P .fi .UNINDENT .UNINDENT .sp Retrieve the results of the RPM probes configured on Juniper MX960 routers: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C $ sudo salt \-C \(aqrouter* and G@os:junos and G@model:MX960\(aq probes.results .ft P .fi .UNINDENT .UNINDENT .sp Return the list of configured users on the CPEs: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C $ sudo salt \(aqcpe*\(aq users.config .ft P .fi .UNINDENT .UNINDENT .sp Using the \fBBGP finder\fP, return the list of BGP neighbors that are down: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C $ sudo salt\-run bgp.neighbors up=False .ft P .fi .UNINDENT .UNINDENT .sp Using the \fBNET finder\fP, determine the devices containing the pattern "PX\-1234\-LHR" in their interface description: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C $ sudo salt\-run net.find PX\-1234\-LHR .ft P .fi .UNINDENT .UNINDENT .SS Cross\-platform configuration management example: NTP .sp Assuming that the user adds the following two lines under \fBfile_roots\fP: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C file_roots: base: \- /etc/salt/pillar/ \- /etc/salt/templates/ \- /etc/salt/states/ .ft P .fi .UNINDENT .UNINDENT .sp Define the list of NTP peers and servers wanted: .sp \fB/etc/salt/pillar/ntp.sls\fP .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C ntp.servers: \- 1.2.3.4 \- 5.6.7.8 ntp.peers: \- 10.11.12.13 \- 14.15.16.17 .ft P .fi .UNINDENT .UNINDENT .sp Include the new file: for example, if we want to have the same NTP servers on all network devices, we can add the following line inside the \fBtop.sls\fP file: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C \(aq*\(aq: \- ntp .ft P .fi .UNINDENT .UNINDENT .sp \fB/etc/salt/pillar/top.sls\fP .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C base: \(aq*\(aq: \- ntp router1: \- router1 router2: \- router2 switch1: \- switch1 switch2: \- switch2 cpe1: \- cpe1 .ft P .fi .UNINDENT .UNINDENT .sp Or include only where needed: .sp \fB/etc/salt/pillar/top.sls\fP .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C base: router1: \- router1 \- ntp router2: \- router2 \- ntp switch1: \- switch1 switch2: \- switch2 cpe1: \- cpe1 .ft P .fi .UNINDENT .UNINDENT .sp Define the cross\-vendor template: .sp \fB/etc/salt/templates/ntp.jinja\fP .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C {%\- if grains.vendor|lower == \(aqcisco\(aq %} no ntp {%\- for server in servers %} ntp server {{ server }} {%\- endfor %} {%\- for peer in peers %} ntp peer {{ peer }} {%\- endfor %} {%\- elif grains.os|lower == \(aqjunos\(aq %} system { replace: ntp { {%\- for server in servers %} server {{ server }}; {%\- endfor %} {%\- for peer in peers %} peer {{ peer }}; {%\- endfor %} } } {%\- endif %} .ft P .fi .UNINDENT .UNINDENT .sp Define the SLS state file, making use of the \fBNetconfig state module\fP: .sp \fB/etc/salt/states/router/ntp.sls\fP .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C ntp_config_example: netconfig.managed: \- template_name: salt://ntp.jinja \- peers: {{ pillar.get(\(aqntp.peers\(aq, []) | json }} \- servers: {{ pillar.get(\(aqntp.servers\(aq, []) | json }} .ft P .fi .UNINDENT .UNINDENT .sp Run the state and assure NTP configuration consistency across your multi\-vendor network: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C $ sudo salt \(aqrouter*\(aq state.sls router.ntp .ft P .fi .UNINDENT .UNINDENT .sp Besides CLI, the state can be scheduled or executed when triggered by a certain event. .SS JUNOS .sp Juniper has developed a Junos specific proxy infrastructure which allows remote execution and configuration management of Junos devices without having to install SaltStack on the device. The infrastructure includes: .INDENT 0.0 .IP \(bu 2 \fBJunos proxy\fP .IP \(bu 2 \fBJunos execution module\fP .IP \(bu 2 \fBJunos state module\fP .IP \(bu 2 \fBJunos syslog engine\fP .UNINDENT .sp The execution and state modules are implemented using junos\-eznc (PyEZ). Junos PyEZ is a microframework for Python that enables you to remotely manage and automate devices running the Junos operating system. .SS Getting started .sp Install PyEZ on the system which will run the Junos proxy minion. It is required to run Junos specific modules. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C pip install junos\-eznc .ft P .fi .UNINDENT .UNINDENT .sp Next, set the master of the proxy minions. .sp \fB/etc/salt/proxy\fP .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C master: .ft P .fi .UNINDENT .UNINDENT .sp Add the details of the Junos device. Device details are usually stored in salt pillars. If the you do not wish to store credentials in the pillar, one can setup passwordless ssh. .sp \fB/srv/pillar/vmx_details.sls\fP .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C proxy: proxytype: junos host: username: user passwd: secret123 .ft P .fi .UNINDENT .UNINDENT .sp Map the pillar file to the proxy minion. This is done in the top file. .sp \fB/srv/pillar/top.sls\fP .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C base: vmx: \- vmx_details .ft P .fi .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 Before starting the Junos proxy make sure that netconf is enabled on the Junos device. This can be done by adding the following configuration on the Junos device. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C set system services netconf ssh .ft P .fi .UNINDENT .UNINDENT .UNINDENT .UNINDENT .sp Start the salt master. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt\-master \-l debug .ft P .fi .UNINDENT .UNINDENT .sp Then start the salt proxy. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt\-proxy \-\-proxyid=vmx \-l debug .ft P .fi .UNINDENT .UNINDENT .sp Once the master and junos proxy minion have started, we can run execution and state modules on the proxy minion. Below are few examples. .SS CLI examples .sp For detailed documentation of all the junos execution modules refer: \fBJunos execution module\fP .sp Display device facts. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C $ sudo salt \(aqvmx\(aq junos.facts .ft P .fi .UNINDENT .UNINDENT .sp Refresh the Junos facts. This function will also refresh the facts which are stored in salt grains. (Junos proxy stores Junos facts in the salt grains) .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C $ sudo salt \(aqvmx\(aq junos.facts_refresh .ft P .fi .UNINDENT .UNINDENT .sp Call an RPC. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C $ sudo salt \(aqvmx\(aq junos.rpc \(aqget\-interface\-information\(aq \(aq/var/log/interface\-info.txt\(aq terse=True .ft P .fi .UNINDENT .UNINDENT .sp Install config on the device. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C $ sudo salt \(aqvmx\(aq junos.install_config \(aqsalt://my_config.set\(aq .ft P .fi .UNINDENT .UNINDENT .sp Shutdown the junos device. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C $ sudo salt \(aqvmx\(aq junos.shutdown shutdown=True in_min=10 .ft P .fi .UNINDENT .UNINDENT .SS State file examples .sp For detailed documentation of all the junos state modules refer: \fBJunos state module\fP .sp Executing an RPC on Junos device and storing the output in a file. .sp \fB/srv/salt/rpc.sls\fP .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C get\-interface\-information: junos: \- rpc \- dest: /home/user/rpc.log \- interface_name: lo0 .ft P .fi .UNINDENT .UNINDENT .sp Lock the junos device, load the configuration, commit it and unlock the device. .sp \fB/srv/salt/load.sls\fP .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C lock the config: junos.lock salt://configs/my_config.set: junos: \- install_config \- timeout: 100 \- diffs_file: \(aqvar/log/diff\(aq commit the changes: junos: \- commit unlock the config: junos.unlock .ft P .fi .UNINDENT .UNINDENT .sp According to the device personality install appropriate image on the device. .sp \fB/srv/salt/image_install.sls\fP .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C {% if grains[\(aqjunos_facts\(aq][\(aqpersonality\(aq] == MX %} salt://images/mx_junos_image.tgz: junos: \- install_os \- timeout: 100 \- reboot: True {% elif grains[\(aqjunos_facts\(aq][\(aqpersonality\(aq] == EX %} salt://images/ex_junos_image.tgz: junos: \- install_os \- timeout: 150 {% elif grains[\(aqjunos_facts\(aq][\(aqpersonality\(aq] == SRX %} salt://images/srx_junos_image.tgz: junos: \- install_os \- timeout: 150 {% endif %} .ft P .fi .UNINDENT .UNINDENT .SS Junos Syslog Engine .sp \fBJunos Syslog Engine\fP is a Salt engine which receives data from various Junos devices, extracts event information and forwards it on the master/minion event bus. To start the engine on the salt master, add the following configuration in the master config file. The engine can also run on the salt minion. .sp \fB/etc/salt/master\fP .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C engines: \- junos_syslog: port: xxx .ft P .fi .UNINDENT .UNINDENT .sp For junos_syslog engine to receive events, syslog must be set on the Junos device. This can be done via following configuration: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C set system syslog host port xxx any any .ft P .fi .UNINDENT .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. .SH COMMAND LINE REFERENCE .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 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 \fBhighstate\fP, \fBjson\fP, \fBkey\fP, \fBoverstatestage\fP, \fBpprint\fP, \fBraw\fP, \fBtxt\fP, \fByaml\fP, and many others\&. .UNINDENT .UNINDENT .sp Some outputters are formatted only for data returned from specific functions. 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. .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 \-\-out\-file\-append, \-\-output\-file\-append Append 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 .INDENT 0.0 .TP .B \-\-state\-output=STATE_OUTPUT, \-\-state_output=STATE_OUTPUT Override the configured state_output value for minion output. One of \(aqfull\(aq, \(aqterse\(aq, \(aqmixed\(aq, \(aqchanges\(aq or \(aqfilter\(aq. Default: \(aqnone\(aq. .UNINDENT .INDENT 0.0 .TP .B \-\-state\-verbose=STATE_VERBOSE, \-\-state_verbose=STATE_VERBOSE Override the configured state_verbose value for minion output. Set to True or False. Default: none. .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.version .sp salt \-C \fI\%\(aqG@os\fP:Arch.* and webserv* or \fI\%G@kernel\fP:FreeBSD\(aq [ options ] test.version .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 \-\-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, and \fIpam\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 \fBhighstate\fP, \fBjson\fP, \fBkey\fP, \fBoverstatestage\fP, \fBpprint\fP, \fBraw\fP, \fBtxt\fP, \fByaml\fP, and many others\&. .UNINDENT .UNINDENT .sp Some outputters are formatted only for data returned from specific functions. 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. .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 \-\-out\-file\-append, \-\-output\-file\-append Append 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 .INDENT 0.0 .TP .B \-\-state\-output=STATE_OUTPUT, \-\-state_output=STATE_OUTPUT Override the configured state_output value for minion output. One of \(aqfull\(aq, \(aqterse\(aq, \(aqmixed\(aq, \(aqchanges\(aq or \(aqfilter\(aq. Default: \(aqnone\(aq. .UNINDENT .INDENT 0.0 .TP .B \-\-state\-verbose=STATE_VERBOSE, \-\-state_verbose=STATE_VERBOSE Override the configured state_verbose value for minion output. Set to True or False. Default: none. .UNINDENT .sp \fBNOTE:\fP .INDENT 0.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 .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 or files to one or more minions .SS Synopsis .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt\-cp \(aq*\(aq [ options ] SOURCE [SOURCE2 SOURCE3 ...] DEST salt\-cp \-E \(aq.*\(aq [ options ] SOURCE [SOURCE2 SOURCE3 ...] DEST salt\-cp \-G \(aqos:Arch.*\(aq [ options ] SOURCE [SOURCE2 SOURCE3 ...] DEST .ft P .fi .UNINDENT .UNINDENT .SS Description .sp salt\-cp copies files from the master to all of the Salt minions matched by the specified target expression. .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 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 master or minion is running with debug logging, the contents of the file will be logged to disk. .sp In addition, this tool is less efficient than the Salt fileserver when copying larger files. It is recommended to instead use \fBcp.get_file\fP to copy larger files to minions. However, this requires the file to be located within one of the fileserver directories. .UNINDENT .UNINDENT .sp Changed in version 2016.3.7,2016.11.6,2017.7.0: Compression support added, disable with \fB\-n\fP\&. Also, if the destination path ends in a path separator (i.e. \fB/\fP, or \fB\e\fP on Windows, the desitination will be assumed to be a directory. Finally, recursion is now supported, allowing for entire directories to be copied. .sp Changed in version 2016.11.7,2017.7.2: Reverted back to the old copy mode to preserve backward compatibility. The new functionality added in 2016.6.6 and 2017.7.0 is now available using the \fB\-C\fP or \fB\-\-chunked\fP CLI arguments. Note that compression, recursive copying, and support for copying large files is only available in chunked mode. .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 .INDENT 0.0 .TP .B \-C, \-\-chunked Use new chunked mode to copy files. This mode supports large files, recursive directories copying and compression. .sp New in version 2016.11.7,2017.7.2. .UNINDENT .INDENT 0.0 .TP .B \-n, \-\-no\-compression Disable gzip compression in chunked mode. .sp New in version 2016.3.7,2016.11.6,2017.7.0. .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 \fBhighstate\fP, \fBjson\fP, \fBkey\fP, \fBoverstatestage\fP, \fBpprint\fP, \fBraw\fP, \fBtxt\fP, \fByaml\fP, and many others\&. .UNINDENT .UNINDENT .sp Some outputters are formatted only for data returned from specific functions. 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. .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 \-\-out\-file\-append, \-\-output\-file\-append Append 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 .INDENT 0.0 .TP .B \-\-state\-output=STATE_OUTPUT, \-\-state_output=STATE_OUTPUT Override the configured state_output value for minion output. One of \(aqfull\(aq, \(aqterse\(aq, \(aqmixed\(aq, \(aqchanges\(aq or \(aqfilter\(aq. Default: \(aqnone\(aq. .UNINDENT .INDENT 0.0 .TP .B \-\-state\-verbose=STATE_VERBOSE, \-\-state_verbose=STATE_VERBOSE Override the configured state_verbose value for minion output. Set to True or False. Default: none. .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 \-\-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 \-r, \-\-raw, \-\-raw\-shell Execute a raw shell command. .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 \-\-extra\-filerefs=EXTRA_FILEREFS Pass in extra files to include in the state tarball. .UNINDENT .INDENT 0.0 .TP .B \-\-min\-extra\-modules=MIN_EXTRA_MODS One or comma\-separated list of extra Python modulesto be included into Minimal Salt. .UNINDENT .INDENT 0.0 .TP .B \-\-thin\-extra\-modules=THIN_EXTRA_MODS One or comma\-separated list of extra Python modulesto be included into Thin Salt. .UNINDENT .INDENT 0.0 .TP .B \-v, \-\-verbose Turn on command verbosity, display jid. .UNINDENT .INDENT 0.0 .TP .B \-s, \-\-static Return the data from minions as a group after they all return. .UNINDENT .INDENT 0.0 .TP .B \-w, \-\-wipe Remove the deployment of the salt files when done executing. .UNINDENT .INDENT 0.0 .TP .B \-W, \-\-rand\-thin\-dir Select a random temp dir to deploy on the remote system. The dir will be cleaned after the execution. .UNINDENT .INDENT 0.0 .TP .B \-t, \-\-regen\-thin, \-\-thin Trigger a thin tarball regeneration. This is needed if custom grains/modules/states have been added or updated. .UNINDENT .INDENT 0.0 .TP .B \-\-python2\-bin=PYTHON2_BIN Path to a python2 binary which has salt installed. .UNINDENT .INDENT 0.0 .TP .B \-\-python3\-bin=PYTHON3_BIN Path to a python3 binary which has salt installed. .UNINDENT .INDENT 0.0 .TP .B \-\-jid=JID Pass a JID to be used instead of generating one. .UNINDENT .INDENT 0.0 .TP .B \-\-pre\-flight Run the ssh_pre_flight script defined in the roster. By default this script will only run if the thin dir does not exist on the target minion. This option will force the script to run regardless of the thin dir existing or not. .UNINDENT .SS Authentication Options .INDENT 0.0 .TP .B \-\-priv=SSH_PRIV Specify the SSH private key file to be used for authentication. .UNINDENT .INDENT 0.0 .TP .B \-\-priv\-passwd=SSH_PRIV_PASSWD Specify the SSH private key file\(aqs passphrase if need be. .UNINDENT .INDENT 0.0 .TP .B \-i, \-\-ignore\-host\-keys By default ssh host keys are honored and connections will ask for approval. Use this option to disable StrictHostKeyChecking. .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 \-\-user=SSH_USER Set the default user to attempt to use when authenticating. .UNINDENT .INDENT 0.0 .TP .B \-\-passwd Set the default password to attempt to use when authenticating. .UNINDENT .INDENT 0.0 .TP .B \-\-askpass Interactively ask for the SSH password with no echo \- avoids password in process args and stored in history. .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 \-\-identities\-only Use the only authentication identity files configured in the ssh_config files. See IdentitiesOnly flag in man ssh_config. .UNINDENT .INDENT 0.0 .TP .B \-\-sudo Run command via sudo. .UNINDENT .SS Scan Roster Options .INDENT 0.0 .TP .B \-\-scan\-ports=SSH_SCAN_PORTS Comma\-separated list of ports to scan in the scan roster. .UNINDENT .INDENT 0.0 .TP .B \-\-scan\-timeout=SSH_SCAN_TIMEOUT Scanning socket timeout for the scan roster. .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 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 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 \fBhighstate\fP, \fBjson\fP, \fBkey\fP, \fBoverstatestage\fP, \fBpprint\fP, \fBraw\fP, \fBtxt\fP, \fByaml\fP, and many others\&. .UNINDENT .UNINDENT .sp Some outputters are formatted only for data returned from specific functions. 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. .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 \-\-out\-file\-append, \-\-output\-file\-append Append 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 .INDENT 0.0 .TP .B \-\-state\-output=STATE_OUTPUT, \-\-state_output=STATE_OUTPUT Override the configured state_output value for minion output. One of \(aqfull\(aq, \(aqterse\(aq, \(aqmixed\(aq, \(aqchanges\(aq or \(aqfilter\(aq. Default: \(aqnone\(aq. .UNINDENT .INDENT 0.0 .TP .B \-\-state\-verbose=STATE_VERBOSE, \-\-state_verbose=STATE_VERBOSE Override the configured state_verbose value for minion output. Set to True or False. Default: none. .UNINDENT .sp \fBNOTE:\fP .INDENT 0.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 .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\-unity .SS \fBsalt\-unity\fP .sp A unified invocation wrapper around other Salt CLI scripts. .SS Synopsis .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt\-unity salt \(aq*\(aq test.version .ft P .fi .UNINDENT .UNINDENT .SS Description .sp This script takes an argument which is one of the other Salt CLI scripts and invokes that script. .SS Options .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 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 PILLARS .sp Salt includes a number of built\-in external pillars, listed at all\-salt.pillars\&. .sp The below links contain documentation for the configuration options .INDENT 0.0 .IP \(bu 2 master\-side configuration .IP \(bu 2 minion\-side configuration .UNINDENT .sp Note that some of same the configuration options from the master are present in the minion configuration file, these are used in masterless mode. .sp The source for the built\-in Salt pillars can be found here: \fI\%https://github.com/saltstack/salt/blob/master/salt/pillar\fP .SH MASTER TOPS .sp Salt includes a number of built\-in subsystems to generate top file data, they are listed at all\-salt.tops\&. .sp The source for the built\-in Salt master tops can be found here: \fI\%https://github.com/saltstack/salt/blob/master/salt/tops\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 production use T} _ T{ \fBdjango\fP T} T{ Provide authentication using Django Web Framework T} _ T{ \fBfile\fP T} T{ Provide authentication using local files 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{ \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(User, on_delete=models.CASCADE) minion_or_fn_matcher = models.CharField(max_length=255) minion_fn = models.CharField(max_length=255) .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.acl(username) .INDENT 7.0 .TP .B Parameters \fBusername\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 .INDENT 0.0 .TP .B salt.auth.django.auth(username, password) Simple Django auth .UNINDENT .INDENT 0.0 .TP .B salt.auth.django.is_connection_usable() .UNINDENT .SS salt.auth.file .sp Provide authentication using local files .sp New in version 2018.3.0. .sp The \fIfile\fP auth module allows simple authentication via local files. Different filetypes are supported, including: .INDENT 0.0 .INDENT 3.5 .INDENT 0.0 .IP 1. 3 Text files, with passwords in plaintext or hashed .IP 2. 3 Apache\-style htpasswd files .IP 3. 3 Apache\-style htdigest files .UNINDENT .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 The \fBpython\-passlib\fP library is required when using a \fB^filetype\fP of \fBhtpasswd\fP or \fBhtdigest\fP\&. .UNINDENT .UNINDENT .sp The simplest example is a plaintext file with usernames and passwords: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C external_auth: file: ^filename: /etc/insecure\-user\-list.txt gene: \- .* dean: \- test.* .ft P .fi .UNINDENT .UNINDENT .sp In this example the \fB/etc/insecure\-user\-list.txt\fP file would be formatted as so: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C dean:goneFishing gene:OceanMan .ft P .fi .UNINDENT .UNINDENT .sp \fB^filename\fP is the only required parameter. Any parameter that begins with a \fB^\fP is passed directly to the underlying file authentication function via \fBkwargs\fP, with the leading \fB^\fP being stripped. .sp The text file option is configurable to work with legacy formats: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C external_auth: file: ^filename: /etc/legacy_users.txt ^filetype: text ^hashtype: md5 ^username_field: 2 ^password_field: 3 ^field_separator: \(aq|\(aq trey: \- .* .ft P .fi .UNINDENT .UNINDENT .sp This would authenticate users against a file of the following format: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C 46|trey|16a0034f90b06bf3c5982ed8ac41aab4 555|mike|b6e02a4d2cb2a6ef0669e79be6fd02e4 2001|page|14fce21db306a43d3b680da1a527847a 8888|jon|c4e94ba906578ccf494d71f45795c6cb .ft P .fi .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 The \fBhashutil.digest\fP execution function is used for comparing hashed passwords, so any algorithm supported by that function will work. .UNINDENT .UNINDENT .sp There is also support for Apache\-style \fBhtpasswd\fP and \fBhtdigest\fP files: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C external_auth: file: ^filename: /var/www/html/.htusers ^filetype: htpasswd cory: \- .* .ft P .fi .UNINDENT .UNINDENT .sp When using \fBhtdigest\fP the \fB^realm\fP must be set: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C external_auth: file: ^filename: /var/www/html/.htdigest ^filetype: htdigest ^realm: MySecureRealm cory: \- .* .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.auth.file.auth(username, password) File based authentication .INDENT 7.0 .TP .B ^filename The path to the file to use for authentication. .TP .B ^filetype The type of file: \fBtext\fP, \fBhtpasswd\fP, \fBhtdigest\fP\&. .sp Default: \fBtext\fP .TP .B ^realm The realm required by htdigest authentication. .UNINDENT .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 The following parameters are only used with the \fBtext\fP filetype. .UNINDENT .UNINDENT .INDENT 7.0 .TP .B ^hashtype The digest format of the password. Can be \fBplaintext\fP or any digest available via \fBhashutil.digest\fP\&. .sp Default: \fBplaintext\fP .TP .B ^field_separator The character to use as a delimiter between fields in a text file. .sp Default: \fB:\fP .TP .B ^username_field The numbered field in the text file that contains the username, with numbering beginning at 1 (one). .sp Default: \fB1\fP .TP .B ^password_field The numbered field in the text file that contains the password, with numbering beginning at 1 (one). .sp Default: \fB2\fP .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.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 .INDENT 0.0 .TP .B salt.auth.ldap.process_acl(auth_list, opts=None) Query LDAP, retrieve list of minion_ids from an OU or other search. For each minion_id returned from the LDAP search, copy the perms matchers into the auth dictionary :param auth_list: :param opts: __opts__ for when __opts__ is not injected :return: Modified auth list. .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 Solaris\-like (SmartOS, OmniOS, ...) systems may need \fBauth.pam.service\fP set to \fBother\fP\&. .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 .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 Using PAM groups with SSSD groups on python2. .sp To use sssd with the PAM eauth module and groups the \fIpysss\fP module is needed. On RedHat/CentOS this is \fIpython\-sss\fP\&. .sp This should not be needed with python >= 3.3, because the \fIos\fP modules has the \fIgetgrouplist\fP function. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B class salt.auth.pam.PamConv Wrapper class for pam_conv structure .INDENT 7.0 .TP .B appdata_ptr Structure/Union member .UNINDENT .INDENT 7.0 .TP .B conv Structure/Union member .UNINDENT .UNINDENT .INDENT 0.0 .TP .B class salt.auth.pam.PamHandle Wrapper class for pam_handle_t .INDENT 7.0 .TP .B handle Structure/Union member .UNINDENT .UNINDENT .INDENT 0.0 .TP .B class salt.auth.pam.PamMessage Wrapper class for pam_message structure .INDENT 7.0 .TP .B msg Structure/Union member .UNINDENT .INDENT 7.0 .TP .B msg_style Structure/Union member .UNINDENT .UNINDENT .INDENT 0.0 .TP .B class salt.auth.pam.PamResponse Wrapper class for pam_response structure .INDENT 7.0 .TP .B resp Structure/Union member .UNINDENT .INDENT 7.0 .TP .B resp_retcode Structure/Union member .UNINDENT .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 .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 .INDENT 0.0 .TP .B salt.auth.rest.rest_auth_setup() .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, password) Shared secret authentication .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 .INDENT 0.0 .TP .B salt.auth.yubico.groups(username, *args, **kwargs) .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{ \fBaix_account\fP T} T{ Beacon to fire event when we notice a AIX user is locked due to many failed login attempts. 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{ \fBcert_info\fP T} T{ Beacon to monitor certificate expiration dates from files on the filesystem. 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{ \fBlog_beacon\fP T} T{ Beacon to fire events at specific log messages. T} _ T{ \fBmemusage\fP T} T{ Beacon to monitor memory usage. T} _ T{ \fBnapalm_beacon\fP T} T{ Watch NAPALM functions and fire events on specific triggers 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 process status T} _ T{ \fBsalt_proxy\fP T} T{ Beacon to manage and report the status of one or more salt proxy processes T} _ T{ \fBsensehat\fP T} T{ Monitor temperature, humidity and pressure using the SenseHat of a Raspberry Pi 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{ \fBsmartos_imgadm\fP T} T{ Beacon that fires events on image import/delete. T} _ T{ \fBsmartos_vmadm\fP T} T{ Beacon that fires events on vm state changes 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{ \fBtelegram_bot_msg\fP T} T{ Beacon to emit Telegram messages T} _ T{ \fBtwilio_txt_msg\fP T} T{ Beacon to emit Twilio text messages T} _ T{ \fBwatchdog\fP T} T{ watchdog beacon 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 .INDENT 0.0 .TP .B salt.beacons.adb.validate(config) Validate the beacon configuration .UNINDENT .SS salt.beacons.aix_account module .sp Beacon to fire event when we notice a AIX user is locked due to many failed login attempts. .sp New in version 2018.3.0. .INDENT 0.0 .TP .B depends none .UNINDENT .INDENT 0.0 .TP .B salt.beacons.aix_account.beacon(config) Checks for locked accounts due to too many invalid login attempts, 3 or higher. .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C beacons: aix_account: user: ALL interval: 120 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.beacons.aix_account.validate(config) Validate the beacon configuration .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 advised to set run_once: True (do not poll) on the beacon configuration. .sp The following are required configuration settings: .INDENT 7.0 .IP \(bu 2 \fBservicetype\fP \- The service type to announce .IP \(bu 2 \fBport\fP \- The port of the service to announce .IP \(bu 2 \fBtxt\fP \- The TXT record of the service being announced as a dict. Grains can be used to define TXT values using one of following two formats: .INDENT 2.0 .IP \(bu 2 \fBgrains.\fP .IP \(bu 2 \fBgrains.[i]\fP 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 .sp The following are optional configuration settings: .INDENT 7.0 .IP \(bu 2 \fBservicename\fP \- Set the name of the service. Will use the hostname from the minion\(aqs \fBhost\fP grain if this value is not set. .IP \(bu 2 \fBreset_on_change\fP \- If \fBTrue\fP 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 TXT records. Defaults to \fBFalse\fP\&. .IP \(bu 2 \fBreset_wait\fP \- 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 \fBreset_on_change\fP is \fBTrue\fP\&. Defaults to \fB0\fP\&. .IP \(bu 2 \fBcopy_grains\fP \- If \fBTrue\fP, Salt 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 \fBFalse\fP\&. .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 .INDENT 0.0 .TP .B salt.beacons.avahi_announce.validate(config) Validate the beacon configuration .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 advised to set run_once: True (do not poll) on the beacon configuration. .sp The following are required configuration settings: .INDENT 7.0 .IP \(bu 2 \fBservicetype\fP \- The service type to announce .IP \(bu 2 \fBport\fP \- The port of the service to announce .IP \(bu 2 \fBtxt\fP \- The TXT record of the service being announced as a dict. Grains can be used to define TXT values using one of following two formats: .INDENT 2.0 .IP \(bu 2 \fBgrains.\fP .IP \(bu 2 \fBgrains.[i]\fP 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 .sp The following are optional configuration settings: .INDENT 7.0 .IP \(bu 2 \fBservicename\fP \- Set the name of the service. Will use the hostname from the minion\(aqs \fBhost\fP grain if this value is not set. .IP \(bu 2 \fBreset_on_change\fP \- If \fBTrue\fP 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 TXT records. Defaults to \fBFalse\fP\&. .IP \(bu 2 \fBreset_wait\fP \- 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 \fBreset_on_change\fP is \fBTrue\fP\&. Defaults to \fB0\fP\&. .IP \(bu 2 \fBcopy_grains\fP \- If \fBTrue\fP, Salt 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 \fBFalse\fP\&. .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 .INDENT 0.0 .TP .B salt.beacons.bonjour_announce.validate(config) Validate the beacon configuration .UNINDENT .SS salt.beacons.btmp .sp Beacon to fire events at failed login of users .sp New in version 2015.5.0. .SS Example Configuration .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C # Fire events on all failed logins beacons: btmp: [] # Matching on user name, using a default time range beacons: btmp: \- users: gareth: \- defaults: time_range: start: \(aq8am\(aq end: \(aq4pm\(aq # Matching on user name, overriding the default time range beacons: btmp: \- users: gareth: time_range: start: \(aq8am\(aq end: \(aq4pm\(aq \- defaults: time_range: start: \(aq8am\(aq end: \(aq4pm\(aq # Matching on group name, overriding the default time range beacons: btmp: \- groups: users: time_range: start: \(aq8am\(aq end: \(aq4pm\(aq \- defaults: time_range: start: \(aq8am\(aq end: \(aq4pm\(aq .ft P .fi .UNINDENT .UNINDENT .SS Use Case: Posting Failed Login Events to Slack .sp This can be done using the following reactor SLS: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C report\-wtmp: runner.salt.cmd: \- args: \- fun: slack.post_message \- channel: mychannel # Slack channel \- from_name: someuser # Slack user \- message: "Failed login from \(ga{{ data.get(\(aquser\(aq, \(aq\(aq) or \(aqunknown user\(aq }}\(ga on \(ga{{ data[\(aqid\(aq] }}\(ga" .ft P .fi .UNINDENT .UNINDENT .sp Match the event like so in the master config file: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C reactor: \- \(aqsalt/beacon/*/btmp/\(aq: \- salt://reactor/btmp.sls .ft P .fi .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 This approach uses the \fBslack execution module\fP directly on the master, and therefore requires that the master has a slack API key in its configuration: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C slack: api_key: xoxb\-XXXXXXXXXXXX\-XXXXXXXXXXXX\-XXXXXXXXXXXXXXXXXXXXXXXX .ft P .fi .UNINDENT .UNINDENT .sp See the \fBslack execution module\fP documentation for more information. While you can use an individual user\(aqs API key to post to Slack, a bot user is likely better suited for this. The \fBslack engine\fP documentation has information on how to set up a bot user. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.beacons.btmp.beacon(config) Read the last btmp file and return information on the failed logins .UNINDENT .INDENT 0.0 .TP .B salt.beacons.btmp.validate(config) Validate the beacon configuration .UNINDENT .SS salt.beacons.cert_info .sp Beacon to monitor certificate expiration dates from files on the filesystem. .sp New in version 3000. .INDENT 0.0 .TP .B maintainer <\fI\%devops@eitr.tech\fP> .TP .B maturity new .TP .B depends OpenSSL .UNINDENT .INDENT 0.0 .TP .B salt.beacons.cert_info.beacon(config) Monitor the certificate files on the minion. .sp Specify a notification threshold in days and only emit a beacon if any certificates are expiring within that timeframe or if \fInotify_days\fP equals \fI\-1\fP (always report information). The default notification threshold is 45 days and can be overridden at the beacon level and at an individual certificate level. .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C beacons: cert_info: \- files: \- /etc/pki/tls/certs/mycert.pem \- /etc/pki/tls/certs/yourcert.pem: notify_days: 15 \- /etc/pki/tls/certs/ourcert.pem \- notify_days: 45 \- interval: 86400 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.beacons.cert_info.validate(config) Validate the beacon configuration .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:\e\e\(aq: 90% \- \(aqd:\e\e\(aq: 50% .ft P .fi .UNINDENT .UNINDENT .sp Regular expressions can be used as mount points. .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C beacons: diskusage: \- \(aq^\e/(?!home).*$\(aq: 90% \- \(aq^[a\-zA\-Z]:\e\e$\(aq: 50% .ft P .fi .UNINDENT .UNINDENT .sp The first one will match all mounted disks beginning with "/", except /home The second one will match disks from A:to Z:on a Windows system .sp Note that if a regular expression are evaluated after static mount points, which means that if a regular expression matches another defined mount point, it will override the previously defined threshold. .UNINDENT .INDENT 0.0 .TP .B salt.beacons.diskusage.validate(config) Validate the beacon configuration .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 .INDENT 0.0 .TP .B salt.beacons.glxinfo.validate(config) Validate the beacon configuration .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: \- backends: www\-backend: threshold: 45 servers: \- web1 \- web2 \- interval: 120 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.beacons.haproxy.validate(config) Validate the beacon configuration .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. .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: \- files: /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 \- coalesce: 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 .TP .B coalesce: If this coalescing option is enabled, events are filtered based on their unicity, only unique events are enqueued, doublons are discarded. An event is unique when the combination of its fields (wd, mask, cookie, name) is unique among events of a same batch. After a batch of events is processed any events are accepted again. This option is top\-level (at the same level as the path) and therefore affects all paths that are being watched. This is due to this option being at the Notifier level in pyinotify. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.beacons.inotify.close(config) .UNINDENT .INDENT 0.0 .TP .B salt.beacons.inotify.validate(config) Validate the beacon configuration .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: \- services: sshd: SYSLOG_IDENTIFIER: sshd PRIORITY: 6 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.beacons.journald.validate(config) Validate the beacon configuration .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: \- averages: 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 .INDENT 0.0 .TP .B salt.beacons.load.validate(config) Validate the beacon configuration .UNINDENT .SS salt.beacons.log module .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 .INDENT 0.0 .TP .B salt.beacons.memusage.validate(config) Validate the beacon configuration .UNINDENT .SS salt.beacons.napalm_beacon .SS Watch NAPALM functions and fire events on specific triggers .sp New in version 2018.3.0. .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 The \fBNAPALM\fP beacon only works only when running under a regular Minion or a Proxy Minion, managed via \fI\%NAPALM\fP\&. Check the documentation for the \fBNAPALM proxy module\fP\&. .UNINDENT .UNINDENT .sp The configuration accepts a list of Salt functions to be invoked, and the corresponding output hierarchy that should be matched against. To invoke a function with certain arguments, they can be specified using the \fB_args\fP key, or \fB_kwargs\fP for more specific key\-value arguments. .sp The match structure follows the output hierarchy of the NAPALM functions, under the \fBout\fP key. .sp For example, the following is normal structure returned by the \fBntp.stats\fP execution function: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C { "comment": "", "result": true, "out": [ { "referenceid": ".GPSs.", "remote": "172.17.17.1", "synchronized": true, "reachability": 377, "offset": 0.461, "when": "860", "delay": 143.606, "hostpoll": 1024, "stratum": 1, "jitter": 0.027, "type": "\-" }, { "referenceid": ".INIT.", "remote": "172.17.17.2", "synchronized": false, "reachability": 0, "offset": 0.0, "when": "\-", "delay": 0.0, "hostpoll": 1024, "stratum": 16, "jitter": 4000.0, "type": "\-" } ] } .ft P .fi .UNINDENT .UNINDENT .sp In order to fire events when the synchronization is lost with one of the NTP peers, e.g., \fB172.17.17.2\fP, we can match it explicitly as: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C ntp.stats: remote: 172.17.17.2 synchronized: false .ft P .fi .UNINDENT .UNINDENT .sp There is one single nesting level, as the output of \fBntp.stats\fP is just a list of dictionaries, and this beacon will compare each dictionary from the list with the structure examplified above. .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 When we want to match on any element at a certain level, we can configure \fB*\fP to match anything. .UNINDENT .UNINDENT .sp Considering a more complex structure consisting on multiple nested levels, e.g., the output of the \fBbgp.neighbors\fP execution function, to check when any neighbor from the \fBglobal\fP routing table is down, the match structure would have the format: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C bgp.neighbors: global: \(aq*\(aq: up: false .ft P .fi .UNINDENT .UNINDENT .sp The match structure above will match any BGP neighbor, with any network (\fB*\fP matches any AS number), under the \fBglobal\fP VRF. In other words, this beacon will push an event on the Salt bus when there\(aqs a BGP neighbor down. .sp The right operand can also accept mathematical operations (i.e., \fB<\fP, \fB<=\fP, \fB!=\fP, \fB>\fP, \fB>=\fP etc.) when comparing numerical values. .sp Configuration Example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C beacons: napalm: \- net.interfaces: # fire events when any interfaces is down \(aq*\(aq: is_up: false \- net.interfaces: # fire events only when the xe\-0/0/0 interface is down \(aqxe\-0/0/0\(aq: is_up: false \- ntp.stats: # fire when there\(aqs any NTP peer unsynchornized synchronized: false \- ntp.stats: # fire only when the synchronization # with with the 172.17.17.2 NTP server is lost _args: \- 172.17.17.2 synchronized: false \- ntp.stats: # fire only when there\(aqs a NTP peer with # synchronization stratum > 5 stratum: \(aq> 5\(aq .ft P .fi .UNINDENT .UNINDENT .sp Event structure example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C { "_stamp": "2017\-09\-05T09:51:09.377202", "args": [], "data": { "comment": "", "out": [ { "delay": 0.0, "hostpoll": 1024, "jitter": 4000.0, "offset": 0.0, "reachability": 0, "referenceid": ".INIT.", "remote": "172.17.17.1", "stratum": 16, "synchronized": false, "type": "\-", "when": "\-" } ], "result": true }, "fun": "ntp.stats", "id": "edge01.bjm01", "kwargs": {}, "match": { "stratum": "> 5" } } .ft P .fi .UNINDENT .UNINDENT .sp The event examplified above has been fired when the device identified by the Minion id \fBedge01.bjm01\fP has been synchronized with a NTP server at a stratum level greater than 5. .INDENT 0.0 .TP .B salt.beacons.napalm_beacon.beacon(config) Watch napalm function and fire events. .UNINDENT .INDENT 0.0 .TP .B salt.beacons.napalm_beacon.validate(config) Validate the beacon configuration. .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: \- interfaces: 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: \- interfaces: 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 .INDENT 0.0 .TP .B salt.beacons.network_info.validate(config) Validate the beacon configuration .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: \- interfaces: 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 \- interfaces: eth0: ipaddr: promiscuity: .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.beacons.network_settings.validate(config) Validate the beacon configuration .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 .INDENT 0.0 .TP .B salt.beacons.pkg.validate(config) Validate the beacon configuration .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 .INDENT 0.0 .TP .B salt.beacons.proxy_example.validate(config) Validate the beacon configuration .UNINDENT .SS salt.beacons.ps module .sp Send events covering process 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: \- processes: 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 .INDENT 0.0 .TP .B salt.beacons.ps.validate(config) Validate the beacon configuration .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(config) Handle configured proxies .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C beacons: salt_proxy: \- proxies: p8000: {} p8001: {} .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.beacons.salt_proxy.validate(config) Validate the beacon configuration .UNINDENT .SS salt.beacons.sensehat module .SS Monitor temperature, humidity and pressure using the SenseHat of a Raspberry Pi .sp New in version 2017.7.0. .INDENT 0.0 .TP .B maintainer Benedikt Werner <\fI\%1benediktwerner@gmail.com\fP> .TP .B maturity new .TP .B depends sense_hat Python module .UNINDENT .INDENT 0.0 .TP .B salt.beacons.sensehat.beacon(config) Monitor the temperature, humidity and pressure using the SenseHat sensors. .sp You can either specify a threshold for each value and only emit a beacon if it is exceeded or define a range and emit a beacon when the value is out of range. .sp Units: * humidity: percent * temperature: degrees Celsius * temperature_from_pressure: degrees Celsius * pressure: Millibars .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C beacons: sensehat: \- sensors: humidity: 70% temperature: [20, 40] temperature_from_pressure: 40 pressure: 1500 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.beacons.sensehat.validate(config) Validate the beacon configuration .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: \- services: 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 \fIdelay\fP: when \fIdelay\fP is greater than 0 the beacon will fire events only after the service status changes, and the delay (in seconds) has passed. Applicable only when \fIonchangeonly\fP is True. The default is 0. .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 30 seconds after 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: \- services: nginx: onchangeonly: True delay: 30 uncleanshutdown: /run/nginx.pid .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.beacons.service.validate(config) Validate the beacon configuration .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 .INDENT 0.0 .TP .B salt.beacons.sh.validate(config) Validate the beacon configuration .UNINDENT .SS salt.beacons.smartos_imgadm module .sp Beacon that fires events on image import/delete. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C ## minimal # \- check for new images every 1 second (salt default) # \- does not send events at startup beacons: imgadm: [] ## standard # \- check for new images every 60 seconds # \- send import events at startup for all images beacons: imgadm: \- interval: 60 \- startup_import_event: True .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.beacons.smartos_imgadm.beacon(config) Poll imgadm and compare available images .UNINDENT .INDENT 0.0 .TP .B salt.beacons.smartos_imgadm.validate(config) Validate the beacon configuration .UNINDENT .SS salt.beacons.smartos_vmadm module .sp Beacon that fires events on vm state changes .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C ## minimal # \- check for vm changes every 1 second (salt default) # \- does not send events at startup beacons: vmadm: [] ## standard # \- check for vm changes every 60 seconds # \- send create event at startup for all vms beacons: vmadm: \- interval: 60 \- startup_create_event: True .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.beacons.smartos_vmadm.beacon(config) Poll vmadm for changes .UNINDENT .INDENT 0.0 .TP .B salt.beacons.smartos_vmadm.validate(config) Validate the beacon configuration .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 .sp \fBWARNING:\fP .INDENT 0.0 .INDENT 3.5 Not all status functions are supported for every operating system. Be certain to check the minion log for errors after configuring this beacon. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.beacons.status.beacon(config) Return status for requested information .UNINDENT .INDENT 0.0 .TP .B salt.beacons.status.validate(config) Validate the config is a dict .UNINDENT .SS salt.beacons.telegram_bot_msg .sp Beacon to emit Telegram messages .sp Requires the python\-telegram\-bot library .INDENT 0.0 .TP .B salt.beacons.telegram_bot_msg.beacon(config) Emit a dict with a key "msgs" whose value is a list of messages sent to the configured bot by one of the allowed usernames. .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C beacons: telegram_bot_msg: \- token: "" \- accept_from: \- "" \- interval: 10 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.beacons.telegram_bot_msg.validate(config) Validate the beacon configuration .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 .INDENT 0.0 .TP .B salt.beacons.twilio_txt_msg.validate(config) Validate the beacon configuration .UNINDENT .SS salt.beacons.watchdog module .sp watchdog beacon .sp New in version 2019.2.0. .sp Watch files and translate the changes into salt events .INDENT 0.0 .TP .B depends .INDENT 7.0 .IP \(bu 2 watchdog Python module >= 0.8.3 .UNINDENT .UNINDENT .INDENT 0.0 .TP .B class salt.beacons.watchdog.FileSystemEventHandler A dummy class to make the import work .UNINDENT .INDENT 0.0 .TP .B class salt.beacons.watchdog.Handler(queue, masks=None) .INDENT 7.0 .TP .B on_created(event) .UNINDENT .INDENT 7.0 .TP .B on_deleted(event) .UNINDENT .INDENT 7.0 .TP .B on_modified(event) .UNINDENT .INDENT 7.0 .TP .B on_moved(event) .UNINDENT .UNINDENT .INDENT 0.0 .TP .B exception salt.beacons.watchdog.ValidationError .UNINDENT .INDENT 0.0 .TP .B salt.beacons.watchdog.beacon(config) Watch the configured directories .sp Example Config .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C beacons: watchdog: \- directories: /path/to/dir: mask: \- create \- modify \- delete \- move .ft P .fi .UNINDENT .UNINDENT .sp The mask list can contain the following events (the default mask is create, modify delete, and move): * create \- File or directory is created in watched directory * modify \- The watched directory is modified * delete \- File or directory is deleted from watched directory * move \- File or directory is moved or renamed in the watched directory .UNINDENT .INDENT 0.0 .TP .B salt.beacons.watchdog.close(config) .UNINDENT .INDENT 0.0 .TP .B salt.beacons.watchdog.to_salt_event(event) .UNINDENT .INDENT 0.0 .TP .B salt.beacons.watchdog.validate(config) Validate the beacon configuration .UNINDENT .SS salt.beacons.wtmp .sp Beacon to fire events at login of users as registered in the wtmp file .sp New in version 2015.5.0. .SS Example Configuration .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C # Fire events on all logins beacons: wtmp: [] # Matching on user name, using a default time range beacons: wtmp: \- users: gareth: \- defaults: time_range: start: \(aq8am\(aq end: \(aq4pm\(aq # Matching on user name, overriding the default time range beacons: wtmp: \- users: gareth: time_range: start: \(aq7am\(aq end: \(aq3pm\(aq \- defaults: time_range: start: \(aq8am\(aq end: \(aq4pm\(aq # Matching on group name, overriding the default time range beacons: wtmp: \- groups: users: time_range: start: \(aq7am\(aq end: \(aq3pm\(aq \- defaults: time_range: start: \(aq8am\(aq end: \(aq4pm\(aq .ft P .fi .UNINDENT .UNINDENT .SS How to Tell What An Event Means .sp In the events that this beacon fires, a type of \fB7\fP denotes a login, while a type of \fB8\fP denotes a logout. These values correspond to the \fBut_type\fP value from a wtmp/utmp event (see the \fBwtmp\fP manpage for more information). In the extremely unlikely case that your platform uses different values, they can be overridden using a \fBut_type\fP key in the beacon configuration: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C beacons: wtmp: \- ut_type: login: 9 logout: 10 .ft P .fi .UNINDENT .UNINDENT .sp This beacon\(aqs events include an \fBaction\fP key which will be either \fBlogin\fP or \fBlogout\fP depending on the event type. .sp Changed in version 2019.2.0: \fBaction\fP key added to beacon event, and \fBut_type\fP config parameter added. .SS Use Case: Posting Login/Logout Events to Slack .sp This can be done using the following reactor SLS: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C report\-wtmp: runner.salt.cmd: \- args: \- fun: slack.post_message \- channel: mychannel # Slack channel \- from_name: someuser # Slack user \- message: "{{ data.get(\(aqaction\(aq, \(aqUnknown event\(aq) | capitalize }} from \(ga{{ data.get(\(aquser\(aq, \(aq\(aq) or \(aqunknown user\(aq }}\(ga on \(ga{{ data[\(aqid\(aq] }}\(ga" .ft P .fi .UNINDENT .UNINDENT .sp Match the event like so in the master config file: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C reactor: \- \(aqsalt/beacon/*/wtmp/\(aq: \- salt://reactor/wtmp.sls .ft P .fi .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 This approach uses the \fBslack execution module\fP directly on the master, and therefore requires that the master has a slack API key in its configuration: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C slack: api_key: xoxb\-XXXXXXXXXXXX\-XXXXXXXXXXXX\-XXXXXXXXXXXXXXXXXXXXXXXX .ft P .fi .UNINDENT .UNINDENT .sp See the \fBslack execution module\fP documentation for more information. While you can use an individual user\(aqs API key to post to Slack, a bot user is likely better suited for this. The \fBslack engine\fP documentation has information on how to set up a bot user. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.beacons.wtmp.beacon(config) Read the last wtmp file and return information on the logins .UNINDENT .INDENT 0.0 .TP .B salt.beacons.wtmp.validate(config) Validate the beacon configuration .UNINDENT .SS cache modules .TS center; |l|l|. _ T{ \fBconsul\fP T} T{ Minion data cache plugin for Consul key/value data store. T} _ T{ \fBetcd_cache\fP T} T{ Minion data cache plugin for Etcd key/value data store. T} _ T{ \fBlocalfs\fP T} T{ Cache data in filesystem. T} _ T{ \fBmysql_cache\fP T} T{ Minion data cache plugin for MySQL database. T} _ T{ \fBredis_cache\fP T} T{ Redis T} _ .TE .SS salt.cache.consul .sp Minion data cache plugin for Consul key/value data store. .sp New in version 2016.11.2. .INDENT 0.0 .TP .B depends python\-consul >= 0.2.0 .UNINDENT .sp It is up to the system administrator to set up and configure the Consul infrastructure. All is needed for this plugin is a working Consul agent with a read\-write access to the key\-value store. .sp The related documentation can be found in the \fI\%Consul documentation\fP\&. .sp To enable this cache plugin, the master will need the python client for Consul installed. This can be easily installed with pip: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C pip install python\-consul .ft P .fi .UNINDENT .UNINDENT .sp Optionally, depending on the Consul agent configuration, the following values could be set in the master config. These are the defaults: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C consul.host: 127.0.0.1 consul.port: 8500 consul.token: None consul.scheme: http consul.consistency: default consul.dc: dc1 consul.verify: True .ft P .fi .UNINDENT .UNINDENT .sp Related docs could be found in the \fI\%python\-consul documentation\fP\&. .sp To use the consul as a minion data cache backend, set the master \fBcache\fP config value to \fBconsul\fP: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C cache: consul .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cache.consul.contains(bank, key) Checks if the specified bank contains the specified key. .UNINDENT .INDENT 0.0 .TP .B salt.cache.consul.fetch(bank, key) Fetch a key value. .UNINDENT .INDENT 0.0 .TP .B salt.cache.consul.flush(bank, key=None) Remove the key from the cache bank with all the key content. .UNINDENT .INDENT 0.0 .TP .B salt.cache.consul.list_(bank) Return an iterable object containing all entries stored in the specified bank. .UNINDENT .INDENT 0.0 .TP .B salt.cache.consul.store(bank, key, data) Store a key value. .UNINDENT .SS salt.cache.etcd_cache .sp Minion data cache plugin for Etcd key/value data store. .sp New in version develop. .sp It is up to the system administrator to set up and configure the Etcd infrastructure. All is needed for this plugin is a working Etcd agent with a read\-write access to the key\-value store. .sp The related documentation can be found in the \fI\%Etcd documentation\fP\&. .sp To enable this cache plugin, the master will need the python client for Etcd installed. This can be easily installed with pip: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C pip install python\-etcd .ft P .fi .UNINDENT .UNINDENT .sp Optionally, depending on the Etcd agent configuration, the following values could be set in the master config. These are the defaults: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C etcd.host: 127.0.0.1 etcd.port: 2379 etcd.protocol: http etcd.allow_reconnect: True etcd.allow_redirect: False etcd.srv_domain: None etcd.read_timeout: 60 etcd.username: None etcd.password: None etcd.cert: None etcd.ca_cert: None .ft P .fi .UNINDENT .UNINDENT .sp Related docs could be found in the \fI\%python\-etcd documentation\fP\&. .sp To use the etcd as a minion data cache backend, set the master \fBcache\fP config value to \fBetcd\fP: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C cache: etcd .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cache.etcd_cache.contains(bank, key) Checks if the specified bank contains the specified key. .UNINDENT .INDENT 0.0 .TP .B salt.cache.etcd_cache.fetch(bank, key) Fetch a key value. .UNINDENT .INDENT 0.0 .TP .B salt.cache.etcd_cache.flush(bank, key=None) Remove the key from the cache bank with all the key content. .UNINDENT .INDENT 0.0 .TP .B salt.cache.etcd_cache.ls(bank) Return an iterable object containing all entries stored in the specified bank. .UNINDENT .INDENT 0.0 .TP .B salt.cache.etcd_cache.store(bank, key, data) Store a key value. .UNINDENT .SS salt.cache.localfs .sp Cache data in filesystem. .sp New in version 2016.11.0. .sp The \fBlocalfs\fP Minion cache module is the default cache module and does not require any configuration. .sp Expiration values can be set in the relevant config file (\fB/etc/salt/master\fP for the master, \fB/etc/salt/cloud\fP for Salt Cloud, etc). .INDENT 0.0 .TP .B salt.cache.localfs.contains(bank, key, cachedir) Checks if the specified bank contains the specified key. .UNINDENT .INDENT 0.0 .TP .B salt.cache.localfs.fetch(bank, key, cachedir) Fetch information from a file. .UNINDENT .INDENT 0.0 .TP .B salt.cache.localfs.flush(bank, key=None, cachedir=None) Remove the key from the cache bank with all the key content. .UNINDENT .INDENT 0.0 .TP .B salt.cache.localfs.get_storage_id(kwargs) .UNINDENT .INDENT 0.0 .TP .B salt.cache.localfs.init_kwargs(kwargs) .UNINDENT .INDENT 0.0 .TP .B salt.cache.localfs.list_(bank, cachedir) Return an iterable object containing all entries stored in the specified bank. .UNINDENT .INDENT 0.0 .TP .B salt.cache.localfs.store(bank, key, data, cachedir) Store information in a file. .UNINDENT .INDENT 0.0 .TP .B salt.cache.localfs.updated(bank, key, cachedir) Return the epoch of the mtime for this cache file .UNINDENT .SS salt.cache.mysql_cache .sp Minion data cache plugin for MySQL database. .sp New in version develop. .sp It is up to the system administrator to set up and configure the MySQL infrastructure. All is needed for this plugin is a working MySQL server. .sp The module requires the \fIsalt_cache\fP database to exists but creates its own table if needed. The keys are indexed using the \fIbank\fP and \fIetcd_key\fP columns. .sp To enable this cache plugin, the master will need the python client for MySQL installed. This can be easily installed with pip: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C pip install python\-mysql .ft P .fi .UNINDENT .UNINDENT .sp Optionally, depending on the MySQL agent configuration, the following values could be set in the master config. These are the defaults: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C mysql.host: 127.0.0.1 mysql.port: 2379 mysql.user: None mysql.password: None mysql.database: salt_cache mysql.table_name: cache .ft P .fi .UNINDENT .UNINDENT .sp Related docs could be found in the \fI\%python\-mysql documentation\fP\&. .sp To use the mysql as a minion data cache backend, set the master \fBcache\fP config value to \fBmysql\fP: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C cache: mysql .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cache.mysql_cache.contains(bank, key) Checks if the specified bank contains the specified key. .UNINDENT .INDENT 0.0 .TP .B salt.cache.mysql_cache.fetch(bank, key) Fetch a key value. .UNINDENT .INDENT 0.0 .TP .B salt.cache.mysql_cache.flush(bank, key=None) Remove the key from the cache bank with all the key content. .UNINDENT .INDENT 0.0 .TP .B salt.cache.mysql_cache.ls(bank) Return an iterable object containing all entries stored in the specified bank. .UNINDENT .INDENT 0.0 .TP .B salt.cache.mysql_cache.run_query(conn, query, retries=3) Get a cursor and run a query. Reconnect up to \fIretries\fP times if needed. Returns: cursor, affected rows counter Raises: SaltCacheError, AttributeError, OperationalError .UNINDENT .INDENT 0.0 .TP .B salt.cache.mysql_cache.store(bank, key, data) Store a key value. .UNINDENT .SS salt.cache.redis_cache .SS Redis .sp Redis plugin for the Salt caching subsystem. .sp New in version 2017.7.0. .sp As Redis provides a simple mechanism for very fast key\-value store, in order to privde the necessary features for the Salt caching subsystem, the following conventions are used: .INDENT 0.0 .IP \(bu 2 A Redis key consists of the bank name and the cache key separated by \fB/\fP, e.g.: \fB$KEY_minions/alpha/stuff\fP where \fBminions/alpha\fP is the bank name and \fBstuff\fP is the key name. .IP \(bu 2 As the caching subsystem is organised as a tree, we need to store the caching path and identify the bank and its offspring. At the same time, Redis is linear and we need to avoid doing \fBkeys \fP which is very inefficient as it goes through all the keys on the remote Redis server. Instead, each bank hierarchy has a Redis SET associated which stores the list of sub\-banks. By default, these keys begin with \fB$BANK_\fP\&. .IP \(bu 2 In addition, each key name is stored in a separate SET of all the keys within a bank. By default, these SETs begin with \fB$BANKEYS_\fP\&. .UNINDENT .sp For example, to store the key \fBmy\-key\fP under the bank \fBroot\-bank/sub\-bank/leaf\-bank\fP, the following hierarchy will be built: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C 127.0.0.1:6379> SMEMBERS $BANK_root\-bank 1) "sub\-bank" 127.0.0.1:6379> SMEMBERS $BANK_root\-bank/sub\-bank 1) "leaf\-bank" 127.0.0.1:6379> SMEMBERS $BANKEYS_root\-bank/sub\-bank/leaf\-bank 1) "my\-key" 127.0.0.1:6379> GET $KEY_root\-bank/sub\-bank/leaf\-bank/my\-key "my\-value" .ft P .fi .UNINDENT .UNINDENT .sp There are three types of keys stored: .INDENT 0.0 .IP \(bu 2 \fB$BANK_*\fP is a Redis SET containing the list of banks under the current bank .IP \(bu 2 \fB$BANKEYS_*\fP is a Redis SET containing the list of keys under the current bank .IP \(bu 2 \fB$KEY_*\fP keeps the value of the key .UNINDENT .sp These prefixes and the separator can be adjusted using the configuration options: .INDENT 0.0 .TP .B bank_prefix: \fB$BANK\fP The prefix used for the name of the Redis key storing the list of sub\-banks. .TP .B bank_keys_prefix: \fB$BANKEYS\fP The prefix used for the name of the Redis keyt storing the list of keys under a certain bank. .TP .B key_prefix: \fB$KEY\fP The prefix of the Redis keys having the value of the keys to be cached under a certain bank. .TP .B separator: \fB_\fP The separator between the prefix and the key body. .UNINDENT .sp The connection details can be specified using: .INDENT 0.0 .TP .B host: \fBlocalhost\fP The hostname of the Redis server. .TP .B port: \fB6379\fP The Redis server port. .TP .B cluster_mode: \fBFalse\fP Whether cluster_mode is enabled or not .TP .B cluster.startup_nodes: A list of host, port dictionaries pointing to cluster members. At least one is required but multiple nodes are better .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C cache.redis.cluster.startup_nodes \- host: redis\-member\-1 port: 6379 \- host: redis\-member\-2 port: 6379 .ft P .fi .UNINDENT .UNINDENT .TP .B cluster.skip_full_coverage_check: \fBFalse\fP Some cluster providers restrict certain redis commands such as CONFIG for enhanced security. Set this option to true to skip checks that required advanced privileges. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 Most cloud hosted redis clusters will require this to be set to \fBTrue\fP .UNINDENT .UNINDENT .TP .B db: \fB\(aq0\(aq\fP The database index. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 The database index must be specified as string not as integer value! .UNINDENT .UNINDENT .TP .B password: Redis connection password. .UNINDENT .sp unix_socket_path: .INDENT 0.0 .INDENT 3.5 New in version 2018.3.1. .sp Path to a UNIX socket for access. Overrides \fIhost\fP / \fIport\fP\&. .UNINDENT .UNINDENT .sp Configuration Example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C cache.redis.host: localhost cache.redis.port: 6379 cache.redis.db: \(aq0\(aq cache.redis.password: my pass cache.redis.bank_prefix: #BANK cache.redis.bank_keys_prefix: #BANKEYS cache.redis.key_prefix: #KEY cache.redis.separator: \(aq@\(aq .ft P .fi .UNINDENT .UNINDENT .sp Cluster Configuration Example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C cache.redis.cluster_mode: true cache.redis.cluster.skip_full_coverage_check: true cache.redis.cluster.startup_nodes: \- host: redis\-member\-1 port: 6379 \- host: redis\-member\-2 port: 6379 cache.redis.db: \(aq0\(aq cache.redis.password: my pass cache.redis.bank_prefix: #BANK cache.redis.bank_keys_prefix: #BANKEYS cache.redis.key_prefix: #KEY cache.redis.separator: \(aq@\(aq .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cache.redis_cache.contains(bank, key) Checks if the specified bank contains the specified key. .UNINDENT .INDENT 0.0 .TP .B salt.cache.redis_cache.fetch(bank, key) Fetch data from the Redis cache. .UNINDENT .INDENT 0.0 .TP .B salt.cache.redis_cache.flush(bank, key=None) Remove the key from the cache bank with all the key content. If no key is specified, remove the entire bank with all keys and sub\-banks inside. This function is using the Redis pipelining for best performance. However, when removing a whole bank, in order to re\-create the tree, there are a couple of requests made. In total: .INDENT 7.0 .IP \(bu 2 one for node in the hierarchy sub\-tree, starting from the bank node .IP \(bu 2 one pipelined request to get the keys under all banks in the sub\-tree .IP \(bu 2 one pipeline request to remove the corresponding keys .UNINDENT .sp This is not quite optimal, as if we need to flush a bank having a very long list of sub\-banks, the number of requests to build the sub\-tree may grow quite big. .sp An improvement for this would be loading a custom Lua script in the Redis instance of the user (using the \fBregister_script\fP feature) and call it whenever we flush. This script would only need to build this sub\-tree causing problems. It can be added later and the behaviour should not change as the user needs to explicitly allow Salt inject scripts in their Redis instance. .UNINDENT .INDENT 0.0 .TP .B salt.cache.redis_cache.init_kwargs(kwargs) .UNINDENT .INDENT 0.0 .TP .B salt.cache.redis_cache.list_(bank) Lists entries stored in the specified bank. .UNINDENT .INDENT 0.0 .TP .B salt.cache.redis_cache.store(bank, key, data) Store the data in a Redis key. .UNINDENT .SS cloud modules .TS center; |l|l|. _ T{ \fBaliyun\fP T} T{ AliYun ECS Cloud Module T} _ T{ \fBazurearm\fP T} T{ Azure ARM Cloud Module T} _ T{ \fBclc\fP T} T{ CenturyLink Cloud Module T} _ T{ \fBcloudstack\fP T} T{ CloudStack Cloud Module T} _ T{ \fBdigitalocean\fP T} T{ DigitalOcean Cloud Module T} _ T{ \fBdimensiondata\fP T} T{ Dimension Data Cloud Module T} _ T{ \fBec2\fP T} T{ The EC2 Cloud Module T} _ T{ \fBgce\fP T} T{ Copyright 2013 Google Inc. T} _ T{ \fBgogrid\fP T} T{ GoGrid Cloud Module T} _ T{ \fBjoyent\fP T} T{ Joyent Cloud Module T} _ T{ \fBlibvirt\fP T} T{ Libvirt Cloud Module T} _ T{ \fBlinode\fP T} T{ The Linode Cloud Module T} _ T{ \fBlxc\fP T} T{ Install Salt on an LXC Container T} _ T{ \fBmsazure\fP T} T{ Azure Cloud Module T} _ T{ \fBoneandone\fP T} T{ 1&1 Cloud Server Module T} _ T{ \fBopennebula\fP T} T{ OpenNebula Cloud Module T} _ T{ \fBopenstack\fP T} T{ Openstack Cloud Driver T} _ T{ \fBpacket\fP T} T{ Packet Cloud Module Using Packet\(aqs Python API Client T} _ T{ \fBparallels\fP T} T{ Parallels Cloud Module T} _ T{ \fBprofitbricks\fP T} T{ ProfitBricks Cloud Module T} _ T{ \fBproxmox\fP T} T{ Proxmox Cloud Module T} _ T{ \fBpyrax\fP T} T{ Pyrax Cloud Module T} _ T{ \fBqingcloud\fP T} T{ QingCloud Cloud Module T} _ T{ \fBsaltify\fP T} T{ T} _ T{ \fBscaleway\fP T} T{ Scaleway Cloud Module T} _ T{ \fBsoftlayer\fP T} T{ SoftLayer Cloud Module T} _ T{ \fBsoftlayer_hw\fP T} T{ SoftLayer HW Cloud Module T} _ T{ \fBtencentcloud\fP T} T{ Tencent Cloud Cloud Module T} _ T{ \fBvagrant\fP T} T{ Vagrant Cloud Driver T} _ T{ \fBvirtualbox\fP T} T{ A salt cloud provider that lets you use virtualbox on your machine and act as a cloud. T} _ T{ \fBvmware\fP T} T{ VMware Cloud Module T} _ T{ \fBvultrpy\fP T} T{ Vultr Cloud Module using python\-vultr bindings T} _ T{ \fBxen\fP T} T{ XenServer Cloud Driver T} _ .TE .SS salt.cloud.clouds.aliyun .SS AliYun ECS Cloud Module .sp New in version 2014.7.0. .sp The Aliyun cloud module is used to control access to the aliyun ECS. \fI\%http://www.aliyun.com/\fP .sp Use of this module requires the \fBid\fP and \fBkey\fP parameter to be set. Set up the cloud configuration at \fB/etc/salt/cloud.providers\fP or \fB/etc/salt/cloud.providers.d/aliyun.conf\fP: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C my\-aliyun\-config: # aliyun Access Key ID id: wFGEwgregeqw3435gDger # aliyun Access Key Secret key: GDE43t43REGTrkilg43934t34qT43t4dgegerGEgg location: cn\-qingdao driver: aliyun .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .TP .B depends requests .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.aliyun.avail_images(kwargs=None, call=None) Return a list of the images that are on the provider .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.aliyun.avail_locations(call=None) Return a dict of all available VM locations on the cloud provider with relevant data .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.aliyun.avail_sizes(call=None) Return a list of the image sizes that are on the provider .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.aliyun.create(vm_) Create a single VM from a data dict .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.aliyun.create_node(kwargs) Convenience function to make the rest api call for node creation. .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.aliyun.destroy(name, call=None) Destroy a node. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-a destroy myinstance salt\-cloud \-d myinstance .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.aliyun.get_configured_provider() Return the first configured instance. .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.aliyun.get_dependencies() Warn if dependencies aren\(aqt met. .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.aliyun.get_image(vm_) Return the image object to use .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.aliyun.get_location(vm_=None) .INDENT 7.0 .TP .B Return the aliyun region to use, in this order: .INDENT 7.0 .IP \(bu 2 CLI parameter .IP \(bu 2 VM parameter .IP \(bu 2 Cloud profile setting .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.aliyun.get_securitygroup(vm_) Return the security group .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.aliyun.get_size(vm_) Return the VM\(aqs size. Used by create_node(). .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.aliyun.list_availability_zones(call=None) List all availability zones in the current region .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.aliyun.list_monitor_data(kwargs=None, call=None) Get monitor data of the instance. If instance name is missing, will show all the instance monitor data on the region. .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-f list_monitor_data aliyun salt\-cloud \-f list_monitor_data aliyun name=AY14051311071990225bd .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.aliyun.list_nodes(call=None) Return a list of the VMs that are on the provider .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.aliyun.list_nodes_full(call=None) Return a list of the VMs that are on the provider .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.aliyun.list_nodes_min(call=None) Return a list of the VMs that are on the provider. Only a list of VM names, and their state, is returned. This is the minimum amount of information needed to check for existing VMs. .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.aliyun.list_nodes_select(call=None) Return a list of the VMs that are on the provider, with select fields .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.aliyun.list_securitygroup(call=None) Return a list of security group .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.aliyun.query(params=None) Make a web call to aliyun ECS REST API .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.aliyun.reboot(name, call=None) Reboot a node .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-a reboot myinstance .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.aliyun.script(vm_) Return the script deployment object .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.aliyun.show_disk(name, call=None) Show the disk details of the instance .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-a show_disk aliyun myinstance .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.aliyun.show_image(kwargs, call=None) Show the details from aliyun image .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.aliyun.show_instance(name, call=None) Show the details from aliyun instance .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.aliyun.start(name, call=None) Start a node .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-a start myinstance .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.aliyun.stop(name, force=False, call=None) Stop a node .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-a stop myinstance salt\-cloud \-a stop myinstance force=True .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.cloud.clouds.azurearm .SS Azure ARM Cloud Module .sp New in version 2016.11.0. .sp Changed in version 2019.2.0. .sp The Azure ARM cloud module is used to control access to Microsoft Azure Resource Manager .INDENT 0.0 .TP .B depends .INDENT 7.0 .IP \(bu 2 \fI\%azure\fP >= 2.0.0rc6 .IP \(bu 2 \fI\%azure\-common\fP >= 1.1.4 .IP \(bu 2 \fI\%azure\-mgmt\fP >= 0.30.0rc6 .IP \(bu 2 \fI\%azure\-mgmt\-compute\fP >= 0.33.0 .IP \(bu 2 \fI\%azure\-mgmt\-network\fP >= 0.30.0rc6 .IP \(bu 2 \fI\%azure\-mgmt\-resource\fP >= 0.30.0 .IP \(bu 2 \fI\%azure\-mgmt\-storage\fP >= 0.30.0rc6 .IP \(bu 2 \fI\%azure\-mgmt\-web\fP >= 0.30.0rc6 .IP \(bu 2 \fI\%azure\-storage\fP >= 0.32.0 .IP \(bu 2 \fI\%msrestazure\fP >= 0.4.21 .UNINDENT .TP .B configuration Required provider parameters: .INDENT 7.0 .TP .B if using username and password: .INDENT 7.0 .IP \(bu 2 \fBsubscription_id\fP .IP \(bu 2 \fBusername\fP .IP \(bu 2 \fBpassword\fP .UNINDENT .TP .B if using a service principal: .INDENT 7.0 .IP \(bu 2 \fBsubscription_id\fP .IP \(bu 2 \fBtenant\fP .IP \(bu 2 \fBclient_id\fP .IP \(bu 2 \fBsecret\fP .UNINDENT .TP .B if using Managed Service Identity authentication: .INDENT 7.0 .IP \(bu 2 \fBsubscription_id\fP .UNINDENT .UNINDENT .sp Optional provider parameters: .INDENT 7.0 .TP \fBcloud_environment\fP: Used to point the cloud driver to different API endpoints, such as Azure GovCloud. Possible values: .INDENT 7.0 .IP \(bu 2 \fBAZURE_PUBLIC_CLOUD\fP (default) .IP \(bu 2 \fBAZURE_CHINA_CLOUD\fP .IP \(bu 2 \fBAZURE_US_GOV_CLOUD\fP .IP \(bu 2 \fBAZURE_GERMAN_CLOUD\fP .IP \(bu 2 HTTP base URL for a custom endpoint, such as Azure Stack. The \fB/metadata/endpoints\fP path will be added to the URL. .UNINDENT .TP \fBuserdata\fP and \fBuserdata_file\fP: Azure Resource Manager uses a separate VirtualMachineExtension object to pass userdata scripts to the virtual machine. Arbitrary shell commands can be passed via the \fBuserdata\fP parameter, or via a file local to the Salt Cloud system using the \fBuserdata_file\fP parameter. Note that the local file is not treated as a script by the extension, so "one\-liners" probably work best. If greater functionality is desired, a web\-hosted script file can be specified via \fBuserdata_file: https://raw.githubusercontent.com/account/repo/master/azure\-script.py\fP, which will be executed on the system after VM creation. For Windows systems, script files ending in \fB\&.ps1\fP will be executed with \fBpowershell.exe\fP\&. The \fBuserdata\fP parameter takes precedence over the \fBuserdata_file\fP parameter when creating the custom script extension. .TP \fBwin_installer\fP: This parameter, which holds the local path to the Salt Minion installer package, is used to determine if the virtual machine type will be "Windows". Only set this parameter on profiles which install Windows operating systems. .UNINDENT .UNINDENT .sp Example \fB/etc/salt/cloud.providers\fP or \fB/etc/salt/cloud.providers.d/azure.conf\fP configuration: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C my\-azure\-config with username and password: driver: azurearm subscription_id: 3287abc8\-f98a\-c678\-3bde\-326766fd3617 username: larry password: 123pass Or my\-azure\-config with service principal: driver: azurearm subscription_id: 3287abc8\-f98a\-c678\-3bde\-326766fd3617 tenant: ABCDEFAB\-1234\-ABCD\-1234\-ABCDEFABCDEF client_id: ABCDEFAB\-1234\-ABCD\-1234\-ABCDEFABCDEF secret: XXXXXXXXXXXXXXXXXXXXXXXX cloud_environment: AZURE_US_GOV_CLOUD The Service Principal can be created with the new Azure CLI (https://github.com/Azure/azure\-cli) with: az ad sp create\-for\-rbac \-n "http://" \-\-role \-\-scopes For example, this creates a service principal with \(aqowner\(aq role for the whole subscription: az ad sp create\-for\-rbac \-n "http://mysaltapp" \-\-role owner \-\-scopes /subscriptions/3287abc8\-f98a\-c678\-3bde\-326766fd3617 *Note: review the details of Service Principals. Owner role is more than you normally need, and you can restrict scope to a resource group or individual resources. .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.azurearm.avail_images(call=None) Return a dict of all available images on the provider .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.azurearm.avail_locations(call=None) Return a dict of all available regions. .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.azurearm.avail_sizes(call=None) Return a list of sizes available from the provider .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.azurearm.create(vm_) Create a single VM from a data dict. .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.azurearm.create_network_interface(call=None, kwargs=None) Create a network interface. .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.azurearm.create_or_update_vmextension(call=None, kwargs=None) New in version 2019.2.0. .sp Create or update a VM extension object "inside" of a VM object. .INDENT 7.0 .TP .B required kwargs: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C extension_name: myvmextension virtual_machine_name: myvm settings: {"commandToExecute": "hostname"} .ft P .fi .UNINDENT .UNINDENT .TP .B optional kwargs: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C resource_group: < inferred from cloud configs > location: < inferred from cloud configs > publisher: < default: Microsoft.Azure.Extensions > virtual_machine_extension_type: < default: CustomScript > type_handler_version: < default: 2.0 > auto_upgrade_minor_version: < default: True > protected_settings: < default: None > .ft P .fi .UNINDENT .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.azurearm.delete_blob(call=None, kwargs=None) Delete a blob from a container. .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.azurearm.delete_interface(call=None, kwargs=None) Delete a network interface. .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.azurearm.delete_managed_disk(call=None, kwargs=None) Delete a managed disk from a resource group. .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.azurearm.destroy(name, call=None, kwargs=None) Destroy a VM. .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-d myminion salt\-cloud \-a destroy myminion service_name=myservice .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.azurearm.get_api_versions(call=None, kwargs=None) Get a resource type api versions .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.azurearm.get_configured_provider() Return the first configured provider instance. .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.azurearm.get_conn(client_type) Return a connection object for a client type. .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.azurearm.get_dependencies() Warn if dependencies aren\(aqt met. .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.azurearm.get_location(call=None, kwargs=None) Return the location that is configured for this provider .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.azurearm.get_resource_by_id(resource_id, api_version, extract_value=None) Get an AzureARM resource by id .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.azurearm.list_blobs(call=None, kwargs=None) List blobs. .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.azurearm.list_nodes(call=None) List VMs on this Azure account .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.azurearm.list_nodes_full(call=None) List all VMs on the subscription with full information .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.azurearm.list_resource_groups(call=None) List resource groups associated with the subscription .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.azurearm.list_storage_accounts(call=None) List storage accounts within the subscription. .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.azurearm.list_subnets(call=None, kwargs=None) List subnets in a virtual network. .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.azurearm.list_virtual_networks(call=None, kwargs=None) List virtual networks. .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.azurearm.request_instance(vm_) Request a VM from Azure. .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.azurearm.show_instance(name, call=None) Show the details from AzureARM concerning an instance .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.azurearm.start(name, call=None) New in version 2019.2.0. .sp Start a VM .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-a start myminion .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.azurearm.stop(name, call=None) New in version 2019.2.0. .sp Stop (deallocate) a VM .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-a stop myminion .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.cloud.clouds.clc .SS CenturyLink Cloud Module .sp New in version Oyxgen. .sp The CLC cloud module allows you to manage CLC Via the CLC SDK. .INDENT 0.0 .TP .B codeauthor Stephan Looney <\fI\%slooney@stephanlooney.com\fP> .UNINDENT .SS Dependencies .INDENT 0.0 .IP \(bu 2 clc\-sdk Python Module .IP \(bu 2 flask .UNINDENT .SS CLC SDK .sp clc\-sdk can be installed via pip: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C pip install clc\-sdk .ft P .fi .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 For sdk reference see: \fI\%https://github.com/CenturyLinkCloud/clc\-python\-sdk\fP .UNINDENT .UNINDENT .SS Flask .sp flask can be installed via pip: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C pip install flask .ft P .fi .UNINDENT .UNINDENT .SS Configuration .sp To use this module: set up the clc\-sdk, user, password, key in the cloud configuration at \fB/etc/salt/cloud.providers\fP or \fB/etc/salt/cloud.providers.d/clc.conf\fP: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C my\-clc\-config: driver: clc user: \(aqweb\-user\(aq password: \(aqverybadpass\(aq token: \(aq\(aq token_pass:\(aq\(aq accountalias: \(aqACT\(aq .ft P .fi .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 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 .INDENT 0.0 .TP .B salt.cloud.clouds.clc.avail_images(call=None) returns a list of images available to you .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.clc.avail_locations(call=None) returns a list of locations available to you .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.clc.avail_sizes(call=None) use templates for this .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.clc.create(vm_) get the system build going .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.clc.destroy(name, call=None) destroy the vm .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.clc.get_build_status(req_id, nodename) get the build status from CLC to make sure we don\(aqt return to early .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.clc.get_configured_provider() .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.clc.get_creds() .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.clc.get_dependencies() Warn if dependencies aren\(aqt met. .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.clc.get_group_estimate(call=None, for_output=True, **kwargs) Return a list of the VMs that are on the provider usage: "salt\-cloud \-f get_group_estimate clc group=Dev location=VA1" .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.clc.get_month_to_date(call=None, for_output=True) Return a list of the VMs that are on the provider .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.clc.get_monthly_estimate(call=None, for_output=True) Return a list of the VMs that are on the provider .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.clc.get_queue_data(call=None, for_output=True) .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.clc.get_server_alerts(call=None, for_output=True, **kwargs) Return a list of alerts from CLC as reported by their infra .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.clc.list_nodes_full(call=None, for_output=True) Return a list of the VMs that are on the provider .UNINDENT .SS salt.cloud.clouds.cloudstack .SS CloudStack Cloud Module .sp The CloudStack cloud module is used to control access to a CloudStack based Public Cloud. .INDENT 0.0 .TP .B depends libcloud >= 0.15 .UNINDENT .sp Use of this module requires the \fBapikey\fP, \fBsecretkey\fP, \fBhost\fP and \fBpath\fP parameters. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C my\-cloudstack\-cloud\-config: apikey: secretkey: host: localhost path: /client/api driver: cloudstack .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.cloudstack.avail_images(conn=None, call=None) Return a dict of all available VM images on the cloud provider with relevant data .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.cloudstack.avail_locations(conn=None, call=None) Return a dict of all available VM locations on the cloud provider with relevant data .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.cloudstack.avail_sizes(conn=None, call=None) Return a dict of all available VM images on the cloud provider with relevant data .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.cloudstack.block_device_mappings(vm_) Return the block device mapping: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C [{\(aqDeviceName\(aq: \(aq/dev/sdb\(aq, \(aqVirtualName\(aq: \(aqephemeral0\(aq}, {\(aqDeviceName\(aq: \(aq/dev/sdc\(aq, \(aqVirtualName\(aq: \(aqephemeral1\(aq}] .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.cloudstack.cloudstack_displayname(vm_) Return display name of VM: .INDENT 7.0 .TP .B :: "minion1" .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.cloudstack.create(vm_) Create a single VM from a data dict .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.cloudstack.destroy(name, conn=None, call=None) Delete a single VM, and all of its volumes .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.cloudstack.get_configured_provider() Return the first configured instance. .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.cloudstack.get_conn() Return a conn object for the passed VM data .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.cloudstack.get_dependencies() Warn if dependencies aren\(aqt met. .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.cloudstack.get_image(conn, vm_) Return the image object to use .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.cloudstack.get_ip(data) Return the IP address of the VM If the VM has public IP as defined by libcloud module then use it Otherwise try to extract the private IP and use that one. .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.cloudstack.get_key() Returns the ssh private key for VM access .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.cloudstack.get_keypair(vm_) Return the keypair to use .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.cloudstack.get_location(conn, vm_) Return the node location to use .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.cloudstack.get_networkid(vm_) Return the networkid to use, only valid for Advanced Zone .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.cloudstack.get_node(conn, name) Return a libcloud node for the named VM .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.cloudstack.get_password(vm_) Return the password to use .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.cloudstack.get_project(conn, vm_) Return the project to use. .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.cloudstack.get_security_groups(conn, vm_) Return a list of security groups to use, defaulting to [\(aqdefault\(aq] .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.cloudstack.get_size(conn, vm_) Return the VM\(aqs size object .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.cloudstack.list_nodes(conn=None, call=None) Return a list of the VMs that are on the provider .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.cloudstack.list_nodes_full(conn=None, call=None) Return a list of the VMs that are on the provider, with all fields .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.cloudstack.list_nodes_select(conn=None, call=None) Return a list of the VMs that are on the provider, with select fields .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.cloudstack.script(vm_) Return the script deployment object .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.cloudstack.show_instance(name, call=None) Show the details from the provider concerning an instance .UNINDENT .SS salt.cloud.clouds.digitalocean .SS DigitalOcean Cloud Module .sp The DigitalOcean cloud module is used to control access to the DigitalOcean VPS system. .sp Use of this module requires a 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\-digital\-ocean\-config: personal_access_token: xxx ssh_key_file: /path/to/ssh/key/file ssh_key_names: my\-key\-name,my\-key\-name\-2 driver: digitalocean .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .TP .B depends requests .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.digitalocean.assign_floating_ip(kwargs=None, call=None) Assign a floating IP .sp New in version 2016.3.0. .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-f assign_floating_ip my\-digitalocean\-config droplet_id=1234567 floating_ip=\(aq45.55.96.47\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.digitalocean.avail_images(call=None) Return a list of the images that are on the provider .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.digitalocean.avail_locations(call=None) Return a dict of all available VM locations on the cloud provider with relevant data .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.digitalocean.avail_sizes(call=None) Return a list of the image sizes that are on the provider .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.digitalocean.create(vm_) Create a single VM from a data dict .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.digitalocean.create_floating_ip(kwargs=None, call=None) Create a new floating IP .sp New in version 2016.3.0. .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-f create_floating_ip my\-digitalocean\-config region=\(aqNYC2\(aq salt\-cloud \-f create_floating_ip my\-digitalocean\-config droplet_id=\(aq1234567\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.digitalocean.create_key(kwargs=None, call=None) Upload a public key .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.digitalocean.create_node(args) Create a node .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.digitalocean.delete_floating_ip(kwargs=None, call=None) Delete a floating IP .sp New in version 2016.3.0. .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-f delete_floating_ip my\-digitalocean\-config floating_ip=\(aq45.55.96.47\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.digitalocean.destroy(name, call=None) Destroy a node. Will check termination protection and warn if enabled. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-\-destroy mymachine .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.digitalocean.destroy_dns_records(fqdn) Deletes DNS records for the given hostname if the domain is managed with DO. .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.digitalocean.get_configured_provider() Return the first configured instance. .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.digitalocean.get_dependencies() Warn if dependencies aren\(aqt met. .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.digitalocean.get_image(vm_) Return the image object to use .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.digitalocean.get_keyid(keyname) Return the ID of the keyname .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.digitalocean.get_location(vm_) Return the VM\(aqs location .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.digitalocean.get_size(vm_) Return the VM\(aqs size. Used by create_node(). .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.digitalocean.import_keypair(kwargs=None, call=None) Upload public key to cloud provider. Similar to EC2 import_keypair. .sp New in version 2016.11.0. .INDENT 7.0 .TP .B kwargs file(mandatory): public key file\-name keyname(mandatory): public key name in the provider .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.digitalocean.list_floating_ips(call=None) Return a list of the floating ips that are on the provider .sp New in version 2016.3.0. .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-f list_floating_ips my\-digitalocean\-config .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.digitalocean.list_keypairs(call=None) Return a dict of all available VM locations on the cloud provider with relevant data .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.digitalocean.list_nodes(call=None) Return a list of the VMs that are on the provider .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.digitalocean.list_nodes_full(call=None, for_output=True) Return a list of the VMs that are on the provider .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.digitalocean.list_nodes_select(call=None) Return a list of the VMs that are on the provider, with select fields .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.digitalocean.post_dns_record(**kwargs) Creates a DNS record for the given name if the domain is managed with DO. .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.digitalocean.query(method=\(aqdroplets\(aq, droplet_id=None, command=None, args=None, http_method=\(aqget\(aq) Make a web call to DigitalOcean .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.digitalocean.reboot(name, call=None) Reboot a droplet in DigitalOcean. .sp New in version 2015.8.8. .INDENT 7.0 .TP .B name The name of the droplet to restart. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-a reboot droplet_name .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.digitalocean.remove_key(kwargs=None, call=None) Delete public key .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.digitalocean.script(vm_) Return the script deployment object .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.digitalocean.show_floating_ip(kwargs=None, call=None) Show the details of a floating IP .sp New in version 2016.3.0. .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-f show_floating_ip my\-digitalocean\-config floating_ip=\(aq45.55.96.47\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.digitalocean.show_instance(name, call=None) Show the details from DigitalOcean concerning a droplet .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.digitalocean.show_keypair(kwargs=None, call=None) Show the details of an SSH keypair .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.digitalocean.show_pricing(kwargs=None, call=None) Show pricing for a particular profile. This is only an estimate, based on unofficial pricing sources. .sp New in version 2015.8.0. .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-f show_pricing my\-digitalocean\-config profile=my\-profile .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.digitalocean.start(name, call=None) Start a droplet in DigitalOcean. .sp New in version 2015.8.8. .INDENT 7.0 .TP .B name The name of the droplet to start. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-a start droplet_name .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.digitalocean.stop(name, call=None) Stop a droplet in DigitalOcean. .sp New in version 2015.8.8. .INDENT 7.0 .TP .B name The name of the droplet to stop. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-a stop droplet_name .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.digitalocean.unassign_floating_ip(kwargs=None, call=None) Unassign a floating IP .sp New in version 2016.3.0. .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-f unassign_floating_ip my\-digitalocean\-config floating_ip=\(aq45.55.96.47\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.cloud.clouds.dimensiondata .SS Dimension Data Cloud Module .sp This is a cloud module for the Dimension Data Cloud, using the existing Libcloud driver for Dimension Data. .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 .INDENT 0.0 .TP .B maintainer Anthony Shaw <\fI\%anthonyshaw@apache.org\fP> .TP .B depends libcloud >= 1.2.1 .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.dimensiondata.avail_images(conn=None, call=None) Return a dict of all available VM images on the cloud provider with relevant data .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.dimensiondata.avail_locations(conn=None, call=None) Return a dict of all available VM locations on the cloud provider with relevant data .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.dimensiondata.avail_sizes(conn=None, call=None) Return a dict of all available VM images on the cloud provider with relevant data .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.dimensiondata.create(vm_) Create a single VM from a data dict .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.dimensiondata.create_lb(kwargs=None, call=None) Create a load\-balancer configuration. CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-f create_lb dimensiondata \e name=dev\-lb port=80 protocol=http \e members=w1,w2,w3 algorithm=ROUND_ROBIN .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.dimensiondata.destroy(name, conn=None, call=None) Delete a single VM .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.dimensiondata.get_configured_provider() Return the first configured instance. .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.dimensiondata.get_conn() Return a conn object for the passed VM data .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.dimensiondata.get_dependencies() Warn if dependencies aren\(aqt met. .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.dimensiondata.get_image(conn, vm_) Return the image object to use .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.dimensiondata.get_lb_conn(dd_driver=None) Return a load\-balancer conn object .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.dimensiondata.get_node(conn, name) Return a libcloud node for the named VM .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.dimensiondata.get_size(conn, vm_) Return the VM\(aqs size object .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.dimensiondata.list_nodes(conn=None, call=None) Return a list of the VMs that are on the provider .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.dimensiondata.list_nodes_full(conn=None, call=None) Return a list of the VMs that are on the provider, with all fields .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.dimensiondata.list_nodes_select(conn=None, call=None) Return a list of the VMs that are on the provider, with select fields .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.dimensiondata.preferred_ip(vm_, ips) Return the preferred Internet protocol. Either \(aqipv4\(aq (default) or \(aqipv6\(aq. .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.dimensiondata.reboot(name, conn=None) Reboot a single VM .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.dimensiondata.script(vm_) Return the script deployment object .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.dimensiondata.show_instance(name, call=None) Show the details from the provider concerning an instance .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.dimensiondata.ssh_interface(vm_) Return the ssh_interface type to connect to. Either \(aqpublic_ips\(aq (default) or \(aqprivate_ips\(aq. .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.dimensiondata.start(name, call=None) Stop a VM in DimensionData. .INDENT 7.0 .TP .B Parameters \fBname\fP (\fI\%str\fP) \-\- The name of the VM to stop. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-a stop vm_name .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.dimensiondata.stop(name, call=None) Stop a VM in DimensionData. .INDENT 7.0 .TP .B name: The name of the VM to stop. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-a stop vm_name .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.cloud.clouds.ec2 .SS The EC2 Cloud Module .sp The EC2 cloud module is used to interact with the Amazon Elastic Compute Cloud. .INDENT 0.0 .TP .B To use the EC2 cloud module, set up the cloud configuration at \fB/etc/salt/cloud.providers\fP or \fB/etc/salt/cloud.providers.d/ec2.conf\fP: .UNINDENT .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C my\-ec2\-config: # EC2 API credentials: Access Key ID and Secret Access Key. # Alternatively, to use IAM Instance Role credentials available via # EC2 metadata set both id and key to \(aquse\-instance\-role\-credentials\(aq id: GKTADJGHEIQSXMKKRBJ08H key: askdjghsdfjkghWupUjasdflkdfklgjsdfjajkghs # If \(aqrole_arn\(aq is specified the above credentials are used to # to assume to the role. By default, role_arn is set to None. role_arn: arn:aws:iam::012345678910:role/SomeRoleName # The ssh keyname to use keyname: default # The amazon security group securitygroup: ssh_open # The location of the private key which corresponds to the keyname private_key: /root/default.pem # Be default, service_url is set to amazonaws.com. If you are using this # driver for something other than Amazon EC2, change it here: service_url: amazonaws.com # The endpoint that is ultimately used is usually formed using the region # and the service_url. If you would like to override that entirely, you # can explicitly define the endpoint: endpoint: myendpoint.example.com:1138/services/Cloud # SSH Gateways can be used with this provider. Gateways can be used # when a salt\-master is not on the same private network as the instance # that is being deployed. # Defaults to None # Required ssh_gateway: gateway.example.com # Defaults to port 22 # Optional ssh_gateway_port: 22 # Defaults to root # Optional ssh_gateway_username: root # Default to nc \-q0 %h %p # Optional ssh_gateway_command: "\-W %h:%p" # One authentication method is required. If both # are specified, Private key wins. # Private key defaults to None ssh_gateway_private_key: /path/to/key.pem # Password defaults to None ssh_gateway_password: ExamplePasswordHere driver: ec2 # Pass userdata to the instance to be created userdata_file: /etc/salt/my\-userdata\-file # Instance termination protection setting # Default is disabled termination_protection: False .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .TP .B depends requests .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.ec2.attach_volume(name=None, kwargs=None, instance_id=None, call=None) Attach a volume to an instance .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.ec2.avail_images(kwargs=None, call=None) Return a dict of all available VM images on the cloud provider. .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.ec2.avail_locations(call=None) List all available locations .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.ec2.avail_sizes(call=None) Return a dict of all available VM sizes on the cloud provider with relevant data. Latest version can be found at: .sp \fI\%http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/instance\-types.html\fP .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.ec2.block_device_mappings(vm_) Return the block device mapping: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C [{\(aqDeviceName\(aq: \(aq/dev/sdb\(aq, \(aqVirtualName\(aq: \(aqephemeral0\(aq}, {\(aqDeviceName\(aq: \(aq/dev/sdc\(aq, \(aqVirtualName\(aq: \(aqephemeral1\(aq}] .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.ec2.copy_snapshot(kwargs=None, call=None) Copy a snapshot .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.ec2.create(vm_=None, call=None) Create a single VM from a data dict .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.ec2.create_attach_volumes(name, kwargs, call=None, wait_to_finish=True) Create and attach volumes to created node .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.ec2.create_keypair(kwargs=None, call=None) Create an SSH keypair .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.ec2.create_snapshot(kwargs=None, call=None, wait_to_finish=False) Create a snapshot. .INDENT 7.0 .TP .B volume_id The ID of the Volume from which to create a snapshot. .TP .B description The optional description of the snapshot. .UNINDENT .sp CLI Exampe: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-f create_snapshot my\-ec2\-config volume_id=vol\-351d8826 salt\-cloud \-f create_snapshot my\-ec2\-config volume_id=vol\-351d8826 \e description="My Snapshot Description" .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.ec2.create_volume(kwargs=None, call=None, wait_to_finish=False) Create a volume. .INDENT 7.0 .TP .B zone The availability zone used to create the volume. Required. String. .TP .B size The size of the volume, in GiBs. Defaults to \fB10\fP\&. Integer. .TP .B snapshot The snapshot\-id from which to create the volume. Integer. .TP .B type The volume type. This can be gp2 for General Purpose SSD, io1 for Provisioned IOPS SSD, st1 for Throughput Optimized HDD, sc1 for Cold HDD, or standard for Magnetic volumes. String. .TP .B iops The number of I/O operations per second (IOPS) to provision for the volume, with a maximum ratio of 50 IOPS/GiB. Only valid for Provisioned IOPS SSD volumes. Integer. .sp This option will only be set if \fBtype\fP is also specified as \fBio1\fP\&. .TP .B encrypted Specifies whether the volume will be encrypted. Boolean. .sp If \fBsnapshot\fP is also given in the list of kwargs, then this value is ignored since volumes that are created from encrypted snapshots are also automatically encrypted. .TP .B tags The tags to apply to the volume during creation. Dictionary. .TP .B call The \fBcreate_volume\fP function must be called with \fB\-f\fP or \fB\-\-function\fP\&. String. .TP .B wait_to_finish Whether or not to wait for the volume to be available. Boolean. Defaults to \fBFalse\fP\&. .UNINDENT .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-f create_volume my\-ec2\-config zone=us\-east\-1b salt\-cloud \-f create_volume my\-ec2\-config zone=us\-east\-1b tags=\(aq{"tag1": "val1", "tag2", "val2"}\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.ec2.del_tags(name=None, kwargs=None, call=None, instance_id=None, resource_id=None) Delete tags for a resource. Normally a VM name or instance_id is passed in, but a resource_id may be passed instead. If both are passed in, the instance_id will be used. .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-a del_tags mymachine tags=mytag, salt\-cloud \-a del_tags mymachine tags=tag1,tag2,tag3 salt\-cloud \-a del_tags resource_id=vol\-3267ab32 tags=tag1,tag2,tag3 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.ec2.delete_keypair(kwargs=None, call=None) Delete an SSH keypair .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.ec2.delete_snapshot(kwargs=None, call=None) Delete a snapshot .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.ec2.delete_volume(name=None, kwargs=None, instance_id=None, call=None) Delete a volume .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.ec2.delvol_on_destroy(name, kwargs=None, call=None) Delete all/specified EBS volumes upon instance termination .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-a delvol_on_destroy mymachine .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.ec2.describe_snapshots(kwargs=None, call=None) Describe a snapshot (or snapshots) .INDENT 7.0 .TP .B snapshot_id One or more snapshot IDs. Multiple IDs must be separated by ",". .TP .B owner Return the snapshots owned by the specified owner. Valid values include: self, amazon, . Multiple values must be separated by ",". .TP .B restorable_by One or more AWS accounts IDs that can create volumes from the snapshot. Multiple aws account IDs must be separated by ",". .UNINDENT .sp TODO: Add all of the filters. .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.ec2.describe_volumes(kwargs=None, call=None) Describe a volume (or volumes) .INDENT 7.0 .TP .B volume_id One or more volume IDs. Multiple IDs must be separated by ",". .UNINDENT .sp TODO: Add all of the filters. .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.ec2.destroy(name, call=None) Destroy a node. Will check termination protection and warn if enabled. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-\-destroy mymachine .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.ec2.detach_volume(name=None, kwargs=None, instance_id=None, call=None) Detach a volume from an instance .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.ec2.disable_detailed_monitoring(name, call=None) Enable/disable detailed monitoring on a node .sp CLI Example: .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.ec2.disable_term_protect(name, call=None) Disable termination protection on a node .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-a disable_term_protect mymachine .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.ec2.enable_detailed_monitoring(name, call=None) Enable/disable detailed monitoring on a node .sp CLI Example: .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.ec2.enable_term_protect(name, call=None) Enable termination protection on a node .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-a enable_term_protect mymachine .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.ec2.get_availability_zone(vm_) Return the availability zone to use .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.ec2.get_configured_provider() Return the first configured instance. .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.ec2.get_console_output(name=None, location=None, instance_id=None, call=None, kwargs=None) Show the console output from the instance. .sp By default, returns decoded data, not the Base64\-encoded data that is actually returned from the EC2 API. .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.ec2.get_dependencies() Warn if dependencies aren\(aqt met. .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.ec2.get_imageid(vm_) Returns the ImageId to use .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.ec2.get_location(vm_=None) .INDENT 7.0 .TP .B Return the EC2 region to use, in this order: .INDENT 7.0 .IP \(bu 2 CLI parameter .IP \(bu 2 VM parameter .IP \(bu 2 Cloud profile setting .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.ec2.get_password_data(name=None, kwargs=None, instance_id=None, call=None) Return password data for a Windows instance. .sp By default only the encrypted password data will be returned. However, if a key_file is passed in, then a decrypted password will also be returned. .sp Note that the key_file references the private key that was used to generate the keypair associated with this instance. This private key will _not_ be transmitted to Amazon; it is only used internally inside of Salt Cloud to decrypt data _after_ it has been received from Amazon. .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-a get_password_data mymachine salt\-cloud \-a get_password_data mymachine key_file=/root/ec2key.pem .ft P .fi .UNINDENT .UNINDENT .sp Note: PKCS1_v1_5 was added in PyCrypto 2.5 .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.ec2.get_placementgroup(vm_) Returns the PlacementGroup to use .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.ec2.get_provider(vm_=None) Extract the provider name from vm .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.ec2.get_spot_config(vm_) Returns the spot instance configuration for the provided vm .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.ec2.get_ssh_gateway_config(vm_) Return the ssh_gateway configuration. .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.ec2.get_subnetid(vm_) Returns the SubnetId to use .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.ec2.get_tags(name=None, instance_id=None, call=None, location=None, kwargs=None, resource_id=None) Retrieve tags for a resource. Normally a VM name or instance_id is passed in, but a resource_id may be passed instead. If both are passed in, the instance_id will be used. .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-a get_tags mymachine salt\-cloud \-a get_tags resource_id=vol\-3267ab32 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.ec2.get_tenancy(vm_) Returns the Tenancy to use. .sp Can be "dedicated" or "default". Cannot be present for spot instances. .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.ec2.iam_profile(vm_) Return the IAM profile. .sp The IAM instance profile to associate with the instances. This is either the Amazon Resource Name (ARN) of the instance profile or the name of the role. .sp Type: String .sp Default: None .sp Required: No .sp Example: arn:aws:iam::111111111111:instance\-profile/s3access .sp Example: s3access .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.ec2.import_keypair(kwargs=None, call=None) Import an SSH public key. .sp New in version 2015.8.3. .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.ec2.keepvol_on_destroy(name, kwargs=None, call=None) Do not delete all/specified EBS volumes upon instance termination .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-a keepvol_on_destroy mymachine .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.ec2.keyname(vm_) Return the keyname .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.ec2.list_availability_zones(vm_=None) List all availability zones in the current region .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.ec2.list_nodes(call=None) Return a list of the VMs that are on the provider .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.ec2.list_nodes_full(location=None, call=None) Return a list of the VMs that are on the provider .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.ec2.list_nodes_min(location=None, call=None) Return a list of the VMs that are on the provider. Only a list of VM names, and their state, is returned. This is the minimum amount of information needed to check for existing VMs. .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.ec2.list_nodes_select(call=None) Return a list of the VMs that are on the provider, with select fields .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.ec2.optimize_providers(providers) Return an optimized list of providers. .sp We want to reduce the duplication of querying the same region. .sp If a provider is using the same credentials for the same region the same data will be returned for each provider, thus causing un\-wanted duplicate data and API calls to EC2. .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.ec2.query(params=None, setname=None, requesturl=None, location=None, return_url=False, return_root=False) .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.ec2.query_instance(vm_=None, call=None) Query an instance upon creation from the EC2 API .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.ec2.queue_instances(instances) Queue a set of instances to be provisioned later. Expects a list. .sp Currently this only queries node data, and then places it in the cloud cache (if configured). If the salt\-cloud\-reactor is being used, these instances will be automatically provisioned using that. .sp For more information about the salt\-cloud\-reactor, see: .sp \fI\%https://github.com/saltstack\-formulas/salt\-cloud\-reactor\fP .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.ec2.reboot(name, call=None) Reboot a node. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-a reboot mymachine .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.ec2.register_image(kwargs=None, call=None) Create an ami from a snapshot .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-f register_image my\-ec2\-config ami_name=my_ami description="my description" root_device_name=/dev/xvda snapshot_id=snap\-xxxxxxxx .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.ec2.rename(name, kwargs, call=None) Properly rename a node. Pass in the new name as "new name". .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-a rename mymachine newname=yourmachine .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.ec2.request_instance(vm_=None, call=None) Put together all of the information necessary to request an instance on EC2, and then fire off the request the instance. .sp Returns data about the instance .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.ec2.script(vm_) Return the script deployment object .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.ec2.securitygroup(vm_) Return the security group .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.ec2.securitygroupid(vm_) Returns the SecurityGroupId .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.ec2.set_tags(name=None, tags=None, call=None, location=None, instance_id=None, resource_id=None, kwargs=None) Set tags for a resource. Normally a VM name or instance_id is passed in, but a resource_id may be passed instead. If both are passed in, the instance_id will be used. .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-a set_tags mymachine tag1=somestuff tag2=\(aqOther stuff\(aq salt\-cloud \-a set_tags resource_id=vol\-3267ab32 tag=somestuff .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.ec2.show_delvol_on_destroy(name, kwargs=None, call=None) Do not delete all/specified EBS volumes upon instance termination .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-a show_delvol_on_destroy mymachine .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.ec2.show_detailed_monitoring(name=None, instance_id=None, call=None, quiet=False) Show the details from EC2 regarding cloudwatch detailed monitoring. .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.ec2.show_image(kwargs, call=None) Show the details from EC2 concerning an AMI .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.ec2.show_instance(name=None, instance_id=None, call=None, kwargs=None) Show the details from EC2 concerning an AMI. .sp Can be called as an action (which requires a name): .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-a show_instance myinstance .ft P .fi .UNINDENT .UNINDENT .sp \&...or as a function (which requires either a name or instance_id): .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-f show_instance my\-ec2 name=myinstance salt\-cloud \-f show_instance my\-ec2 instance_id=i\-d34db33f .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.ec2.show_keypair(kwargs=None, call=None) Show the details of an SSH keypair .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.ec2.show_pricing(kwargs=None, call=None) Show pricing for a particular profile. This is only an estimate, based on unofficial pricing sources. .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-f show_pricing my\-ec2\-config profile=my\-profile .ft P .fi .UNINDENT .UNINDENT .sp If pricing sources have not been cached, they will be downloaded. Once they have been cached, they will not be updated automatically. To manually update all prices, use the following command: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-f update_pricing .ft P .fi .UNINDENT .UNINDENT .sp New in version 2015.8.0. .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.ec2.show_term_protect(name=None, instance_id=None, call=None, quiet=False) Show the details from EC2 concerning an instance\(aqs termination protection state .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.ec2.show_volume(kwargs=None, call=None) Wrapper around describe_volumes. Here just to keep functionality. Might be depreciated later. .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.ec2.sign(key, msg) .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.ec2.ssh_interface(vm_) Return the ssh_interface type to connect to. Either \(aqpublic_ips\(aq (default) or \(aqprivate_ips\(aq. .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.ec2.ssm_create_association(name=None, kwargs=None, instance_id=None, call=None) Associates the specified SSM document with the specified instance .sp \fI\%http://docs.aws.amazon.com/ssm/latest/APIReference/API_CreateAssociation.html\fP .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-a ssm_create_association ec2\-instance\-name ssm_document=ssm\-document\-name .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.ec2.ssm_describe_association(name=None, kwargs=None, instance_id=None, call=None) Describes the associations for the specified SSM document or instance. .sp \fI\%http://docs.aws.amazon.com/ssm/latest/APIReference/API_DescribeAssociation.html\fP .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-a ssm_describe_association ec2\-instance\-name ssm_document=ssm\-document\-name .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.ec2.start(name, call=None) Start a node .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.ec2.stop(name, call=None) Stop a node .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.ec2.update_pricing(kwargs=None, call=None) Download most recent pricing information from AWS and convert to a local JSON file. .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-f update_pricing my\-ec2\-config salt\-cloud \-f update_pricing my\-ec2\-config type=linux .ft P .fi .UNINDENT .UNINDENT .sp New in version 2015.8.0. .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.ec2.volume_create(**kwargs) Wrapper around create_volume. Here just to ensure the compatibility with the cloud module. .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.ec2.volume_list(**kwargs) Wrapper around describe_volumes. Here just to ensure the compatibility with the cloud module. .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.ec2.wait_for_instance(vm_=None, data=None, ip_address=None, display_ssh_output=True, call=None) Wait for an instance upon creation from the EC2 API, to become available .UNINDENT .SS salt.cloud.clouds.gce .sp Copyright 2013 Google Inc. All Rights Reserved. .sp Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at .INDENT 0.0 .INDENT 3.5 \fI\%http://www.apache.org/licenses/LICENSE\-2.0\fP .UNINDENT .UNINDENT .sp Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. .SS Google Compute Engine Module .sp The Google Compute Engine module. This module interfaces with Google Compute Engine (GCE). To authenticate to GCE, you will need to create a Service Account. To set up Service Account Authentication, follow the gce_setup instructions. .SS Example Provider Configuration .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C my\-gce\-config: # The Google Cloud Platform Project ID project: "my\-project\-id" # The Service Account client ID service_account_email_address: 1234567890@developer.gserviceaccount.com # The location of the private key (PEM format) service_account_private_key: /home/erjohnso/PRIVKEY.pem driver: gce # Specify whether to use public or private IP for deploy script. # Valid options are: # private_ips \- The salt\-master is also hosted with GCE # public_ips \- The salt\-master is hosted outside of GCE ssh_interface: public_ips .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .TP .B maintainer Eric Johnson <\fI\%erjohnso@google.com\fP> .TP .B maintainer Russell Tolle <\fI\%russ.tolle@gmail.com\fP> .TP .B depends libcloud >= 1.0.0 .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.gce.attach_disk(name=None, kwargs=None, call=None) Attach an existing disk to an existing instance. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-a attach_disk myinstance disk_name=mydisk mode=READ_WRITE .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.gce.attach_lb(kwargs=None, call=None) Add an existing node/member to an existing load\-balancer configuration. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-f attach_lb gce name=lb member=myinstance .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.gce.avail_images(conn=None) Return a dict of all available VM images on the cloud provider with relevant data. .sp Note that for GCE, there are custom images within the project, but the generic images are in other projects. This returns a dict of images in the project plus images in well\-known public projects that provide supported images, as listed on this page: \fI\%https://cloud.google.com/compute/docs/operating\-systems/\fP .sp If image names overlap, the image in the current project is used. .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.gce.avail_locations(conn=None, call=None) Return a dict of all available VM locations on the cloud provider with relevant data .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.gce.avail_sizes(conn=None) Return a dict of available instances sizes (a.k.a machine types) and convert them to something more serializable. .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.gce.create(vm_=None, call=None) Create a single GCE instance from a data dict. .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.gce.create_address(kwargs=None, call=None) Create a static address in a region. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-f create_address gce name=my\-ip region=us\-central1 address=IP .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.gce.create_attach_volumes(name, kwargs, call=None) New in version 2017.7.0. .sp Create and attach multiple volumes to a node. The \(aqvolumes\(aq and \(aqnode\(aq arguments are required, where \(aqnode\(aq is a libcloud node, and \(aqvolumes\(aq is a list of maps, where each map contains: .INDENT 7.0 .TP .B size The size of the new disk in GB. Required. .TP .B type The disk type, either pd\-standard or pd\-ssd. Optional, defaults to pd\-standard. .TP .B image An image to use for this new disk. Optional. .TP .B snapshot A snapshot to use for this new disk. Optional. .TP .B auto_delete An option(bool) to keep or remove the disk upon instance deletion. Optional, defaults to False. .UNINDENT .sp Volumes are attached in the order in which they are given, thus on a new node the first volume will be /dev/sdb, the second /dev/sdc, and so on. .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.gce.create_disk(kwargs=None, call=None) Create a new persistent disk. Must specify \fIdisk_name\fP and \fIlocation\fP, and optionally can specify \(aqdisk_type\(aq as pd\-standard or pd\-ssd, which defaults to pd\-standard. Can also specify an \fIimage\fP or \fIsnapshot\fP but if neither of those are specified, a \fIsize\fP (in GB) is required. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-f create_disk gce disk_name=pd size=300 location=us\-central1\-b .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.gce.create_fwrule(kwargs=None, call=None) Create a GCE firewall rule. The \(aqdefault\(aq network is used if not specified. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-f create_fwrule gce name=allow\-http allow=tcp:80 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.gce.create_hc(kwargs=None, call=None) Create an HTTP health check configuration. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-f create_hc gce name=hc path=/healthy port=80 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.gce.create_lb(kwargs=None, call=None) Create a load\-balancer configuration. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-f create_lb gce name=lb region=us\-central1 ports=80 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.gce.create_network(kwargs=None, call=None) \&... versionchanged:: 2017.7.0 Create a GCE network. Must specify name and cidr. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-f create_network gce name=mynet cidr=10.10.10.0/24 mode=legacy description=optional salt\-cloud \-f create_network gce name=mynet description=optional .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.gce.create_snapshot(kwargs=None, call=None) Create a new disk snapshot. Must specify \fIname\fP and \fIdisk_name\fP\&. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-f create_snapshot gce name=snap1 disk_name=pd .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.gce.create_subnetwork(kwargs=None, call=None) \&... versionadded:: 2017.7.0 Create a GCE Subnetwork. Must specify name, cidr, network, and region. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-f create_subnetwork gce name=mysubnet network=mynet1 region=us\-west1 cidr=10.0.0.0/24 description=optional .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.gce.delete_address(kwargs=None, call=None) Permanently delete a static address. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-f delete_address gce name=my\-ip .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.gce.delete_disk(kwargs=None, call=None) Permanently delete a persistent disk. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-f delete_disk gce disk_name=pd .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.gce.delete_fwrule(kwargs=None, call=None) Permanently delete a firewall rule. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-f delete_fwrule gce name=allow\-http .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.gce.delete_hc(kwargs=None, call=None) Permanently delete a health check. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-f delete_hc gce name=hc .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.gce.delete_lb(kwargs=None, call=None) Permanently delete a load\-balancer. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-f delete_lb gce name=lb .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.gce.delete_network(kwargs=None, call=None) Permanently delete a network. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-f delete_network gce name=mynet .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.gce.delete_snapshot(kwargs=None, call=None) Permanently delete a disk snapshot. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-f delete_snapshot gce name=disk\-snap\-1 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.gce.delete_subnetwork(kwargs=None, call=None) \&... versionadded:: 2017.7.0 Delete a GCE Subnetwork. Must specify name and region. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-f delete_subnetwork gce name=mysubnet network=mynet1 region=us\-west1 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.gce.destroy(vm_name, call=None) Call \(aqdestroy\(aq on the instance. Can be called with "\-a destroy" or \-d .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-a destroy myinstance1 myinstance2 ... salt\-cloud \-d myinstance1 myinstance2 ... .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.gce.detach_disk(name=None, kwargs=None, call=None) Detach a disk from an instance. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-a detach_disk myinstance disk_name=mydisk .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.gce.detach_lb(kwargs=None, call=None) Remove an existing node/member from an existing load\-balancer configuration. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-f detach_lb gce name=lb member=myinstance .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.gce.get_configured_provider() Return the first configured instance. .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.gce.get_conn() Return a conn object for the passed VM data .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.gce.get_dependencies() Warn if dependencies aren\(aqt met. .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.gce.get_lb_conn(gce_driver=None) Return a load\-balancer conn object .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.gce.list_nodes(conn=None, call=None) Return a list of the VMs that are on the provider .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.gce.list_nodes_full(conn=None, call=None) Return a list of the VMs that are on the provider, with all fields .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.gce.list_nodes_select(conn=None, call=None) Return a list of the VMs that are on the provider, with select fields .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.gce.reboot(vm_name, call=None) Call GCE \(aqreset\(aq on the instance. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-a reboot myinstance .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.gce.request_instance(vm_) Request a single GCE instance from a data dict. .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.gce.script(vm_) Return the script deployment object .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.gce.show_address(kwargs=None, call=None) Show the details of an existing static address. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-f show_address gce name=mysnapshot region=us\-central1 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.gce.show_disk(name=None, kwargs=None, call=None) Show the details of an existing disk. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-a show_disk myinstance disk_name=mydisk salt\-cloud \-f show_disk gce disk_name=mydisk .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.gce.show_fwrule(kwargs=None, call=None) Show the details of an existing firewall rule. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-f show_fwrule gce name=allow\-http .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.gce.show_hc(kwargs=None, call=None) Show the details of an existing health check. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-f show_hc gce name=hc .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.gce.show_instance(vm_name, call=None) Show the details of the existing instance. .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.gce.show_lb(kwargs=None, call=None) Show the details of an existing load\-balancer. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-f show_lb gce name=lb .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.gce.show_network(kwargs=None, call=None) Show the details of an existing network. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-f show_network gce name=mynet .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.gce.show_pricing(kwargs=None, call=None) Show pricing for a particular profile. This is only an estimate, based on unofficial pricing sources. .sp New in version 2015.8.0. .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-f show_pricing my\-gce\-config profile=my\-profile .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.gce.show_snapshot(kwargs=None, call=None) Show the details of an existing snapshot. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-f show_snapshot gce name=mysnapshot .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.gce.show_subnetwork(kwargs=None, call=None) \&... versionadded:: 2017.7.0 Show details of an existing GCE Subnetwork. Must specify name and region. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-f show_subnetwork gce name=mysubnet region=us\-west1 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.gce.start(vm_name, call=None) Call GCE \(aqstart on the instance. .sp New in version 2017.7.0. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-a start myinstance .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.gce.stop(vm_name, call=None) Call GCE \(aqstop\(aq on the instance. .sp New in version 2017.7.0. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-a stop myinstance .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.gce.update_pricing(kwargs=None, call=None) Download most recent pricing information from GCE and save locally .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-f update_pricing my\-gce\-config .ft P .fi .UNINDENT .UNINDENT .sp New in version 2015.8.0. .UNINDENT .SS salt.cloud.clouds.gogrid .SS GoGrid Cloud Module .sp The GoGrid cloud module. This module interfaces with the gogrid public cloud service. 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 Set up the cloud configuration at \fB/etc/salt/cloud.providers\fP or \fB/etc/salt/cloud.providers.d/gogrid.conf\fP: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C my\-gogrid\-config: # The generated api key to use apikey: asdff7896asdh789 # The apikey\(aqs shared secret sharedsecret: saltybacon driver: gogrid .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 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 .INDENT 0.0 .TP .B salt.cloud.clouds.gogrid.avail_images() Available images .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.gogrid.avail_locations() Available locations .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.gogrid.avail_sizes() Available sizes .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.gogrid.create(vm_) Create a single VM from a data dict .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.gogrid.destroy(name, call=None) Destroy a machine by name .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-d vm_name .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.gogrid.get_configured_provider() Return the first configured instance. .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.gogrid.list_common_lookups(kwargs=None, call=None) List common lookups for a particular type of item .sp New in version 2015.8.0. .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.gogrid.list_nodes(full=False, call=None) List of nodes, keeping only a brief listing .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-Q .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.gogrid.list_nodes_full(call=None) List nodes, with all available information .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-F .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.gogrid.list_nodes_select(call=None) Return a list of the VMs that are on the provider, with select fields .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-S .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.gogrid.list_passwords(kwargs=None, call=None) List all password on the account .sp New in version 2015.8.0. .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.gogrid.list_public_ips(kwargs=None, call=None) List all available public IPs. .sp CLI Example: \&.. code\-block:: bash .INDENT 7.0 .INDENT 3.5 salt\-cloud \-f list_public_ips .UNINDENT .UNINDENT .sp To list unavailable (assigned) IPs, use: .sp CLI Example: \&.. code\-block:: bash .INDENT 7.0 .INDENT 3.5 salt\-cloud \-f list_public_ips state=assigned .UNINDENT .UNINDENT .sp New in version 2015.8.0. .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.gogrid.reboot(name, call=None) Reboot a machine by name .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-a reboot vm_name .ft P .fi .UNINDENT .UNINDENT .sp New in version 2015.8.0. .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.gogrid.show_instance(name, call=None) Start a machine by name .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-a show_instance vm_name .ft P .fi .UNINDENT .UNINDENT .sp New in version 2015.8.0. .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.gogrid.start(name, call=None) Start a machine by name .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-a start vm_name .ft P .fi .UNINDENT .UNINDENT .sp New in version 2015.8.0. .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.gogrid.stop(name, call=None) Stop a machine by name .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-a stop vm_name .ft P .fi .UNINDENT .UNINDENT .sp New in version 2015.8.0. .UNINDENT .SS salt.cloud.clouds.joyent .SS Joyent Cloud Module .sp The Joyent Cloud module is used to interact with the Joyent cloud system. .sp Set up the cloud configuration at \fB/etc/salt/cloud.providers\fP or \fB/etc/salt/cloud.providers.d/joyent.conf\fP: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C my\-joyent\-config: driver: joyent # The Joyent login user user: fred # The Joyent user\(aqs password password: saltybacon # The location of the ssh private key that can log into the new VM private_key: /root/mykey.pem # The name of the private key keyname: mykey .ft P .fi .UNINDENT .UNINDENT .sp When creating your profiles for the joyent cloud, add the location attribute to the profile, this will automatically get picked up when performing tasks associated with that vm. An example profile might look like: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C joyent_512: provider: my\-joyent\-config size: g4\-highcpu\-512M image: centos\-6 location: us\-east\-1 .ft P .fi .UNINDENT .UNINDENT .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 .INDENT 0.0 .TP .B depends PyCrypto .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.joyent.avail_images(call=None) Get list of available images .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-\-list\-images .ft P .fi .UNINDENT .UNINDENT .sp Can use a custom URL for images. Default is: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C image_url: images.joyent.com/images .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.joyent.avail_locations(call=None) List all available locations .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.joyent.avail_sizes(call=None) get list of available packages .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-\-list\-sizes .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.joyent.create(vm_) Create a single VM from a data dict .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-p profile_name vm_name .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.joyent.create_node(**kwargs) convenience function to make the rest api call for node creation. .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.joyent.delete_key(kwargs=None, call=None) List the keys available .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-f delete_key joyent keyname=mykey .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.joyent.destroy(name, call=None) destroy a machine by name .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBname\fP \-\- name given to the machine .IP \(bu 2 \fBcall\fP \-\- call value in this case is \(aqaction\(aq .UNINDENT .TP .B Returns array of booleans , true if successfully stopped and true if successfully removed .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-d vm_name .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.joyent.get_configured_provider() Return the first configured instance. .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.joyent.get_image(vm_) Return the image object to use .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.joyent.get_location(vm_=None) .INDENT 7.0 .TP .B Return the joyent data center to use, in this order: .INDENT 7.0 .IP \(bu 2 CLI parameter .IP \(bu 2 VM parameter .IP \(bu 2 Cloud profile setting .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.joyent.get_location_path(location=\(aqus\-east\-1\(aq, api_host_suffix=\(aq.api.joyentcloud.com\(aq) create url from location variable :param location: joyent data center location :return: url .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.joyent.get_node(name) gets the node from the full node list by name :param name: name of the vm :return: node object .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.joyent.get_size(vm_) Return the VM\(aqs size object .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.joyent.has_method(obj, method_name) Find if the provided object has a specific method .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.joyent.import_key(kwargs=None, call=None) List the keys available .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-f import_key joyent keyname=mykey keyfile=/tmp/mykey.pub .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.joyent.joyent_node_state(id_) Convert joyent returned state to state common to other data center return values for consistency .INDENT 7.0 .TP .B Parameters \fBid\fP \-\- joyent state value .TP .B Returns state value .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.joyent.key_list(items=None) convert list to dictionary using the key as the identifier :param items: array to iterate over :return: dictionary .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.joyent.list_keys(kwargs=None, call=None) List the keys available .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.joyent.list_nodes(full=False, call=None) list of nodes, keeping only a brief listing .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-Q .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.joyent.list_nodes_full(call=None) list of nodes, maintaining all content provided from joyent listings .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-F .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.joyent.list_nodes_select(call=None) Return a list of the VMs that are on the provider, with select fields .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.joyent.query(action=None, command=None, args=None, method=\(aqGET\(aq, location=None, data=None) Make a web call to Joyent .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.joyent.query_instance(vm_=None, call=None) Query an instance upon creation from the Joyent API .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.joyent.reboot(name, call=None) reboot a machine by name :param name: name given to the machine :param call: call value in this case is \(aqaction\(aq :return: true if successful .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-a reboot vm_name .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.joyent.reformat_node(item=None, full=False) Reformat the returned data from joyent, determine public/private IPs and strip out fields if necessary to provide either full or brief content. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBitem\fP \-\- node dictionary .IP \(bu 2 \fBfull\fP \-\- full or brief output .UNINDENT .TP .B Returns dict .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.joyent.show_instance(name, call=None) get details about a machine :param name: name given to the machine :param call: call value in this case is \(aqaction\(aq :return: machine information .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-a show_instance vm_name .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.joyent.show_key(kwargs=None, call=None) List the keys available .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.joyent.ssh_interface(vm_) Return the ssh_interface type to connect to. Either \(aqpublic_ips\(aq (default) or \(aqprivate_ips\(aq. .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.joyent.start(name, call=None) start a machine by name :param name: name given to the machine :param call: call value in this case is \(aqaction\(aq :return: true if successful .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-a start vm_name .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.joyent.stop(name, call=None) stop a machine by name :param name: name given to the machine :param call: call value in this case is \(aqaction\(aq :return: true if successful .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-a stop vm_name .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.joyent.take_action(name=None, call=None, command=None, data=None, method=\(aqGET\(aq, location=\(aqus\-east\-1\(aq) take action call used by start,stop, reboot :param name: name given to the machine :param call: call value in this case is \(aqaction\(aq :command: api path :data: any data to be passed to the api, must be in json format :method: GET,POST,or DELETE :location: data center to execute the command on :return: true if successful .UNINDENT .SS salt.cloud.clouds.libvirt .SS Libvirt Cloud Module .sp Example provider: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C # A provider maps to a libvirt instance my\-libvirt\-config: driver: libvirt # url: "qemu+ssh://user@remotekvm/system?socket=/var/run/libvirt/libvirt\-sock" url: qemu:///system .ft P .fi .UNINDENT .UNINDENT .sp Example profile: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C base\-itest: # points back at provider configuration e.g. the libvirt daemon to talk to provider: my\-libvirt\-config base_domain: base\-image # ip_source = [ ip\-learning | qemu\-agent ] ip_source: ip\-learning # clone_strategy = [ quick | full ] clone_strategy: quick ssh_username: vagrant # has_ssh_agent: True password: vagrant # if /tmp is mounted noexec do workaround deploy_command: sh /tmp/.saltcloud/deploy.sh # \-F makes the bootstrap script overwrite existing config # which make reprovisioning a box work script_args: \-F grains: sushi: more tasty # point at the another master at another port minion: master: 192.168.16.1 master_port: 5506 .ft P .fi .UNINDENT .UNINDENT .sp Tested on: \- Fedora 26 (libvirt 3.2.1, qemu 2.9.1) \- Fedora 25 (libvirt 1.3.3.2, qemu 2.6.1) \- Fedora 23 (libvirt 1.2.18, qemu 2.4.1) \- Centos 7 (libvirt 1.2.17, qemu 1.5.3) .INDENT 0.0 .TP .B salt.cloud.clouds.libvirt.create(vm_) Provision a single machine .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.libvirt.create_volume_with_backing_store_xml(volume) .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.libvirt.create_volume_xml(volume) .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.libvirt.destroy(name, call=None) This function irreversibly destroys a virtual machine on the cloud provider. Before doing so, it should fire an event on the Salt event bus. .sp The tag for this event is \fIsalt/cloud//destroying\fP\&. Once the virtual machine has been destroyed, another event is fired. The tag for that event is \fIsalt/cloud//destroyed\fP\&. .INDENT 7.0 .TP .B Dependencies: list_nodes .UNINDENT .sp @param name: @type name: str @param call: @type call: @return: True if all went well, otherwise an error message @rtype: bool|str .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.libvirt.destroy_domain(conn, domain) .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.libvirt.do_cleanup(cleanup) Clean up clone domain leftovers as much as possible. .sp Extra robust clean up in order to deal with some small changes in libvirt behavior over time. Passed in volumes and domains are deleted, any errors are ignored. Used when cloning/provisioning a domain fails. .INDENT 7.0 .TP .B Parameters \fBcleanup\fP \-\- list containing dictonaries with two keys: \(aqwhat\(aq and \(aqitem\(aq. If \(aqwhat\(aq is domain the \(aqitem\(aq is a libvirt domain object. If \(aqwhat\(aq is volume then the item is a libvirt volume object. .TP .B Returns none .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.libvirt.find_pool_and_volume(conn, path) .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.libvirt.generate_new_name(orig_name) .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.libvirt.get_configured_provider() Return the first configured instance. .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.libvirt.get_domain_ip(domain, idx, ip_source, skip_loopback=True) .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.libvirt.get_domain_ips(domain, ip_source) .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.libvirt.get_domain_volumes(conn, domain) .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.libvirt.libvirt_error_handler(ctx, error) Redirect stderr prints from libvirt to salt logging. .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.libvirt.list_nodes(call=None) Return a list of the VMs .sp id (str) image (str) size (str) state (str) private_ips (list) public_ips (list) .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.libvirt.list_nodes_full(call=None) Because this module is not specific to any cloud providers, there will be no nodes to list. .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.libvirt.list_nodes_select(call=None) Return a list of the VMs that are on the provider, with select fields .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.libvirt.to_ip_addr_type(addr_type) .UNINDENT .SS salt.cloud.clouds.linode .SS The Linode Cloud Module .sp The Linode cloud module is used to interact with the Linode Cloud. .sp You can target a specific version of the Linode API with the \fBapi_version\fP parameter. The default is \fBv3\fP\&. .SS Provider .sp The following provider parameters are supported: .INDENT 0.0 .IP \(bu 2 \fBapikey\fP: (required) The key to use to authenticate with the Linode API. .IP \(bu 2 \fBpassword\fP: (required) The default password to set on new VMs. Must be 8 characters with at least one lowercase, uppercase, and numeric. .IP \(bu 2 \fBapi_version\fP: (optional) The version of the Linode API to interact with. Defaults to \fBv3\fP\&. .IP \(bu 2 \fBpoll_interval\fP: (optional) The rate of time in milliseconds to poll the Linode API for changes. Defaults to \fB500\fP\&. .IP \(bu 2 \fBratelimit_sleep\fP: (optional) The time in seconds to wait before retrying after a ratelimit has been enforced. Defaults to \fB0\fP\&. .UNINDENT .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 APIv3 usage is deprecated and will be removed in a future release in favor of APIv4. To move to APIv4 now, set the \fBapi_version\fP parameter in your provider configuration to \fBv4\fP\&. See the full migration guide here \fI\%https://docs.saltstack.com/en/latest/topics/cloud/linode.html#migrating\-to\-apiv4\fP\&. .UNINDENT .UNINDENT .sp Set up the provider configuration at \fB/etc/salt/cloud.providers\fP or \fB/etc/salt/cloud.providers.d/linode.conf\fP: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C my\-linode\-provider: driver: linode api_version: v4 apikey: f4ZsmwtB1c7f85Jdu43RgXVDFlNjuJaeIYV8QMftTqKScEB2vSosFSr... password: F00barbaz .ft P .fi .UNINDENT .UNINDENT .sp For use with APIv3 (deprecated): .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C my\-linode\-provider\-v3: driver: linode apikey: f4ZsmwtB1c7f85Jdu43RgXVDFlNjuJaeIYV8QMftTqKScEB2vSosFSr... password: F00barbaz .ft P .fi .UNINDENT .UNINDENT .SS Profile .sp The following profile parameters are supported: .INDENT 0.0 .IP \(bu 2 \fBsize\fP: (required) The size of the VM. This should be a Linode instance type ID (i.e. \fBg6\-standard\-2\fP). For APIv3, this would be a plan ID (i.e. \fBLinode 2GB\fP). Run \fBsalt\-cloud \-f avail_sizes my\-linode\-provider\fP for options. .IP \(bu 2 \fBlocation\fP: (required) The location of the VM. This should be a Linode region (e.g. \fBus\-east\fP). For APIv3, this would be a datacenter location (i.e. \fBNewark, NJ, USA\fP). Run \fBsalt\-cloud \-f avail_locations my\-linode\-provider\fP for options. .IP \(bu 2 \fBimage\fP: (required) The image to deploy the boot disk from. This should be an image ID (e.g. \fBlinode/ubuntu16.04\fP); official images start with \fBlinode/\fP\&. For APIv3, this would be an image label (i.e. Ubuntu 16.04). Run \fBsalt\-cloud \-f avail_images my\-linode\-provider\fP for more options. .IP \(bu 2 \fBpassword\fP: (*required) The default password for the VM. Must be provided at the profile or provider level. .IP \(bu 2 \fBassign_private_ip\fP: (optional) Whether or not to assign a private key to the VM. Defaults to \fBFalse\fP\&. .IP \(bu 2 \fBssh_interface\fP: (optional) The interface with which to connect over SSH. Valid options are \fBprivate_ips\fP or \fBpublic_ips\fP\&. Defaults to \fBpublic_ips\fP\&. .IP \(bu 2 \fBssh_pubkey\fP: (optional) The public key to authorize for SSH with the VM. .IP \(bu 2 \fBswap\fP: (optional) The amount of disk space to allocate for the swap partition. Defaults to \fB256\fP\&. .IP \(bu 2 \fBclonefrom\fP: (optional) The name of the Linode to clone from. .IP \(bu 2 \fBdisk_size\fP: (deprecated, optional) The amount of disk space to allocate for the OS disk. This has no effect with APIv4; the size of the boot disk will be the remainder of disk space after the swap parition is allocated. .UNINDENT .sp Set up a profile configuration in \fB/etc/salt/cloud.profiles.d/\fP: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C my\-linode\-profile: # a minimal configuration provider: my\-linode\-provider size: g6\-standard\-1 image: linode/alpine3.12 location: us\-east my\-linode\-profile\-advanced: # an advanced configuration provider: my\-linode\-provider size: g6\-standard\-3 image: linode/alpine3.10 location: eu\-west password: bogus123X assign_private_ip: true ssh_interface: private_ips ssh_pubkey: ssh\-rsa AAAAB3NzaC1yc2EAAAADAQAB... swap_size: 512 my\-linode\-profile\-v3: # a legacy configuration provider: my\-linode\-provider\-v3 size: Nanode 1GB image: Alpine 3.12 location: Fremont, CA, USA .ft P .fi .UNINDENT .UNINDENT .SS Migrating to APIv4 .sp In order to target APIv4, ensure your provider configuration has \fBapi_version\fP set to \fBv4\fP\&. .sp You will also need to generate a new token for your account. See \fI\%https://www.linode.com/docs/platform/api/getting\-started\-with\-the\-linode\-api/#create\-an\-api\-token\fP .sp There are a few changes to note: \- There has been a general move from label references to ID references. The profile configuration parameters \fBlocation\fP, \fBsize\fP, and \fBimage\fP have moved from being label based references to IDs. See the profile section for more information. In addition to these inputs being changed, \fBavail_sizes\fP, \fBavail_locations\fP, and \fBavail_images\fP now output options sorted by ID instead of label. \- The \fBdisk_size\fP profile configuration parameter has been deprecated and will not be taken into account when creating new VMs while targeting APIv4. .INDENT 0.0 .TP .B maintainer Charles Kenney <\fI\%ckenney@linode.com\fP> .TP .B maintainer Phillip Campbell <\fI\%pcampbell@linode.com\fP> .TP .B depends requests .UNINDENT .INDENT 0.0 .TP .B class salt.cloud.clouds.linode.LinodeAPI .INDENT 7.0 .TP .B abstract avail_images() avail_images implementation .UNINDENT .INDENT 7.0 .TP .B abstract avail_locations() avail_locations implementation .UNINDENT .INDENT 7.0 .TP .B abstract avail_sizes() avail_sizes implementation .UNINDENT .INDENT 7.0 .TP .B abstract boot(name=None, kwargs=None) boot implementation .UNINDENT .INDENT 7.0 .TP .B abstract clone(kwargs=None) clone implementation .UNINDENT .INDENT 7.0 .TP .B abstract create(vm_) create implementation .UNINDENT .INDENT 7.0 .TP .B abstract create_config(kwargs=None) create_config implementation .UNINDENT .INDENT 7.0 .TP .B abstract destroy(name) destroy implementation .UNINDENT .INDENT 7.0 .TP .B abstract get_config_id(kwargs=None) get_config_id implementation .UNINDENT .INDENT 7.0 .TP .B get_linode(kwargs=None) .UNINDENT .INDENT 7.0 .TP .B get_plan_id(kwargs=None) get_plan_id implementation .UNINDENT .INDENT 7.0 .TP .B abstract list_nodes() list_nodes implementation .UNINDENT .INDENT 7.0 .TP .B abstract list_nodes_full() list_nodes_full implementation .UNINDENT .INDENT 7.0 .TP .B abstract list_nodes_min() list_nodes_min implementation .UNINDENT .INDENT 7.0 .TP .B list_nodes_select(call) .UNINDENT .INDENT 7.0 .TP .B abstract reboot(name) reboot implementation .UNINDENT .INDENT 7.0 .TP .B abstract show_instance(name) show_instance implementation .UNINDENT .INDENT 7.0 .TP .B abstract show_pricing(kwargs=None) show_pricing implementation .UNINDENT .INDENT 7.0 .TP .B abstract start(name) start implementation .UNINDENT .INDENT 7.0 .TP .B abstract stop(name) stop implementation .UNINDENT .UNINDENT .INDENT 0.0 .TP .B class salt.cloud.clouds.linode.LinodeAPIv3 .INDENT 7.0 .TP .B avail_images() avail_images implementation .UNINDENT .INDENT 7.0 .TP .B avail_locations() avail_locations implementation .UNINDENT .INDENT 7.0 .TP .B avail_sizes() avail_sizes implementation .UNINDENT .INDENT 7.0 .TP .B boot(name=None, kwargs=None) boot implementation .UNINDENT .INDENT 7.0 .TP .B clone(kwargs=None) clone implementation .UNINDENT .INDENT 7.0 .TP .B create(vm_) create implementation .UNINDENT .INDENT 7.0 .TP .B create_config(kwargs=None) create_config implementation .UNINDENT .INDENT 7.0 .TP .B destroy(name) destroy implementation .UNINDENT .INDENT 7.0 .TP .B get_config_id(kwargs=None) get_config_id implementation .UNINDENT .INDENT 7.0 .TP .B get_plan_id(kwargs=None) get_plan_id implementation .UNINDENT .INDENT 7.0 .TP .B list_nodes() list_nodes implementation .UNINDENT .INDENT 7.0 .TP .B list_nodes_full() list_nodes_full implementation .UNINDENT .INDENT 7.0 .TP .B list_nodes_min() list_nodes_min implementation .UNINDENT .INDENT 7.0 .TP .B reboot(name) reboot implementation .UNINDENT .INDENT 7.0 .TP .B show_instance(name) show_instance implementation .UNINDENT .INDENT 7.0 .TP .B show_pricing(kwargs=None) show_pricing implementation .UNINDENT .INDENT 7.0 .TP .B start(name) start implementation .UNINDENT .INDENT 7.0 .TP .B stop(name) stop implementation .UNINDENT .UNINDENT .INDENT 0.0 .TP .B class salt.cloud.clouds.linode.LinodeAPIv4 .INDENT 7.0 .TP .B avail_images() avail_images implementation .UNINDENT .INDENT 7.0 .TP .B avail_locations() avail_locations implementation .UNINDENT .INDENT 7.0 .TP .B avail_sizes() avail_sizes implementation .UNINDENT .INDENT 7.0 .TP .B boot(name=None, kwargs=None) boot implementation .UNINDENT .INDENT 7.0 .TP .B clone(kwargs=None) clone implementation .UNINDENT .INDENT 7.0 .TP .B create(vm_) create implementation .UNINDENT .INDENT 7.0 .TP .B create_config(kwargs=None) create_config implementation .UNINDENT .INDENT 7.0 .TP .B destroy(name) destroy implementation .UNINDENT .INDENT 7.0 .TP .B get_config_id(kwargs=None) get_config_id implementation .UNINDENT .INDENT 7.0 .TP .B list_nodes() list_nodes implementation .UNINDENT .INDENT 7.0 .TP .B list_nodes_full() list_nodes_full implementation .UNINDENT .INDENT 7.0 .TP .B list_nodes_min() list_nodes_min implementation .UNINDENT .INDENT 7.0 .TP .B reboot(name) reboot implementation .UNINDENT .INDENT 7.0 .TP .B show_instance(name) show_instance implementation .UNINDENT .INDENT 7.0 .TP .B show_pricing(kwargs=None) show_pricing implementation .UNINDENT .INDENT 7.0 .TP .B start(name) start implementation .UNINDENT .INDENT 7.0 .TP .B stop(name) stop implementation .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.linode.avail_images(call=None) Return available Linode images. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-\-list\-images my\-linode\-config salt\-cloud \-f avail_images my\-linode\-config .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.linode.avail_locations(call=None) Return available Linode datacenter locations. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-\-list\-locations my\-linode\-config salt\-cloud \-f avail_locations my\-linode\-config .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.linode.avail_sizes(call=None) Return available Linode sizes. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-\-list\-sizes my\-linode\-config salt\-cloud \-f avail_sizes my\-linode\-config .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.linode.boot(name=None, kwargs=None, call=None) Boot a Linode. .INDENT 7.0 .TP .B name The name of the Linode to boot. Can be used instead of \fBlinode_id\fP\&. .TP .B linode_id The ID of the Linode to boot. If provided, will be used as an alternative to \fBname\fP and reduces the number of API calls to Linode by one. Will be preferred over \fBname\fP\&. .TP .B config_id The ID of the Config to boot. Required. .TP .B check_running Defaults to True. If set to False, overrides the call to check if the VM is running before calling the linode.boot API call. Change \fBcheck_running\fP to True is useful during the boot call in the create function, since the new VM will not be running yet. .UNINDENT .sp Can be called as an action (which requires a name): .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-a boot my\-instance config_id=10 .ft P .fi .UNINDENT .UNINDENT .sp \&...or as a function (which requires either a name or linode_id): .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-f boot my\-linode\-config name=my\-instance config_id=10 salt\-cloud \-f boot my\-linode\-config linode_id=1225876 config_id=10 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.linode.clone(kwargs=None, call=None) Clone a Linode. .INDENT 7.0 .TP .B linode_id The ID of the Linode to clone. Required. .TP .B location The location of the new Linode. Required. .TP .B size The size of the new Linode (must be greater than or equal to the clone source). Required. .TP .B datacenter_id The ID of the Datacenter where the Linode will be placed. Required for APIv3 usage. Deprecated. Use \fBlocation\fP instead. .TP .B plan_id The ID of the plan (size) of the Linode. Required. Required for APIv3 usage. Deprecated. Use \fBsize\fP instead. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-f clone my\-linode\-config linode_id=1234567 datacenter_id=2 plan_id=5 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.linode.create(vm_) Create a single Linode VM. .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.linode.create_config(kwargs=None, call=None) Creates a Linode Configuration Profile. .INDENT 7.0 .TP .B name The name of the VM to create the config for. .TP .B linode_id The ID of the Linode to create the configuration for. .TP .B root_disk_id The Root Disk ID to be used for this config. .TP .B swap_disk_id The Swap Disk ID to be used for this config. .TP .B data_disk_id The Data Disk ID to be used for this config. .UNINDENT .sp New in version 2016.3.0. .INDENT 7.0 .TP .B kernel_id The ID of the kernel to use for this configuration profile. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.linode.destroy(name, call=None) Destroys a Linode by name. .INDENT 7.0 .TP .B name The name of VM to be be destroyed. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-d vm_name .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.linode.get_config_id(kwargs=None, call=None) Returns a config_id for a given linode. .sp New in version 2015.8.0. .INDENT 7.0 .TP .B name The name of the Linode for which to get the config_id. Can be used instead of \fBlinode_id\fP\&. .TP .B linode_id The ID of the Linode for which to get the config_id. Can be used instead of \fBname\fP\&. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-f get_config_id my\-linode\-config name=my\-linode salt\-cloud \-f get_config_id my\-linode\-config linode_id=1234567 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.linode.get_configured_provider() Return the first configured instance. .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.linode.get_linode(kwargs=None, call=None) Returns data for a single named Linode. .INDENT 7.0 .TP .B name The name of the Linode for which to get data. Can be used instead \fBlinode_id\fP\&. Note this will induce an additional API call compared to using \fBlinode_id\fP\&. .TP .B linode_id The ID of the Linode for which to get data. Can be used instead of \fBname\fP\&. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-f get_linode my\-linode\-config name=my\-instance salt\-cloud \-f get_linode my\-linode\-config linode_id=1234567 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.linode.get_plan_id(kwargs=None, call=None) Returns the Linode Plan ID. .INDENT 7.0 .TP .B label The label, or name, of the plan to get the ID from. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-f get_plan_id linode label="Nanode 1GB" salt\-cloud \-f get_plan_id linode label="Linode 2GB" .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.linode.list_nodes(call=None) Returns a list of linodes, keeping only a brief listing. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-Q salt\-cloud \-\-query salt\-cloud \-f list_nodes my\-linode\-config .ft P .fi .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 The \fBimage\fP label only displays information about the VM\(aqs distribution vendor, such as "Debian" or "RHEL" and does not display the actual image name. This is due to a limitation of the Linode API. .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.linode.list_nodes_full(call=None) List linodes, with all available information. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-F salt\-cloud \-\-full\-query salt\-cloud \-f list_nodes_full my\-linode\-config .ft P .fi .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 The \fBimage\fP label only displays information about the VM\(aqs distribution vendor, such as "Debian" or "RHEL" and does not display the actual image name. This is due to a limitation of the Linode API. .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.linode.list_nodes_min(call=None) Return a list of the VMs that are on the provider. Only a list of VM names and their state is returned. This is the minimum amount of information needed to check for existing VMs. .sp New in version 2015.8.0. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-f list_nodes_min my\-linode\-config salt\-cloud \-\-function list_nodes_min my\-linode\-config .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.linode.list_nodes_select(call=None) Return a list of the VMs that are on the provider, with select fields. .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.linode.reboot(name, call=None) Reboot a linode. .sp New in version 2015.8.0. .INDENT 7.0 .TP .B name The name of the VM to reboot. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-a reboot vm_name .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.linode.show_instance(name, call=None) Displays details about a particular Linode VM. Either a name or a linode_id must be provided. .sp New in version 2015.8.0. .INDENT 7.0 .TP .B name The name of the VM for which to display details. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-a show_instance vm_name .ft P .fi .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 The \fBimage\fP label only displays information about the VM\(aqs distribution vendor, such as "Debian" or "RHEL" and does not display the actual image name. This is due to a limitation of the Linode API. .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.linode.show_pricing(kwargs=None, call=None) Show pricing for a particular profile. This is only an estimate, based on unofficial pricing sources. .sp New in version 2015.8.0. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-f show_pricing my\-linode\-config profile=my\-linode\-profile .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.linode.start(name, call=None) Start a VM in Linode. .INDENT 7.0 .TP .B name The name of the VM to start. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-a stop vm_name .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.linode.stop(name, call=None) Stop a VM in Linode. .INDENT 7.0 .TP .B name The name of the VM to stop. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-a stop vm_name .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.cloud.clouds.lxc .SS Install Salt on an LXC Container .sp New in version 2014.7.0. .sp Please read core config documentation\&. .INDENT 0.0 .TP .B salt.cloud.clouds.lxc.avail_images() .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.lxc.create(vm_, call=None) Create an lxc Container. This function is idempotent and will try to either provision or finish the provision of an lxc container. .sp NOTE: Most of the initialization code has been moved and merged with the lxc runner and lxc.init functions .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.lxc.destroy(vm_, call=None) Destroy a lxc container .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.lxc.get_configured_provider(vm_=None) Return the contextual provider of None if no configured one can be found. .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.lxc.get_provider(name) .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.lxc.list_nodes(conn=None, call=None) .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.lxc.list_nodes_full(conn=None, call=None) .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.lxc.list_nodes_select(call=None) Return a list of the VMs that are on the provider, with select fields .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.lxc.show_instance(name, call=None) Show the details from the provider concerning an instance .UNINDENT .SS salt.cloud.clouds.msazure .SS Azure Cloud Module .sp The Azure cloud module is used to control access to Microsoft Azure .INDENT 0.0 .TP .B depends .INDENT 7.0 .IP \(bu 2 \fI\%Microsoft Azure SDK for Python\fP >= 1.0.2 .IP \(bu 2 python\-requests, for Python < 2.7.9 .UNINDENT .TP .B configuration Required provider parameters: .INDENT 7.0 .IP \(bu 2 \fBapikey\fP .IP \(bu 2 \fBcertificate_path\fP .IP \(bu 2 \fBsubscription_id\fP .IP \(bu 2 \fBbackend\fP .UNINDENT .sp A Management Certificate (.pem and .crt files) must be created and the .pem file placed on the same machine that salt\-cloud is run from. Information on creating the pem file to use, and uploading the associated cer file can be found at: .sp \fI\%http://www.windowsazure.com/en\-us/develop/python/how\-to\-guides/service\-management/\fP .sp For users with Python < 2.7.9, \fBbackend\fP must currently be set to \fBrequests\fP\&. .UNINDENT .sp Example \fB/etc/salt/cloud.providers\fP or \fB/etc/salt/cloud.providers.d/azure.conf\fP configuration: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C my\-azure\-config: driver: azure subscription_id: 3287abc8\-f98a\-c678\-3bde\-326766fd3617 certificate_path: /etc/salt/azure.pem management_host: management.core.windows.net .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.msazure.add_input_endpoint(kwargs=None, conn=None, call=None) New in version 2015.8.0. .sp Add an input endpoint to the deployment. Please note that there may be a delay before the changes show up. .sp CLI Example: .INDENT 7.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 .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.msazure.add_management_certificate(kwargs=None, conn=None, call=None) New in version 2015.8.0. .sp Add a new management certificate .sp CLI Example: .INDENT 7.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 .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.msazure.add_service_certificate(kwargs=None, conn=None, call=None) New in version 2015.8.0. .sp Add a new service certificate .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-f add_service_certificate my\-azure name=my_service_certificate \e data=\(aq...CERT_DATA...\(aq certificate_format=sha1 password=verybadpass .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.msazure.avail_images(conn=None, call=None) List available images for Azure .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.msazure.avail_locations(conn=None, call=None) List available locations for Azure .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.msazure.avail_sizes(call=None) Return a list of sizes from Azure .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.msazure.cleanup_unattached_disks(kwargs=None, conn=None, call=None) New in version 2015.8.0. .sp Cleans up all disks associated with the account, which are not attached. \fB* CAUTION *\fP This is a destructive function with no undo button, and no "Are you sure?" confirmation! .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-f cleanup_unattached_disks my\-azure name=my_disk salt\-cloud \-f cleanup_unattached_disks my\-azure name=my_disk delete_vhd=True .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.msazure.create(vm_) Create a single VM from a data dict .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.msazure.create_affinity_group(kwargs=None, conn=None, call=None) New in version 2015.8.0. .sp Create a new affinity group .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-f create_affinity_group my\-azure name=my_affinity_group .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.msazure.create_attach_volumes(name, kwargs, call=None, wait_to_finish=True) Create and attach volumes to created node .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.msazure.create_service(kwargs=None, conn=None, call=None) New in version 2015.8.0. .sp Create a new hosted service .sp CLI Example: .INDENT 7.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 .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.msazure.create_storage(kwargs=None, conn=None, call=None) New in version 2015.8.0. .sp Create a new storage account .sp CLI Example: .INDENT 7.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 .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.msazure.create_storage_container(kwargs=None, storage_conn=None, call=None) New in version 2015.8.0. .sp Create a storage container .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-f create_storage_container my\-azure name=mycontainer .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .TP .B name: Name of container to create. .TP .B meta_name_values: Optional. A dict with name_value pairs to associate with the container as metadata. Example:{\(aqCategory\(aq:\(aqtest\(aq} .TP .B blob_public_access: Optional. Possible values include: container, blob .TP .B fail_on_exist: Specify whether to throw an exception when the container exists. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.msazure.delete_affinity_group(kwargs=None, conn=None, call=None) New in version 2015.8.0. .sp Delete a specific affinity group associated with the account .sp CLI Examples: .INDENT 7.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 .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.msazure.delete_disk(kwargs=None, conn=None, call=None) New in version 2015.8.0. .sp Delete a specific disk associated with the account .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-f delete_disk my\-azure name=my_disk salt\-cloud \-f delete_disk my\-azure name=my_disk delete_vhd=True .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.msazure.delete_input_endpoint(kwargs=None, conn=None, call=None) New in version 2015.8.0. .sp Delete an input endpoint from the deployment. Please note that there may be a delay before the changes show up. .sp CLI Example: .INDENT 7.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 .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.msazure.delete_management_certificate(kwargs=None, conn=None, call=None) New in version 2015.8.0. .sp Delete a specific certificate associated with the management .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-f delete_management_certificate my\-azure name=my_management_certificate \e thumbalgorithm=sha1 thumbprint=0123456789ABCDEF .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.msazure.delete_service(kwargs=None, conn=None, call=None) New in version 2015.8.0. .sp Delete a specific service associated with the account .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-f delete_service my\-azure name=my_service .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.msazure.delete_service_certificate(kwargs=None, conn=None, call=None) New in version 2015.8.0. .sp Delete a specific certificate associated with the service .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-f delete_service_certificate my\-azure name=my_service_certificate \e thumbalgorithm=sha1 thumbprint=0123456789ABCDEF .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.msazure.delete_storage(kwargs=None, conn=None, call=None) New in version 2015.8.0. .sp Delete a specific storage account .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-f delete_storage my\-azure name=my_storage .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.msazure.delete_storage_container(kwargs=None, storage_conn=None, call=None) New in version 2015.8.0. .sp Delete a container associated with the storage account .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-f delete_storage_container my\-azure name=mycontainer .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .TP .B name: Name of container to create. .TP .B fail_not_exist: Specify whether to throw an exception when the container exists. .TP .B lease_id: If specified, delete_storage_container only succeeds if the container\(aqs lease is active and matches this ID. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.msazure.destroy(name, conn=None, call=None, kwargs=None) Destroy a VM .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-d myminion salt\-cloud \-a destroy myminion service_name=myservice .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.msazure.get_affinity_group(kwargs=None, conn=None, call=None) New in version 2015.8.0. .sp Show an affinity group associated with the account .sp CLI Example: .INDENT 7.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 .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.msazure.get_blob(kwargs=None, storage_conn=None, call=None) New in version 2015.8.0. .sp Download a blob .sp CLI Example: .INDENT 7.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 .INDENT 7.0 .TP .B container: Name of existing container. .TP .B name: Name of existing blob. .TP .B local_path: The path on the local machine to download the blob to. Either this or return_content must be specified. .TP .B return_content: 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. .TP .B snapshot: Optional. The snapshot parameter is an opaque DateTime value that, when present, specifies the blob snapshot to retrieve. .TP .B lease_id: Required if the blob has an active lease. .TP .B progress_callback: 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. .TP .B max_connections: 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. .TP .B max_retries: Number of times to retry download of blob chunk if an error occurs. .TP .B retry_wait: Sleep time in secs between retries. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.msazure.get_blob_properties(kwargs=None, storage_conn=None, call=None) New in version 2015.8.0. .sp Returns all user\-defined metadata, standard HTTP properties, and system properties for the blob. .sp CLI Example: .INDENT 7.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 .INDENT 7.0 .TP .B container: Name of existing container. .TP .B blob: Name of existing blob. .TP .B lease_id: Required if the blob has an active lease. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.msazure.get_blob_service_properties(kwargs=None, storage_conn=None, call=None) New in version 2015.8.0. .sp Show a blob\(aqs service properties .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-f show_blob_service_properties my\-azure .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.msazure.get_configured_provider() Return the first configured instance. .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.msazure.get_conn() Return a conn object for the passed VM data .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.msazure.get_dependencies() Warn if dependencies aren\(aqt met. .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.msazure.get_deployment(kwargs=None, conn=None, call=None) New in version 2015.8.0. .sp Return information about a deployment .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-f show_deployment my\-azure name=my_deployment .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.msazure.get_disk(kwargs=None, conn=None, call=None) New in version 2015.8.0. .sp Return information about a disk .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-f show_disk my\-azure name=my_disk .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.msazure.get_input_endpoint(kwargs=None, conn=None, call=None) New in version 2015.8.0. .sp Show an input endpoint associated with the deployment .sp CLI Example: .INDENT 7.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 .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.msazure.get_management_certificate(kwargs=None, conn=None, call=None) New in version 2015.8.0. .sp Return information about a management_certificate .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-f get_management_certificate my\-azure name=my_management_certificate \e thumbalgorithm=sha1 thumbprint=0123456789ABCDEF .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.msazure.get_operation_status(kwargs=None, conn=None, call=None) New in version 2015.8.0. .sp Get Operation Status, based on a request ID .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-f get_operation_status my\-azure id=0123456789abcdef0123456789abcdef .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.msazure.get_service_certificate(kwargs=None, conn=None, call=None) New in version 2015.8.0. .sp Return information about a service certificate .sp CLI Example: .INDENT 7.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 .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.msazure.get_storage(kwargs=None, conn=None, call=None) New in version 2015.8.0. .sp List storage service properties .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-f show_storage my\-azure name=my_storage .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.msazure.get_storage_conn(storage_account=None, storage_key=None, conn_kwargs=None) New in version 2015.8.0. .sp Return a storage_conn object for the storage account .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.msazure.get_storage_container(kwargs=None, storage_conn=None, call=None) New in version 2015.8.0. .sp Show a container associated with the storage account .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-f show_storage_container my\-azure name=myservice .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .TP .B name: Name of container to show. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.msazure.get_storage_container_acl(kwargs=None, storage_conn=None, call=None) New in version 2015.8.0. .sp Show a storage container\(aqs acl .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-f show_storage_container_acl my\-azure name=myservice .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .TP .B name: Name of existing container. .TP .B lease_id: If specified, show_storage_container_acl only succeeds if the container\(aqs lease is active and matches this ID. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.msazure.get_storage_container_metadata(kwargs=None, storage_conn=None, call=None) New in version 2015.8.0. .sp Show a storage container\(aqs metadata .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-f show_storage_container_metadata my\-azure name=myservice .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .TP .B name: Name of container to show. .TP .B lease_id: If specified, show_storage_container_metadata only succeeds if the container\(aqs lease is active and matches this ID. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.msazure.get_storage_keys(kwargs=None, conn=None, call=None) New in version 2015.8.0. .sp Show storage account keys .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-f show_storage_keys my\-azure name=my_storage .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.msazure.lease_storage_container(kwargs=None, storage_conn=None, call=None) New in version 2015.8.0. .sp Lease a container associated with the storage account .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-f lease_storage_container my\-azure name=mycontainer .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .TP .B name: Name of container to create. .TP .B lease_action: Required. Possible values: acquire|renew|release|break|change .TP .B lease_id: Required if the container has an active lease. .TP .B lease_duration: 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. .TP .B lease_break_period: 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. .TP .B proposed_lease_id: Optional for acquire, required for change. Proposed lease ID, in a GUID string format. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.msazure.list_affinity_groups(kwargs=None, conn=None, call=None) New in version 2015.8.0. .sp List input endpoints associated with the deployment .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-f list_affinity_groups my\-azure .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.msazure.list_blobs(kwargs=None, storage_conn=None, call=None) New in version 2015.8.0. .sp List blobs associated with the container .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-f list_blobs my\-azure container=mycontainer .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .TP .B container: The name of the storage container .TP .B prefix: Optional. Filters the results to return only blobs whose names begin with the specified prefix. .TP .B marker: 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. .TP .B maxresults: 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). .TP .B include: 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 7.0 .TP .B snapshots: Specifies that snapshots should be included in the enumeration. Snapshots are listed from oldest to newest in the response. .TP .B metadata: Specifies that blob metadata be returned in the response. .TP .B 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. .TP .B 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. .UNINDENT .TP .B delimiter: 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. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.msazure.list_disks(kwargs=None, conn=None, call=None) New in version 2015.8.0. .sp List disks associated with the account .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-f list_disks my\-azure .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.msazure.list_hosted_services(conn=None, call=None) List VMs on this Azure account, with full information .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.msazure.list_input_endpoints(kwargs=None, conn=None, call=None) New in version 2015.8.0. .sp List input endpoints associated with the deployment .sp CLI Example: .INDENT 7.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 .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.msazure.list_management_certificates(kwargs=None, conn=None, call=None) New in version 2015.8.0. .sp List management certificates associated with the subscription .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-f list_management_certificates my\-azure name=my_management .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.msazure.list_nodes(conn=None, call=None) List VMs on this Azure account .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.msazure.list_nodes_full(conn=None, call=None) List VMs on this Azure account, with full information .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.msazure.list_nodes_select(conn=None, call=None) Return a list of the VMs that are on the provider, with select fields .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.msazure.list_service_certificates(kwargs=None, conn=None, call=None) New in version 2015.8.0. .sp List certificates associated with the service .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-f list_service_certificates my\-azure name=my_service .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.msazure.list_services(kwargs=None, conn=None, call=None) New in version 2015.8.0. .sp List hosted services associated with the account .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-f list_services my\-azure .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.msazure.list_storage(kwargs=None, conn=None, call=None) New in version 2015.8.0. .sp List storage accounts associated with the account .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-f list_storage my\-azure .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.msazure.list_storage_containers(kwargs=None, storage_conn=None, call=None) New in version 2015.8.0. .sp List containers associated with the storage account .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-f list_storage_containers my\-azure .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.msazure.list_storage_services(conn=None, call=None) List VMs on this Azure account, with full information .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.msazure.list_virtual_networks(kwargs=None, conn=None, call=None) New in version 2015.8.0. .sp List input endpoints associated with the deployment .sp CLI Example: .INDENT 7.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 .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.msazure.make_blob_url(kwargs=None, storage_conn=None, call=None) New in version 2015.8.0. .sp Creates the URL to access a blob .sp CLI Example: .INDENT 7.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 .INDENT 7.0 .TP .B container: Name of the container. .TP .B blob: Name of the blob. .TP .B account: Name of the storage account. If not specified, derives the host base from the provider configuration. .TP .B protocol: Protocol to use: \(aqhttp\(aq or \(aqhttps\(aq. If not specified, derives the host base from the provider configuration. .TP .B host_base: Live host base URL. If not specified, derives the host base from the provider configuration. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.msazure.put_blob(kwargs=None, storage_conn=None, call=None) New in version 2015.8.0. .sp Upload a blob .sp CLI Examples: .INDENT 7.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 .INDENT 7.0 .TP .B container: Name of existing container. .TP .B name: Name of existing blob. .TP .B blob_path: The path on the local machine of the file to upload as a blob. Either this or blob_content must be specified. .TP .B blob_content: The actual content to be uploaded as a blob. Either this or blob_path must me specified. .TP .B cache_control: Optional. The Blob service stores this value but does not use or modify it. .TP .B content_language: Optional. Specifies the natural languages used by this resource. .TP .B content_md5: 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). .TP .B blob_content_type: Optional. Set the blob\(aqs content type. .TP .B blob_content_encoding: Optional. Set the blob\(aqs content encoding. .TP .B blob_content_language: Optional. Set the blob\(aqs content language. .TP .B blob_content_md5: Optional. Set the blob\(aqs MD5 hash. .TP .B blob_cache_control: Optional. Sets the blob\(aqs cache control. .TP .B meta_name_values: A dict containing name, value for metadata. .TP .B lease_id: Required if the blob has an active lease. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.msazure.query(path, method=\(aqGET\(aq, data=None, params=None, header_dict=None, decode=True) Perform a query directly against the Azure REST API .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.msazure.regenerate_storage_keys(kwargs=None, conn=None, call=None) New in version 2015.8.0. .sp Regenerate storage account keys. Requires a key_type ("primary" or "secondary") to be specified. .sp CLI Example: .INDENT 7.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 .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.msazure.script(vm_) Return the script deployment object .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.msazure.set_blob_properties(kwargs=None, storage_conn=None, call=None) New in version 2015.8.0. .sp Set a blob\(aqs properties .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-f set_blob_properties my\-azure .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .TP .B container: Name of existing container. .TP .B blob: Name of existing blob. .TP .B blob_cache_control: Optional. Modifies the cache control string for the blob. .TP .B blob_content_type: Optional. Sets the blob\(aqs content type. .TP .B blob_content_md5: Optional. Sets the blob\(aqs MD5 hash. .TP .B blob_content_encoding: Optional. Sets the blob\(aqs content encoding. .TP .B blob_content_language: Optional. Sets the blob\(aqs content language. .TP .B lease_id: Required if the blob has an active lease. .TP .B blob_content_disposition: 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. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.msazure.set_blob_service_properties(kwargs=None, storage_conn=None, call=None) New in version 2015.8.0. .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. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-f set_blob_service_properties my\-azure .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .TP .B properties: a StorageServiceProperties object. .TP .B timeout: Optional. The timeout parameter is expressed in seconds. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.msazure.set_storage_container_acl(kwargs=None, storage_conn=None, call=None) New in version 2015.8.0. .sp Set a storage container\(aqs acl .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-f set_storage_container my\-azure name=mycontainer .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .TP .B name: Name of existing container. .TP .B signed_identifiers: SignedIdentifers instance .TP .B blob_public_access: Optional. Possible values include: container, blob .TP .B lease_id: If specified, set_storage_container_acl only succeeds if the container\(aqs lease is active and matches this ID. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.msazure.set_storage_container_metadata(kwargs=None, storage_conn=None, call=None) New in version 2015.8.0. .sp Set a storage container\(aqs metadata .sp CLI Example: .INDENT 7.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 .INDENT 7.0 .TP .B name: Name of existing container. .TP .B meta_name_values: A dict containing name, value for metadata. Example: {\(aqcategory\(aq:\(aqtest\(aq} .TP .B lease_id: If specified, set_storage_container_metadata only succeeds if the container\(aqs lease is active and matches this ID. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.msazure.show_affinity_group(kwargs=None, conn=None, call=None) New in version 2015.8.0. .sp Show an affinity group associated with the account .sp CLI Example: .INDENT 7.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 .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.msazure.show_blob_properties(kwargs=None, storage_conn=None, call=None) New in version 2015.8.0. .sp Returns all user\-defined metadata, standard HTTP properties, and system properties for the blob. .sp CLI Example: .INDENT 7.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 .INDENT 7.0 .TP .B container: Name of existing container. .TP .B blob: Name of existing blob. .TP .B lease_id: Required if the blob has an active lease. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.msazure.show_blob_service_properties(kwargs=None, storage_conn=None, call=None) New in version 2015.8.0. .sp Show a blob\(aqs service properties .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-f show_blob_service_properties my\-azure .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.msazure.show_deployment(kwargs=None, conn=None, call=None) New in version 2015.8.0. .sp Return information about a deployment .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-f show_deployment my\-azure name=my_deployment .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.msazure.show_disk(kwargs=None, conn=None, call=None) New in version 2015.8.0. .sp Return information about a disk .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-f show_disk my\-azure name=my_disk .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.msazure.show_input_endpoint(kwargs=None, conn=None, call=None) New in version 2015.8.0. .sp Show an input endpoint associated with the deployment .sp CLI Example: .INDENT 7.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 .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.msazure.show_instance(name, call=None) Show the details from the provider concerning an instance .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.msazure.show_management_certificate(kwargs=None, conn=None, call=None) New in version 2015.8.0. .sp Return information about a management_certificate .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-f get_management_certificate my\-azure name=my_management_certificate \e thumbalgorithm=sha1 thumbprint=0123456789ABCDEF .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.msazure.show_service(kwargs=None, conn=None, call=None) New in version 2015.8.0. .sp List hosted service properties .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-f show_service my\-azure name=my_service .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.msazure.show_service_certificate(kwargs=None, conn=None, call=None) New in version 2015.8.0. .sp Return information about a service certificate .sp CLI Example: .INDENT 7.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 .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.msazure.show_storage(kwargs=None, conn=None, call=None) New in version 2015.8.0. .sp List storage service properties .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-f show_storage my\-azure name=my_storage .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.msazure.show_storage_container(kwargs=None, storage_conn=None, call=None) New in version 2015.8.0. .sp Show a container associated with the storage account .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-f show_storage_container my\-azure name=myservice .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .TP .B name: Name of container to show. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.msazure.show_storage_container_acl(kwargs=None, storage_conn=None, call=None) New in version 2015.8.0. .sp Show a storage container\(aqs acl .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-f show_storage_container_acl my\-azure name=myservice .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .TP .B name: Name of existing container. .TP .B lease_id: If specified, show_storage_container_acl only succeeds if the container\(aqs lease is active and matches this ID. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.msazure.show_storage_container_metadata(kwargs=None, storage_conn=None, call=None) New in version 2015.8.0. .sp Show a storage container\(aqs metadata .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-f show_storage_container_metadata my\-azure name=myservice .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .TP .B name: Name of container to show. .TP .B lease_id: If specified, show_storage_container_metadata only succeeds if the container\(aqs lease is active and matches this ID. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.msazure.show_storage_keys(kwargs=None, conn=None, call=None) New in version 2015.8.0. .sp Show storage account keys .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-f show_storage_keys my\-azure name=my_storage .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.msazure.update_affinity_group(kwargs=None, conn=None, call=None) New in version 2015.8.0. .sp Update an affinity group\(aqs properties .sp CLI Example: .INDENT 7.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 .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.msazure.update_disk(kwargs=None, conn=None, call=None) New in version 2015.8.0. .sp Update a disk\(aqs properties .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-f update_disk my\-azure name=my_disk label=my_disk salt\-cloud \-f update_disk my\-azure name=my_disk new_name=another_disk .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.msazure.update_input_endpoint(kwargs=None, conn=None, call=None, activity=\(aqupdate\(aq) New in version 2015.8.0. .sp Update an input endpoint associated with the deployment. Please note that there may be a delay before the changes show up. .sp CLI Example: .INDENT 7.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 .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.msazure.update_storage(kwargs=None, conn=None, call=None) New in version 2015.8.0. .sp Update a storage account\(aqs properties .sp CLI Example: .INDENT 7.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 .UNINDENT .SS salt.cloud.clouds.oneandone .SS 1&1 Cloud Server Module .sp The 1&1 SaltStack cloud module allows a 1&1 server to be automatically deployed and bootstrapped with Salt. It also has functions to create block storages and ssh keys. .INDENT 0.0 .TP .B depends 1and1 >= 1.2.0 .UNINDENT .sp The module requires the 1&1 api_token to be provided. The server should also be assigned a public LAN, a private LAN, or both along with SSH key pairs. .sp Set up the cloud configuration at \fB/etc/salt/cloud.providers\fP or \fB/etc/salt/cloud.providers.d/oneandone.conf\fP: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C my\-oneandone\-config: driver: oneandone # The 1&1 api token api_token: # SSH private key filename ssh_private_key: /path/to/private_key # SSH public key filename ssh_public_key: /path/to/public_key .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C my\-oneandone\-profile: provider: my\-oneandone\-config # Either provide fixed_instance_size_id or vcore, cores_per_processor, ram, and hdds. # Size of the ID desired for the server fixed_instance_size: S # Total amount of processors vcore: 2 # Number of cores per processor cores_per_processor: 2 # RAM memory size in GB ram: 4 # Hard disks hdds: \- is_main: true size: 20 \- is_main: false size: 20 # ID of the appliance image that will be installed on server appliance_id: # ID of the datacenter where the server will be created datacenter_id: # Description of the server description: My server description # Password of the server. Password must contain more than 8 characters # using uppercase letters, numbers and other special symbols. password: P4$$w0rD # Power on server after creation \- default True power_on: true # Firewall policy ID. If it is not provided, the server will assign # the best firewall policy, creating a new one if necessary. # If the parameter is sent with a 0 value, the server will be created with all ports blocked. firewall_policy_id: # IP address ID ip_id: # Load balancer ID load_balancer_id: # Monitoring policy ID monitoring_policy_id: .ft P .fi .UNINDENT .UNINDENT .sp Set \fBdeploy\fP to False if Salt should not be installed on the node. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C my\-oneandone\-profile: deploy: False .ft P .fi .UNINDENT .UNINDENT .sp Create an SSH key .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C sudo salt\-cloud \-f create_ssh_key my\-oneandone\-config name=\(aqSaltTest\(aq description=\(aqSaltTestDescription\(aq .ft P .fi .UNINDENT .UNINDENT .sp Create a block storage .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C sudo salt\-cloud \-f create_block_storage my\-oneandone\-config name=\(aqSaltTest2\(aq description=\(aqSaltTestDescription\(aq size=50 datacenter_id=\(aq5091F6D8CBFEF9C26ACE957C652D5D49\(aq .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.oneandone.avail_images(conn=None, call=None) Return a list of the server appliances that are on the provider .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.oneandone.avail_locations(conn=None, call=None) List available locations/datacenters for 1&1 .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.oneandone.avail_sizes(call=None) Return a dict of all available VM sizes on the cloud provider with relevant data. .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.oneandone.create(vm_) Create a single VM from a data dict .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.oneandone.create_block_storage(kwargs=None, call=None) Create a block storage .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.oneandone.create_ssh_key(kwargs=None, call=None) Create an ssh key .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.oneandone.destroy(name, call=None) destroy a server by name .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBname\fP \-\- name given to the server .IP \(bu 2 \fBcall\fP \-\- call value in this case is \(aqaction\(aq .UNINDENT .TP .B Returns array of booleans , true if successfully stopped and true if successfully removed .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-d vm_name .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.oneandone.get_configured_provider() Return the first configured instance. .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.oneandone.get_conn() Return a conn object for the passed VM data .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.oneandone.get_dependencies() Warn if dependencies are not met. .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.oneandone.get_image(vm_) Return the image object to use .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.oneandone.get_key_filename(vm_) Check SSH private key file and return absolute path if exists. .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.oneandone.get_node(conn, name) Return a node for the named VM .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.oneandone.get_size(vm_) Return the VM\(aqs size object .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.oneandone.get_wait_timeout(vm_) Return the wait_for_timeout for resource provisioning. .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.oneandone.list_nodes(conn=None, call=None) Return a list of VMs that are on the provider .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.oneandone.list_nodes_full(conn=None, call=None) Return a list of the VMs that are on the provider, with all fields .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.oneandone.list_nodes_select(conn=None, call=None) Return a list of the VMs that are on the provider, with select fields .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.oneandone.load_public_key(vm_) Load the public key file if exists. .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.oneandone.reboot(name, call=None) reboot a server by name :param name: name given to the machine :param call: call value in this case is \(aqaction\(aq :return: true if successful .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-a reboot vm_name .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.oneandone.script(vm_) Return the script deployment object .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.oneandone.show_instance(name, call=None) Show the details from the provider concerning an instance .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.oneandone.start(name, call=None) start a server by name :param name: name given to the machine :param call: call value in this case is \(aqaction\(aq :return: true if successful .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-a start vm_name .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.oneandone.stop(name, call=None) stop a server by name :param name: name given to the machine :param call: call value in this case is \(aqaction\(aq :return: true if successful .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-a stop vm_name .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.cloud.clouds.opennebula .SS OpenNebula Cloud Module .sp The OpenNebula cloud module is used to control access to an OpenNebula cloud. .sp New in version 2014.7.0. .INDENT 0.0 .TP .B depends lxml .TP .B depends OpenNebula installation running version \fB4.14\fP or later. .UNINDENT .sp Use of this module requires the \fBxml_rpc\fP, \fBuser\fP, and \fBpassword\fP parameters to be set. .sp Set up the cloud configuration at \fB/etc/salt/cloud.providers\fP or \fB/etc/salt/cloud.providers.d/opennebula.conf\fP: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C my\-opennebula\-config: xml_rpc: http://localhost:2633/RPC2 user: oneadmin password: JHGhgsayu32jsa driver: opennebula .ft P .fi .UNINDENT .UNINDENT .sp This driver supports accessing new VM instances via DNS entry instead of IP address. To enable this feature, in the provider or profile file add \fIfqdn_base\fP with a value matching the base of your fully\-qualified domain name. Example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C my\-opennebula\-config: [...] fqdn_base: [...] .ft P .fi .UNINDENT .UNINDENT .sp The driver will prepend the hostname to the fqdn_base and do a DNS lookup to find the IP of the new VM. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-f image_allocate opennebula datastore_name=default \e data=\(aqNAME="My New Image" DESCRIPTION="Description of the image." \e PATH=/home/one_user/images/image_name.img\(aq salt\-cloud \-f secgroup_allocate opennebula \e data="Name = test RULE = [PROTOCOL = TCP, RULE_TYPE = inbound, \e RANGE = 1000:2000]" .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.opennebula.avail_images(call=None) Return available OpenNebula images. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-\-list\-images opennebula salt\-cloud \-\-function avail_images opennebula salt\-cloud \-f avail_images opennebula .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.opennebula.avail_locations(call=None) Return available OpenNebula locations. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-\-list\-locations opennebula salt\-cloud \-\-function avail_locations opennebula salt\-cloud \-f avail_locations opennebula .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.opennebula.avail_sizes(call=None) Because sizes are built into templates with OpenNebula, there will be no sizes to return here. .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.opennebula.create(vm_) Create a single VM from a data dict. .INDENT 7.0 .TP .B vm_ The dictionary use to create a VM. .UNINDENT .sp Optional vm_ dict options for overwriting template: .INDENT 7.0 .TP .B region_id Optional \- OpenNebula Zone ID .TP .B memory Optional \- In MB .TP .B cpu Optional \- Percent of host CPU to allocate .TP .B vcpu .INDENT 7.0 .INDENT 3.5 Optional \- Amount of vCPUs to allocate .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-p my\-opennebula\-profile vm_name salt\-cloud \-p my\-opennebula\-profile vm_name memory=16384 cpu=2.5 vcpu=16 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.opennebula.destroy(name, call=None) Destroy a node. Will check termination protection and warn if enabled. .INDENT 7.0 .TP .B name The name of the vm to be destroyed. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-\-destroy vm_name salt\-cloud \-d vm_name salt\-cloud \-\-action destroy vm_name salt\-cloud \-a destroy vm_name .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.opennebula.get_cluster_id(kwargs=None, call=None) Returns a cluster\(aqs ID from the given cluster name. .sp New in version 2016.3.0. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-f get_cluster_id opennebula name=my\-cluster\-name .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.opennebula.get_configured_provider() Return the first configured instance. .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.opennebula.get_datastore_id(kwargs=None, call=None) Returns a data store\(aqs ID from the given data store name. .sp New in version 2016.3.0. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-f get_datastore_id opennebula name=my\-datastore\-name .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.opennebula.get_dependencies() Warn if dependencies aren\(aqt met. .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.opennebula.get_host_id(kwargs=None, call=None) Returns a host\(aqs ID from the given host name. .sp New in version 2016.3.0. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-f get_host_id opennebula name=my\-host\-name .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.opennebula.get_image(vm_) Return the image object to use. .INDENT 7.0 .TP .B vm_ The VM dictionary for which to obtain an image. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.opennebula.get_image_id(kwargs=None, call=None) Returns an image\(aqs ID from the given image name. .sp New in version 2016.3.0. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-f get_image_id opennebula name=my\-image\-name .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.opennebula.get_location(vm_) Return the VM\(aqs location. .INDENT 7.0 .TP .B vm_ The VM dictionary for which to obtain a location. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.opennebula.get_one_version(kwargs=None, call=None) Returns the OpenNebula version. .sp New in version 2016.3.5. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-f get_one_version one_provider_name .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.opennebula.get_secgroup_id(kwargs=None, call=None) Returns a security group\(aqs ID from the given security group name. .sp New in version 2016.3.0. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-f get_secgroup_id opennebula name=my\-secgroup\-name .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.opennebula.get_template(vm_) Return the template id for a VM. .sp New in version 2016.11.0. .INDENT 7.0 .TP .B vm_ The VM dictionary for which to obtain a template. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.opennebula.get_template_id(kwargs=None, call=None) Returns a template\(aqs ID from the given template name. .sp New in version 2016.3.0. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-f get_template_id opennebula name=my\-template\-name .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.opennebula.get_template_image(kwargs=None, call=None) Returns a template\(aqs image from the given template name. .sp New in version 2018.3.0. .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-f get_template_image opennebula name=my\-template\-name .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.opennebula.get_vm_id(kwargs=None, call=None) Returns a virtual machine\(aqs ID from the given virtual machine\(aqs name. .sp New in version 2016.3.0. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-f get_vm_id opennebula name=my\-vm .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.opennebula.get_vn_id(kwargs=None, call=None) Returns a virtual network\(aqs ID from the given virtual network\(aqs name. .sp New in version 2016.3.0. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-f get_vn_id opennebula name=my\-vn\-name .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.opennebula.image_allocate(call=None, kwargs=None) Allocates a new image in OpenNebula. .sp New in version 2016.3.0. .INDENT 7.0 .TP .B path The path to a file containing the template of the image to allocate. Syntax within the file can be the usual attribute=value or XML. Can be used instead of \fBdata\fP\&. .TP .B data The data containing the template of the image to allocate. Syntax can be the usual attribute=value or XML. Can be used instead of \fBpath\fP\&. .TP .B datastore_id The ID of the data\-store to be used for the new image. Can be used instead of \fBdatastore_name\fP\&. .TP .B datastore_name The name of the data\-store to be used for the new image. Can be used instead of \fBdatastore_id\fP\&. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-f image_allocate opennebula path=/path/to/image_file.txt datastore_id=1 salt\-cloud \-f image_allocate opennebula datastore_name=default \e data=\(aqNAME="Ubuntu 14.04" PATH="/home/one_user/images/ubuntu_desktop.img" \e DESCRIPTION="Ubuntu 14.04 for development."\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.opennebula.image_clone(call=None, kwargs=None) Clones an existing image. .sp New in version 2016.3.0. .INDENT 7.0 .TP .B name The name of the new image. .TP .B image_id The ID of the image to be cloned. Can be used instead of \fBimage_name\fP\&. .TP .B image_name The name of the image to be cloned. Can be used instead of \fBimage_id\fP\&. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-f image_clone opennebula name=my\-new\-image image_id=10 salt\-cloud \-f image_clone opennebula name=my\-new\-image image_name=my\-image\-to\-clone .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.opennebula.image_delete(call=None, kwargs=None) Deletes the given image from OpenNebula. Either a name or an image_id must be supplied. .sp New in version 2016.3.0. .INDENT 7.0 .TP .B name The name of the image to delete. Can be used instead of \fBimage_id\fP\&. .TP .B image_id The ID of the image to delete. Can be used instead of \fBname\fP\&. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-f image_delete opennebula name=my\-image salt\-cloud \-\-function image_delete opennebula image_id=100 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.opennebula.image_info(call=None, kwargs=None) Retrieves information for a given image. Either a name or an image_id must be supplied. .sp New in version 2016.3.0. .INDENT 7.0 .TP .B name The name of the image for which to gather information. Can be used instead of \fBimage_id\fP\&. .TP .B image_id The ID of the image for which to gather information. Can be used instead of \fBname\fP\&. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-f image_info opennebula name=my\-image salt\-cloud \-\-function image_info opennebula image_id=5 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.opennebula.image_persistent(call=None, kwargs=None) Sets the Image as persistent or not persistent. .sp New in version 2016.3.0. .INDENT 7.0 .TP .B name The name of the image to set. Can be used instead of \fBimage_id\fP\&. .TP .B image_id The ID of the image to set. Can be used instead of \fBname\fP\&. .TP .B persist A boolean value to set the image as persistent or not. Set to true for persistent, false for non\-persistent. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-f image_persistent opennebula name=my\-image persist=True salt\-cloud \-\-function image_persistent opennebula image_id=5 persist=False .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.opennebula.image_snapshot_delete(call=None, kwargs=None) Deletes a snapshot from the image. .sp New in version 2016.3.0. .INDENT 7.0 .TP .B image_id The ID of the image from which to delete the snapshot. Can be used instead of \fBimage_name\fP\&. .TP .B image_name The name of the image from which to delete the snapshot. Can be used instead of \fBimage_id\fP\&. .TP .B snapshot_id The ID of the snapshot to delete. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-f image_snapshot_delete vm_id=106 snapshot_id=45 salt\-cloud \-f image_snapshot_delete vm_name=my\-vm snapshot_id=111 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.opennebula.image_snapshot_flatten(call=None, kwargs=None) Flattens the snapshot of an image and discards others. .sp New in version 2016.3.0. .INDENT 7.0 .TP .B image_id The ID of the image. Can be used instead of \fBimage_name\fP\&. .TP .B image_name The name of the image. Can be used instead of \fBimage_id\fP\&. .TP .B snapshot_id The ID of the snapshot to flatten. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-f image_snapshot_flatten vm_id=106 snapshot_id=45 salt\-cloud \-f image_snapshot_flatten vm_name=my\-vm snapshot_id=45 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.opennebula.image_snapshot_revert(call=None, kwargs=None) Reverts an image state to a previous snapshot. .sp New in version 2016.3.0. .INDENT 7.0 .TP .B image_id The ID of the image to revert. Can be used instead of \fBimage_name\fP\&. .TP .B image_name The name of the image to revert. Can be used instead of \fBimage_id\fP\&. .TP .B snapshot_id The ID of the snapshot to which the image will be reverted. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-f image_snapshot_revert vm_id=106 snapshot_id=45 salt\-cloud \-f image_snapshot_revert vm_name=my\-vm snapshot_id=120 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.opennebula.image_update(call=None, kwargs=None) Replaces the image template contents. .sp New in version 2016.3.0. .INDENT 7.0 .TP .B image_id The ID of the image to update. Can be used instead of \fBimage_name\fP\&. .TP .B image_name The name of the image to update. Can be used instead of \fBimage_id\fP\&. .TP .B path The path to a file containing the template of the image. Syntax within the file can be the usual attribute=value or XML. Can be used instead of \fBdata\fP\&. .TP .B data Contains the template of the image. Syntax can be the usual attribute=value or XML. Can be used instead of \fBpath\fP\&. .TP .B update_type There are two ways to update an image: \fBreplace\fP the whole template or \fBmerge\fP the new template with the existing one. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-f image_update opennebula image_id=0 file=/path/to/image_update_file.txt update_type=replace salt\-cloud \-f image_update opennebula image_name="Ubuntu 14.04" update_type=merge \e data=\(aqNAME="Ubuntu Dev" PATH="/home/one_user/images/ubuntu_desktop.img" \e DESCRIPTION = "Ubuntu 14.04 for development."\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.opennebula.list_clusters(call=None) Returns a list of clusters in OpenNebula. .sp New in version 2016.3.0. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-f list_clusters opennebula .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.opennebula.list_datastores(call=None) Returns a list of data stores on OpenNebula. .sp New in version 2016.3.0. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-f list_datastores opennebula .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.opennebula.list_hosts(call=None) Returns a list of hosts on OpenNebula. .sp New in version 2016.3.0. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-f list_hosts opennebula .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.opennebula.list_nodes(call=None) Return a list of VMs on OpenNebula. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-Q salt\-cloud \-\-query salt\-cloud \-\-function list_nodes opennebula salt\-cloud \-f list_nodes opennebula .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.opennebula.list_nodes_full(call=None) Return a list of the VMs on OpenNebula. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-F salt\-cloud \-\-full\-query salt\-cloud \-\-function list_nodes_full opennebula salt\-cloud \-f list_nodes_full opennebula .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.opennebula.list_nodes_select(call=None) Return a list of the VMs that are on the provider, with select fields. .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.opennebula.list_security_groups(call=None) Lists all security groups available to the user and the user\(aqs groups. .sp New in version 2016.3.0. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-f list_security_groups opennebula .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.opennebula.list_templates(call=None) Lists all templates available to the user and the user\(aqs groups. .sp New in version 2016.3.0. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-f list_templates opennebula .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.opennebula.list_vns(call=None) Lists all virtual networks available to the user and the user\(aqs groups. .sp New in version 2016.3.0. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-f list_vns opennebula .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.opennebula.reboot(name, call=None) Reboot a VM. .sp New in version 2016.3.0. .INDENT 7.0 .TP .B name The name of the VM to reboot. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-a reboot my\-vm .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.opennebula.secgroup_allocate(call=None, kwargs=None) Allocates a new security group in OpenNebula. .sp New in version 2016.3.0. .INDENT 7.0 .TP .B path The path to a file containing the template of the security group. Syntax within the file can be the usual attribute=value or XML. Can be used instead of \fBdata\fP\&. .TP .B data The template data of the security group. Syntax can be the usual attribute=value or XML. Can be used instead of \fBpath\fP\&. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-f secgroup_allocate opennebula path=/path/to/secgroup_file.txt salt\-cloud \-f secgroup_allocate opennebula \e data="NAME = test RULE = [PROTOCOL = TCP, RULE_TYPE = inbound, \e RANGE = 1000:2000]" .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.opennebula.secgroup_clone(call=None, kwargs=None) Clones an existing security group. .sp New in version 2016.3.0. .INDENT 7.0 .TP .B name The name of the new template. .TP .B secgroup_id The ID of the security group to be cloned. Can be used instead of \fBsecgroup_name\fP\&. .TP .B secgroup_name The name of the security group to be cloned. Can be used instead of \fBsecgroup_id\fP\&. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-f secgroup_clone opennebula name=my\-cloned\-secgroup secgroup_id=0 salt\-cloud \-f secgroup_clone opennebula name=my\-cloned\-secgroup secgroup_name=my\-secgroup .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.opennebula.secgroup_delete(call=None, kwargs=None) Deletes the given security group from OpenNebula. Either a name or a secgroup_id must be supplied. .sp New in version 2016.3.0. .INDENT 7.0 .TP .B name The name of the security group to delete. Can be used instead of \fBsecgroup_id\fP\&. .TP .B secgroup_id The ID of the security group to delete. Can be used instead of \fBname\fP\&. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-f secgroup_delete opennebula name=my\-secgroup salt\-cloud \-\-function secgroup_delete opennebula secgroup_id=100 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.opennebula.secgroup_info(call=None, kwargs=None) Retrieves information for the given security group. Either a name or a secgroup_id must be supplied. .sp New in version 2016.3.0. .INDENT 7.0 .TP .B name The name of the security group for which to gather information. Can be used instead of \fBsecgroup_id\fP\&. .TP .B secgroup_id The ID of the security group for which to gather information. Can be used instead of \fBname\fP\&. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-f secgroup_info opennebula name=my\-secgroup salt\-cloud \-\-function secgroup_info opennebula secgroup_id=5 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.opennebula.secgroup_update(call=None, kwargs=None) Replaces the security group template contents. .sp New in version 2016.3.0. .INDENT 7.0 .TP .B secgroup_id The ID of the security group to update. Can be used instead of \fBsecgroup_name\fP\&. .TP .B secgroup_name The name of the security group to update. Can be used instead of \fBsecgroup_id\fP\&. .TP .B path The path to a file containing the template of the security group. Syntax within the file can be the usual attribute=value or XML. Can be used instead of \fBdata\fP\&. .TP .B data The template data of the security group. Syntax can be the usual attribute=value or XML. Can be used instead of \fBpath\fP\&. .TP .B update_type There are two ways to update a security group: \fBreplace\fP the whole template or \fBmerge\fP the new template with the existing one. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-\-function secgroup_update opennebula secgroup_id=100 \e path=/path/to/secgroup_update_file.txt \e update_type=replace salt\-cloud \-f secgroup_update opennebula secgroup_name=my\-secgroup update_type=merge \e data="Name = test RULE = [PROTOCOL = TCP, RULE_TYPE = inbound, RANGE = 1000:2000]" .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.opennebula.show_instance(name, call=None) Show the details from OpenNebula concerning a named VM. .INDENT 7.0 .TP .B name The name of the VM for which to display details. .TP .B call Type of call to use with this function such as \fBfunction\fP\&. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-\-action show_instance vm_name salt\-cloud \-a show_instance vm_name .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.opennebula.start(name, call=None) Start a VM. .sp New in version 2016.3.0. .INDENT 7.0 .TP .B name The name of the VM to start. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-a start my\-vm .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.opennebula.stop(name, call=None) Stop a VM. .sp New in version 2016.3.0. .INDENT 7.0 .TP .B name The name of the VM to stop. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-a stop my\-vm .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.opennebula.template_allocate(call=None, kwargs=None) Allocates a new template in OpenNebula. .sp New in version 2016.3.0. .INDENT 7.0 .TP .B path The path to a file containing the elements of the template to be allocated. Syntax within the file can be the usual attribute=value or XML. Can be used instead of \fBdata\fP\&. .TP .B data Contains the elements of the template to be allocated. Syntax can be the usual attribute=value or XML. Can be used instead of \fBpath\fP\&. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-f template_allocate opennebula path=/path/to/template_file.txt salt\-cloud \-f template_allocate opennebula \e data=\(aqCPU="1.0" DISK=[IMAGE="Ubuntu\-14.04"] GRAPHICS=[LISTEN="0.0.0.0",TYPE="vnc"] \e MEMORY="1024" NETWORK="yes" NIC=[NETWORK="192net",NETWORK_UNAME="oneadmin"] \e OS=[ARCH="x86_64"] SUNSTONE_CAPACITY_SELECT="YES" SUNSTONE_NETWORK_SELECT="YES" \e VCPU="1"\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.opennebula.template_clone(call=None, kwargs=None) Clones an existing virtual machine template. .sp New in version 2016.3.0. .INDENT 7.0 .TP .B name The name of the new template. .TP .B template_id The ID of the template to be cloned. Can be used instead of \fBtemplate_name\fP\&. .TP .B template_name The name of the template to be cloned. Can be used instead of \fBtemplate_id\fP\&. .TP .B clone_images Optional, defaults to False. Indicates if the images attached to the template should be cloned as well. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-f template_clone opennebula name=my\-new\-template template_id=0 salt\-cloud \-f template_clone opennebula name=my\-new\-template template_name=my\-template .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.opennebula.template_delete(call=None, kwargs=None) Deletes the given template from OpenNebula. Either a name or a template_id must be supplied. .sp New in version 2016.3.0. .INDENT 7.0 .TP .B name The name of the template to delete. Can be used instead of \fBtemplate_id\fP\&. .TP .B template_id The ID of the template to delete. Can be used instead of \fBname\fP\&. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-f template_delete opennebula name=my\-template salt\-cloud \-\-function template_delete opennebula template_id=5 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.opennebula.template_instantiate(call=None, kwargs=None) Instantiates a new virtual machine from a template. .sp New in version 2016.3.0. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 \fBtemplate_instantiate\fP creates a VM on OpenNebula from a template, but it does not install Salt on the new VM. Use the \fBcreate\fP function for that functionality: \fBsalt\-cloud \-p opennebula\-profile vm\-name\fP\&. .UNINDENT .UNINDENT .INDENT 7.0 .TP .B vm_name Name for the new VM instance. .TP .B template_id The ID of the template from which the VM will be created. Can be used instead of \fBtemplate_name\fP\&. .TP .B template_name The name of the template from which the VM will be created. Can be used instead of \fBtemplate_id\fP\&. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-f template_instantiate opennebula vm_name=my\-new\-vm template_id=0 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.opennebula.template_update(call=None, kwargs=None) Replaces the template contents. .sp New in version 2016.3.0. .INDENT 7.0 .TP .B template_id The ID of the template to update. Can be used instead of \fBtemplate_name\fP\&. .TP .B template_name The name of the template to update. Can be used instead of \fBtemplate_id\fP\&. .TP .B path The path to a file containing the elements of the template to be updated. Syntax within the file can be the usual attribute=value or XML. Can be used instead of \fBdata\fP\&. .TP .B data Contains the elements of the template to be updated. Syntax can be the usual attribute=value or XML. Can be used instead of \fBpath\fP\&. .TP .B update_type There are two ways to update a template: \fBreplace\fP the whole template or \fBmerge\fP the new template with the existing one. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-\-function template_update opennebula template_id=1 update_type=replace \e path=/path/to/template_update_file.txt salt\-cloud \-f template_update opennebula template_name=my\-template update_type=merge \e data=\(aqCPU="1.0" DISK=[IMAGE="Ubuntu\-14.04"] GRAPHICS=[LISTEN="0.0.0.0",TYPE="vnc"] \e MEMORY="1024" NETWORK="yes" NIC=[NETWORK="192net",NETWORK_UNAME="oneadmin"] \e OS=[ARCH="x86_64"] SUNSTONE_CAPACITY_SELECT="YES" SUNSTONE_NETWORK_SELECT="YES" \e VCPU="1"\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.opennebula.vm_action(name, kwargs=None, call=None) Submits an action to be performed on a given virtual machine. .sp New in version 2016.3.0. .INDENT 7.0 .TP .B name The name of the VM to action. .TP .B action .INDENT 7.0 .TP .B The action to be performed on the VM. Available options include: .INDENT 7.0 .IP \(bu 2 boot .IP \(bu 2 delete .IP \(bu 2 delete\-recreate .IP \(bu 2 hold .IP \(bu 2 poweroff .IP \(bu 2 poweroff\-hard .IP \(bu 2 reboot .IP \(bu 2 reboot\-hard .IP \(bu 2 release .IP \(bu 2 resched .IP \(bu 2 resume .IP \(bu 2 shutdown .IP \(bu 2 shutdown\-hard .IP \(bu 2 stop .IP \(bu 2 suspend .IP \(bu 2 undeploy .IP \(bu 2 undeploy\-hard .IP \(bu 2 unresched .UNINDENT .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-a vm_action my\-vm action=\(aqrelease\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.opennebula.vm_allocate(call=None, kwargs=None) Allocates a new virtual machine in OpenNebula. .sp New in version 2016.3.0. .INDENT 7.0 .TP .B path The path to a file defining the template of the VM to allocate. Syntax within the file can be the usual attribute=value or XML. Can be used instead of \fBdata\fP\&. .TP .B data Contains the template definitions of the VM to allocate. Syntax can be the usual attribute=value or XML. Can be used instead of \fBpath\fP\&. .TP .B hold If this parameter is set to \fBTrue\fP, the VM will be created in the \fBHOLD\fP state. If not set, the VM is created in the \fBPENDING\fP state. Default is \fBFalse\fP\&. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-f vm_allocate path=/path/to/vm_template.txt salt\-cloud \-\-function vm_allocate path=/path/to/vm_template.txt hold=True .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.opennebula.vm_attach(name, kwargs=None, call=None) Attaches a new disk to the given virtual machine. .sp New in version 2016.3.0. .INDENT 7.0 .TP .B name The name of the VM for which to attach the new disk. .TP .B path The path to a file containing a single disk vector attribute. Syntax within the file can be the usual attribute=value or XML. Can be used instead of \fBdata\fP\&. .TP .B data Contains the data needed to attach a single disk vector attribute. Syntax can be the usual attribute=value or XML. Can be used instead of \fBpath\fP\&. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-a vm_attach my\-vm path=/path/to/disk_file.txt salt\-cloud \-a vm_attach my\-vm data="DISK=[DISK_ID=1]" .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.opennebula.vm_attach_nic(name, kwargs=None, call=None) Attaches a new network interface to the given virtual machine. .sp New in version 2016.3.0. .INDENT 7.0 .TP .B name The name of the VM for which to attach the new network interface. .TP .B path The path to a file containing a single NIC vector attribute. Syntax within the file can be the usual attribute=value or XML. Can be used instead of \fBdata\fP\&. .TP .B data Contains the single NIC vector attribute to attach to the VM. Syntax can be the usual attribute=value or XML. Can be used instead of \fBpath\fP\&. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-a vm_attach_nic my\-vm path=/path/to/nic_file.txt salt\-cloud \-a vm_attach_nic my\-vm data="NIC=[NETWORK_ID=1]" .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.opennebula.vm_deploy(name, kwargs=None, call=None) Initiates the instance of the given VM on the target host. .sp New in version 2016.3.0. .INDENT 7.0 .TP .B name The name of the VM to deploy. .TP .B host_id The ID of the target host where the VM will be deployed. Can be used instead of \fBhost_name\fP\&. .TP .B host_name The name of the target host where the VM will be deployed. Can be used instead of \fBhost_id\fP\&. .TP .B capacity_maintained True to enforce the Host capacity is not over\-committed. This parameter is only acknowledged for users in the \fBoneadmin\fP group. Host capacity will be always enforced for regular users. .TP .B datastore_id The ID of the target system data\-store where the VM will be deployed. Optional and can be used instead of \fBdatastore_name\fP\&. If neither \fBdatastore_id\fP nor \fBdatastore_name\fP are set, OpenNebula will choose the data\-store. .TP .B datastore_name The name of the target system data\-store where the VM will be deployed. Optional, and can be used instead of \fBdatastore_id\fP\&. If neither \fBdatastore_id\fP nor \fBdatastore_name\fP are set, OpenNebula will choose the data\-store. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-a vm_deploy my\-vm host_id=0 salt\-cloud \-a vm_deploy my\-vm host_id=1 capacity_maintained=False salt\-cloud \-a vm_deploy my\-vm host_name=host01 datastore_id=1 salt\-cloud \-a vm_deploy my\-vm host_name=host01 datastore_name=default .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.opennebula.vm_detach(name, kwargs=None, call=None) Detaches a disk from a virtual machine. .sp New in version 2016.3.0. .INDENT 7.0 .TP .B name The name of the VM from which to detach the disk. .TP .B disk_id The ID of the disk to detach. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-a vm_detach my\-vm disk_id=1 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.opennebula.vm_detach_nic(name, kwargs=None, call=None) Detaches a disk from a virtual machine. .sp New in version 2016.3.0. .INDENT 7.0 .TP .B name The name of the VM from which to detach the network interface. .TP .B nic_id The ID of the nic to detach. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-a vm_detach_nic my\-vm nic_id=1 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.opennebula.vm_disk_save(name, kwargs=None, call=None) Sets the disk to be saved in the given image. .sp New in version 2016.3.0. .INDENT 7.0 .TP .B name The name of the VM containing the disk to save. .TP .B disk_id The ID of the disk to save. .TP .B image_name The name of the new image where the disk will be saved. .TP .B image_type The type for the new image. If not set, then the default \fBONED\fP Configuration will be used. Other valid types include: OS, CDROM, DATABLOCK, KERNEL, RAMDISK, and CONTEXT. .TP .B snapshot_id The ID of the snapshot to export. If not set, the current image state will be used. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-a vm_disk_save my\-vm disk_id=1 image_name=my\-new\-image salt\-cloud \-a vm_disk_save my\-vm disk_id=1 image_name=my\-new\-image image_type=CONTEXT snapshot_id=10 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.opennebula.vm_disk_snapshot_create(name, kwargs=None, call=None) Takes a new snapshot of the disk image. .sp New in version 2016.3.0. .INDENT 7.0 .TP .B name The name of the VM of which to take the snapshot. .TP .B disk_id The ID of the disk to save. .TP .B description The description for the snapshot. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-a vm_disk_snapshot_create my\-vm disk_id=0 description="My Snapshot Description" .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.opennebula.vm_disk_snapshot_delete(name, kwargs=None, call=None) Deletes a disk snapshot based on the given VM and the disk_id. .sp New in version 2016.3.0. .INDENT 7.0 .TP .B name The name of the VM containing the snapshot to delete. .TP .B disk_id The ID of the disk to save. .TP .B snapshot_id The ID of the snapshot to be deleted. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-a vm_disk_snapshot_delete my\-vm disk_id=0 snapshot_id=6 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.opennebula.vm_disk_snapshot_revert(name, kwargs=None, call=None) Reverts a disk state to a previously taken snapshot. .sp New in version 2016.3.0. .INDENT 7.0 .TP .B name The name of the VM containing the snapshot. .TP .B disk_id The ID of the disk to revert its state. .TP .B snapshot_id The ID of the snapshot to which the snapshot should be reverted. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-a vm_disk_snapshot_revert my\-vm disk_id=0 snapshot_id=6 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.opennebula.vm_info(name, call=None) Retrieves information for a given virtual machine. A VM name must be supplied. .sp New in version 2016.3.0. .INDENT 7.0 .TP .B name The name of the VM for which to gather information. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-a vm_info my\-vm .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.opennebula.vm_migrate(name, kwargs=None, call=None) Migrates the specified virtual machine to the specified target host. .sp New in version 2016.3.0. .INDENT 7.0 .TP .B name The name of the VM to migrate. .TP .B host_id The ID of the host to which the VM will be migrated. Can be used instead of \fBhost_name\fP\&. .TP .B host_name The name of the host to which the VM will be migrated. Can be used instead of \fBhost_id\fP\&. .TP .B live_migration If set to \fBTrue\fP, a live\-migration will be performed. Default is \fBFalse\fP\&. .TP .B capacity_maintained True to enforce the Host capacity is not over\-committed. This parameter is only acknowledged for users in the \fBoneadmin\fP group. Host capacity will be always enforced for regular users. .TP .B datastore_id The target system data\-store ID where the VM will be migrated. Can be used instead of \fBdatastore_name\fP\&. .TP .B datastore_name The name of the data\-store target system where the VM will be migrated. Can be used instead of \fBdatastore_id\fP\&. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-a vm_migrate my\-vm host_id=0 datastore_id=1 salt\-cloud \-a vm_migrate my\-vm host_id=0 datastore_id=1 live_migration=True salt\-cloud \-a vm_migrate my\-vm host_name=host01 datastore_name=default .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.opennebula.vm_monitoring(name, call=None) Returns the monitoring records for a given virtual machine. A VM name must be supplied. .sp The monitoring information returned is a list of VM elements. Each VM element contains the complete dictionary of the VM with the updated information returned by the poll action. .sp New in version 2016.3.0. .INDENT 7.0 .TP .B name The name of the VM for which to gather monitoring records. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-a vm_monitoring my\-vm .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.opennebula.vm_resize(name, kwargs=None, call=None) Changes the capacity of the virtual machine. .sp New in version 2016.3.0. .INDENT 7.0 .TP .B name The name of the VM to resize. .TP .B path The path to a file containing new capacity elements CPU, VCPU, MEMORY. If one of them is not present, or its value is 0, the VM will not be re\-sized. Syntax within the file can be the usual attribute=value or XML. Can be used instead of \fBdata\fP\&. .TP .B data Contains the new capacity elements CPU, VCPU, and MEMORY. If one of them is not present, or its value is 0, the VM will not be re\-sized. Can be used instead of \fBpath\fP\&. .TP .B capacity_maintained True to enforce the Host capacity is not over\-committed. This parameter is only acknowledged for users in the \fBoneadmin\fP group. Host capacity will be always enforced for regular users. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-a vm_resize my\-vm path=/path/to/capacity_template.txt salt\-cloud \-a vm_resize my\-vm path=/path/to/capacity_template.txt capacity_maintained=False salt\-cloud \-a vm_resize my\-vm data="CPU=1 VCPU=1 MEMORY=1024" .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.opennebula.vm_snapshot_create(vm_name, kwargs=None, call=None) Creates a new virtual machine snapshot from the provided VM. .sp New in version 2016.3.0. .INDENT 7.0 .TP .B vm_name The name of the VM from which to create the snapshot. .TP .B snapshot_name The name of the snapshot to be created. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-a vm_snapshot_create my\-vm snapshot_name=my\-new\-snapshot .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.opennebula.vm_snapshot_delete(vm_name, kwargs=None, call=None) Deletes a virtual machine snapshot from the provided VM. .sp New in version 2016.3.0. .INDENT 7.0 .TP .B vm_name The name of the VM from which to delete the snapshot. .TP .B snapshot_id The ID of the snapshot to be deleted. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-a vm_snapshot_delete my\-vm snapshot_id=8 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.opennebula.vm_snapshot_revert(vm_name, kwargs=None, call=None) Reverts a virtual machine to a snapshot .sp New in version 2016.3.0. .INDENT 7.0 .TP .B vm_name The name of the VM to revert. .TP .B snapshot_id The snapshot ID. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-a vm_snapshot_revert my\-vm snapshot_id=42 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.opennebula.vm_update(name, kwargs=None, call=None) Replaces the user template contents. .sp New in version 2016.3.0. .INDENT 7.0 .TP .B name The name of the VM to update. .TP .B path The path to a file containing new user template contents. Syntax within the file can be the usual attribute=value or XML. Can be used instead of \fBdata\fP\&. .TP .B data Contains the new user template contents. Syntax can be the usual attribute=value or XML. Can be used instead of \fBpath\fP\&. .TP .B update_type There are two ways to update a VM: \fBreplace\fP the whole template or \fBmerge\fP the new template with the existing one. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-a vm_update my\-vm path=/path/to/user_template_file.txt update_type=\(aqreplace\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.opennebula.vn_add_ar(call=None, kwargs=None) Adds address ranges to a given virtual network. .sp New in version 2016.3.0. .INDENT 7.0 .TP .B vn_id The ID of the virtual network to add the address range. Can be used instead of \fBvn_name\fP\&. .TP .B vn_name The name of the virtual network to add the address range. Can be used instead of \fBvn_id\fP\&. .TP .B path The path to a file containing the template of the address range to add. Syntax within the file can be the usual attribute=value or XML. Can be used instead of \fBdata\fP\&. .TP .B data Contains the template of the address range to add. Syntax can be the usual attribute=value or XML. Can be used instead of \fBpath\fP\&. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-f vn_add_ar opennebula vn_id=3 path=/path/to/address_range.txt salt\-cloud \-f vn_add_ar opennebula vn_name=my\-vn \e data="AR=[TYPE=IP4, IP=192.168.0.5, SIZE=10]" .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.opennebula.vn_allocate(call=None, kwargs=None) Allocates a new virtual network in OpenNebula. .sp New in version 2016.3.0. .INDENT 7.0 .TP .B path The path to a file containing the template of the virtual network to allocate. Syntax within the file can be the usual attribute=value or XML. Can be used instead of \fBdata\fP\&. .TP .B data Contains the template of the virtual network to allocate. Syntax can be the usual attribute=value or XML. Can be used instead of \fBpath\fP\&. .TP .B cluster_id The ID of the cluster for which to add the new virtual network. Can be used instead of \fBcluster_name\fP\&. If neither \fBcluster_id\fP nor \fBcluster_name\fP are provided, the virtual network won’t be added to any cluster. .TP .B cluster_name The name of the cluster for which to add the new virtual network. Can be used instead of \fBcluster_id\fP\&. If neither \fBcluster_name\fP nor \fBcluster_id\fP are provided, the virtual network won\(aqt be added to any cluster. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-f vn_allocate opennebula path=/path/to/vn_file.txt .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.opennebula.vn_delete(call=None, kwargs=None) Deletes the given virtual network from OpenNebula. Either a name or a vn_id must be supplied. .sp New in version 2016.3.0. .INDENT 7.0 .TP .B name The name of the virtual network to delete. Can be used instead of \fBvn_id\fP\&. .TP .B vn_id The ID of the virtual network to delete. Can be used instead of \fBname\fP\&. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-f vn_delete opennebula name=my\-virtual\-network salt\-cloud \-\-function vn_delete opennebula vn_id=3 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.opennebula.vn_free_ar(call=None, kwargs=None) Frees a reserved address range from a virtual network. .sp New in version 2016.3.0. .INDENT 7.0 .TP .B vn_id The ID of the virtual network from which to free an address range. Can be used instead of \fBvn_name\fP\&. .TP .B vn_name The name of the virtual network from which to free an address range. Can be used instead of \fBvn_id\fP\&. .TP .B ar_id The ID of the address range to free. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-f vn_free_ar opennebula vn_id=3 ar_id=1 salt\-cloud \-f vn_free_ar opennebula vn_name=my\-vn ar_id=1 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.opennebula.vn_hold(call=None, kwargs=None) Holds a virtual network lease as used. .sp New in version 2016.3.0. .INDENT 7.0 .TP .B vn_id The ID of the virtual network from which to hold the lease. Can be used instead of \fBvn_name\fP\&. .TP .B vn_name The name of the virtual network from which to hold the lease. Can be used instead of \fBvn_id\fP\&. .TP .B path The path to a file defining the template of the lease to hold. Syntax within the file can be the usual attribute=value or XML. Can be used instead of \fBdata\fP\&. .TP .B data Contains the template of the lease to hold. Syntax can be the usual attribute=value or XML. Can be used instead of \fBpath\fP\&. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-f vn_hold opennebula vn_id=3 path=/path/to/vn_hold_file.txt salt\-cloud \-f vn_hold opennebula vn_name=my\-vn data="LEASES=[IP=192.168.0.5]" .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.opennebula.vn_info(call=None, kwargs=None) Retrieves information for the virtual network. .sp New in version 2016.3.0. .INDENT 7.0 .TP .B name The name of the virtual network for which to gather information. Can be used instead of \fBvn_id\fP\&. .TP .B vn_id The ID of the virtual network for which to gather information. Can be used instead of \fBname\fP\&. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-f vn_info opennebula vn_id=3 salt\-cloud \-\-function vn_info opennebula name=public .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.opennebula.vn_release(call=None, kwargs=None) Releases a virtual network lease that was previously on hold. .sp New in version 2016.3.0. .INDENT 7.0 .TP .B vn_id The ID of the virtual network from which to release the lease. Can be used instead of \fBvn_name\fP\&. .TP .B vn_name The name of the virtual network from which to release the lease. Can be used instead of \fBvn_id\fP\&. .TP .B path The path to a file defining the template of the lease to release. Syntax within the file can be the usual attribute=value or XML. Can be used instead of \fBdata\fP\&. .TP .B data Contains the template defining the lease to release. Syntax can be the usual attribute=value or XML. Can be used instead of \fBpath\fP\&. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-f vn_release opennebula vn_id=3 path=/path/to/vn_release_file.txt salt\-cloud =f vn_release opennebula vn_name=my\-vn data="LEASES=[IP=192.168.0.5]" .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.opennebula.vn_reserve(call=None, kwargs=None) Reserve network addresses. .sp New in version 2016.3.0. .INDENT 7.0 .TP .B vn_id The ID of the virtual network from which to reserve addresses. Can be used instead of vn_name. .TP .B vn_name The name of the virtual network from which to reserve addresses. Can be used instead of vn_id. .TP .B path The path to a file defining the template of the address reservation. Syntax within the file can be the usual attribute=value or XML. Can be used instead of \fBdata\fP\&. .TP .B data Contains the template defining the address reservation. Syntax can be the usual attribute=value or XML. Data provided must be wrapped in double quotes. Can be used instead of \fBpath\fP\&. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-f vn_reserve opennebula vn_id=3 path=/path/to/vn_reserve_file.txt salt\-cloud \-f vn_reserve opennebula vn_name=my\-vn data="SIZE=10 AR_ID=8 NETWORK_ID=1" .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.cloud.clouds.openstack .SS Openstack Cloud Driver .INDENT 0.0 .TP .B depends \fI\%shade>=1.19.0\fP .UNINDENT .sp OpenStack is an open source project that is in use by a number a cloud providers, each of which have their own ways of using it. .sp This OpenStack driver uses a the shade python module which is managed by the OpenStack Infra team. This module is written to handle all the different versions of different OpenStack tools for salt, so most commands are just passed over to the module to handle everything. .SS Provider .sp There are two ways to configure providers for this driver. The first one is to just let shade handle everything, and configure using \fI\%os\-client\-config\fP and setting up \fI/etc/openstack/clouds.yml\fP\&. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C clouds: democloud: region_name: RegionOne auth: username: \(aqdemo\(aq password: secret project_name: \(aqdemo\(aq auth_url: \(aqhttp://openstack/identity\(aq .ft P .fi .UNINDENT .UNINDENT .sp And then this can be referenced in the salt provider based on the \fIdemocloud\fP name. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C myopenstack: driver: openstack cloud: democloud region_name: RegionOne .ft P .fi .UNINDENT .UNINDENT .sp This allows for just using one configuration for salt\-cloud and for any other openstack tools which are all using \fI/etc/openstack/clouds.yml\fP .sp The other method allows for specifying everything in the provider config, instead of using the extra configuration file. This will allow for passing salt\-cloud configs only through pillars for minions without having to write a clouds.yml file on each minion.abs .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C myopenstack: driver: openstack region_name: RegionOne auth: username: \(aqdemo\(aq password: secret project_name: \(aqdemo\(aq user_domain_name: default, project_domain_name: default, auth_url: \(aqhttp://openstack/identity\(aq .ft P .fi .UNINDENT .UNINDENT .sp Or if you need to use a profile to setup some extra stuff, it can be passed as a \fIprofile\fP to use any of the \fI\%vendor\fP config options. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C myrackspace: driver: openstack profile: rackspace auth: username: rackusername api_key: myapikey region_name: ORD auth_type: rackspace_apikey .ft P .fi .UNINDENT .UNINDENT .sp And this will pull in the profile for rackspace and setup all the correct options for the auth_url and different api versions for services. .SS Profile .sp Most of the options for building servers are just passed on to the \fI\%create_server\fP function from shade. .sp The salt specific ones are: .INDENT 0.0 .INDENT 3.5 .INDENT 0.0 .IP \(bu 2 ssh_key_file: The path to the ssh key that should be used to login to the machine to bootstrap it .IP \(bu 2 ssh_key_file: The name of the keypair in openstack .IP \(bu 2 userdata_template: The renderer to use if the userdata is a file that is templated. Default: False .IP \(bu 2 ssh_interface: The interface to use to login for bootstrapping: public_ips, private_ips, floating_ips, fixed_ips .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C centos: provider: myopenstack image: CentOS 7 size: ds1G ssh_key_name: mykey ssh_key_file: /root/.ssh/id_rsa .ft P .fi .UNINDENT .UNINDENT .sp This is the minimum setup required. .sp If metadata is set to make sure that the host has finished setting up the \fIwait_for_metadata\fP can be set. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C centos: provider: myopenstack image: CentOS 7 size: ds1G ssh_key_name: mykey ssh_key_file: /root/.ssh/id_rsa meta: build_config: rack_user_only wait_for_metadata: rax_service_level_automation: Complete rackconnect_automation_status: DEPLOYED .ft P .fi .UNINDENT .UNINDENT .sp Anything else from the \fI\%create_server\fP docs can be passed through here. .INDENT 0.0 .IP \(bu 2 \fBimage\fP: Image dict, name or ID to boot with. image is required unless boot_volume is given. .IP \(bu 2 \fBflavor\fP: Flavor dict, name or ID to boot onto. .IP \(bu 2 \fBauto_ip\fP: Whether to take actions to find a routable IP for the server. (defaults to True) .IP \(bu 2 \fBips\fP: List of IPs to attach to the server (defaults to None) .IP \(bu 2 \fBip_pool\fP: Name of the network or floating IP pool to get an address from. (defaults to None) .IP \(bu 2 \fBroot_volume\fP: Name or ID of a volume to boot from (defaults to None \- deprecated, use boot_volume) .IP \(bu 2 \fBboot_volume\fP: Name or ID of a volume to boot from (defaults to None) .IP \(bu 2 \fBterminate_volume\fP: If booting from a volume, whether it should be deleted when the server is destroyed. (defaults to False) .IP \(bu 2 \fBvolumes\fP: (optional) A list of volumes to attach to the server .IP \(bu 2 \fBmeta\fP: (optional) A dict of arbitrary key/value metadata to store for this server. Both keys and values must be <=255 characters. .IP \(bu 2 \fBfiles\fP: (optional, deprecated) A dict of files to overwrite on the server upon boot. Keys are file names (i.e. \fB/etc/passwd\fP) and values are the file contents (either as a string or as a file\-like object). A maximum of five entries is allowed, and each file must be 10k or less. .IP \(bu 2 \fBreservation_id\fP: a UUID for the set of servers being requested. .IP \(bu 2 \fBmin_count\fP: (optional extension) The minimum number of servers to launch. .IP \(bu 2 \fBmax_count\fP: (optional extension) The maximum number of servers to launch. .IP \(bu 2 \fBsecurity_groups\fP: A list of security group names .IP \(bu 2 \fBuserdata\fP: user data to pass to be exposed by the metadata server this can be a file type object as well or a string. .IP \(bu 2 \fBkey_name\fP: (optional extension) name of previously created keypair to inject into the instance. .IP \(bu 2 \fBavailability_zone\fP: Name of the availability zone for instance placement. .IP \(bu 2 \fBblock_device_mapping\fP: (optional) A list of dictionaries representing legacy block device mappings for this server. See \fI\%documentation\fP for details. .IP \(bu 2 \fBblock_device_mapping_v2\fP: (optional) A list of dictionaries representing block device mappings for this server. See \fI\%v2 documentation\fP for details. .IP \(bu 2 \fBnics\fP: (optional extension) an ordered list of nics to be added to this server, with information about connected networks, fixed IPs, port etc. .IP \(bu 2 \fBscheduler_hints\fP: (optional extension) arbitrary key\-value pairs specified by the client to help boot an instance .IP \(bu 2 \fBconfig_drive\fP: (optional extension) value for config drive either boolean, or volume\-id .IP \(bu 2 \fBdisk_config\fP: (optional extension) control how the disk is partitioned when the server is created. possible values are \(aqAUTO\(aq or \(aqMANUAL\(aq. .IP \(bu 2 \fBadmin_pass\fP: (optional extension) add a user supplied admin password. .IP \(bu 2 \fBtimeout\fP: (optional) Seconds to wait, defaults to 60. See the \fBwait\fP parameter. .IP \(bu 2 \fBreuse_ips\fP: (optional) Whether to attempt to reuse pre\-existing floating ips should a floating IP be needed (defaults to True) .IP \(bu 2 \fBnetwork\fP: (optional) Network dict or name or ID to attach the server to. Mutually exclusive with the nics parameter. Can also be be a list of network names or IDs or network dicts. .IP \(bu 2 \fBboot_from_volume\fP: Whether to boot from volume. \(aqboot_volume\(aq implies True, but boot_from_volume=True with no boot_volume is valid and will create a volume from the image and use that. .IP \(bu 2 \fBvolume_size\fP: When booting an image from volume, how big should the created volume be? Defaults to 50. .IP \(bu 2 \fBnat_destination\fP: Which network should a created floating IP be attached to, if it\(aqs not possible to infer from the cloud\(aqs configuration. (Optional, defaults to None) .IP \(bu 2 \fBgroup\fP: ServerGroup dict, name or id to boot the server in. If a group is provided in both scheduler_hints and in the group param, the group param will win. (Optional, defaults to None) .UNINDENT .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 If there is anything added, that is not in this list, it can be added to an \fIextras\fP dictionary for the profile, and that will be to the create_server function. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.openstack.avail_images(conn=None, call=None) List available images for OpenStack .sp CLI Example .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-f avail_images myopenstack salt\-cloud \-\-list\-images myopenstack .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.openstack.avail_sizes(conn=None, call=None) List available sizes for OpenStack .sp CLI Example .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-f avail_sizes myopenstack salt\-cloud \-\-list\-sizes myopenstack .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.openstack.call(conn=None, call=None, kwargs=None) Call function from shade. .sp func .INDENT 7.0 .INDENT 3.5 function to call from shade.openstackcloud library .UNINDENT .UNINDENT .sp CLI Example .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-f call myopenstack func=list_images t sujksalt\-cloud \-f call myopenstack func=create_network name=mysubnet .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.openstack.create(vm_) Create a single VM from a data dict .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.openstack.destroy(name, conn=None, call=None) Delete a single VM .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.openstack.get_configured_provider() Return the first configured instance. .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.openstack.get_conn() Return a conn object for the passed VM data .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.openstack.get_dependencies() Warn if dependencies aren\(aqt met. .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.openstack.list_networks(conn=None, call=None) List networks for OpenStack .sp CLI Example .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-f list_networks myopenstack .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.openstack.list_nodes(conn=None, call=None) Return a list of VMs .sp CLI Example .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-f list_nodes myopenstack .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.openstack.list_nodes_full(conn=None, call=None) Return a list of VMs with all the information about them .sp CLI Example .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-f list_nodes_full myopenstack .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.openstack.list_nodes_min(conn=None, call=None) Return a list of VMs with minimal information .sp CLI Example .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-f list_nodes_min myopenstack .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.openstack.list_nodes_select(conn=None, call=None) Return a list of VMs with the fields from \fIquery.selection\fP .sp CLI Example .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-f list_nodes_full myopenstack .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.openstack.list_subnets(conn=None, call=None, kwargs=None) List subnets in a virtual network .INDENT 7.0 .TP .B network network to list subnets of .UNINDENT .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-f list_subnets myopenstack network=salt\-net .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.openstack.preferred_ip(vm_, ips) Return the preferred Internet protocol. Either \(aqipv4\(aq (default) or \(aqipv6\(aq. .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.openstack.request_instance(vm_, conn=None, call=None) Request an instance to be built .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.openstack.show_instance(name, conn=None, call=None) Get VM on this OpenStack account .sp name .INDENT 7.0 .INDENT 3.5 name of the instance .UNINDENT .UNINDENT .sp CLI Example .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-a show_instance myserver .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.openstack.ssh_interface(vm_) Return the ssh_interface type to connect to. Either \(aqpublic_ips\(aq (default) or \(aqprivate_ips\(aq. .UNINDENT .SS salt.cloud.clouds.packet .SS Packet Cloud Module Using Packet\(aqs Python API Client .sp The Packet cloud module is used to control access to the Packet VPS system. .sp Use of this module only requires the \fBtoken\fP parameter. .sp Set up the cloud configuration at \fB/etc/salt/cloud.providers\fP or \fB/etc/salt/cloud.providers.d/packet.conf\fP: .sp The Packet profile requires \fBsize\fP, \fBimage\fP, \fBlocation\fP, \fBproject_id\fP .sp Optional profile parameters: .INDENT 0.0 .IP \(bu 2 \fBstorage_size\fP \- min value is 10, defines Gigabytes of storage that will be attached to device. .IP \(bu 2 \fBstorage_tier\fP \- storage_1 \- Standard Plan, storage_2 \- Performance Plan .IP \(bu 2 \fBsnapshot_count\fP \- int .IP \(bu 2 \fBsnapshot_frequency\fP \- string \- possible values: .INDENT 2.0 .IP \(bu 2 1min .IP \(bu 2 15min .IP \(bu 2 1hour .IP \(bu 2 1day .IP \(bu 2 1week .IP \(bu 2 1month .IP \(bu 2 1year .UNINDENT .UNINDENT .sp This driver requires Packet\(aqs client library: \fI\%https://pypi.python.org/pypi/packet\-python\fP .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C packet\-provider: minion: master: 192.168.50.10 driver: packet token: ewr23rdf35wC8oNjJrhmHa87rjSXzJyi private_key: /root/.ssh/id_rsa packet\-profile: provider: packet\-provider size: baremetal_0 image: ubuntu_16_04_image location: ewr1 project_id: a64d000b\-d47c\-4d26\-9870\-46aac43010a6 storage_size: 10 storage_tier: storage_1 storage_snapshot_count: 1 storage_snapshot_frequency: 15min .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.packet.avail_images(call=None) Return available Packet os images. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-\-list\-images packet\-provider salt\-cloud \-f avail_images packet\-provider .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.packet.avail_locations(call=None) Return available Packet datacenter locations. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-\-list\-locations packet\-provider salt\-cloud \-f avail_locations packet\-provider .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.packet.avail_projects(call=None) Return available Packet projects. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-f avail_projects packet\-provider .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.packet.avail_sizes(call=None) Return available Packet sizes. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-\-list\-sizes packet\-provider salt\-cloud \-f avail_sizes packet\-provider .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.packet.create(vm_) Create a single Packet VM. .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.packet.destroy(name, call=None) Destroys a Packet device by name. .INDENT 7.0 .TP .B name The hostname of VM to be be destroyed. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-d name .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.packet.get_configured_provider() Return the first configured instance. .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.packet.get_devices_by_token() .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.packet.get_image(conn, vm_) Return the image object to use .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.packet.get_size(conn, vm_) Return the VM\(aqs size object .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.packet.is_profile_configured(vm_) .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.packet.list_nodes(call=None) Returns a list of devices, keeping only a brief listing. CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-Q salt\-cloud \-\-query salt\-cloud \-f list_nodes packet\-provider .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.packet.list_nodes_full(call=None) List devices, with all available information. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-F salt\-cloud \-\-full\-query salt\-cloud \-f list_nodes_full packet\-provider .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.packet.list_nodes_min(call=None) Return a list of the VMs that are on the provider. Only a list of VM names and their state is returned. This is the minimum amount of information needed to check for existing VMs. .sp New in version 2015.8.0. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-f list_nodes_min packet\-provider salt\-cloud \-\-function list_nodes_min packet\-provider .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.packet.list_nodes_select(call=None) Return a list of the VMs that are on the provider, with select fields. .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.packet.script(vm_) Return the script deployment object .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.packet.show_instance(name, call=None) Show the details from the provider concerning an instance .UNINDENT .SS salt.cloud.clouds.parallels .SS Parallels Cloud Module .sp The Parallels cloud module is used to control access to cloud providers using the Parallels VPS system. .INDENT 0.0 .TP .B 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: # Parallels account information user: myuser password: mypassword url: https://api.cloud.xmission.com:4465/paci/v1.0/ driver: parallels .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.parallels.avail_images(call=None) Return a list of the images that are on the provider .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.parallels.create(vm_) Create a single VM from a data dict .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.parallels.create_node(vm_) Build and submit the XML to create a node .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.parallels.destroy(name, call=None) Destroy a node. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-\-destroy mymachine .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.parallels.get_configured_provider() Return the first configured instance. .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.parallels.get_image(vm_) Return the image object to use .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.parallels.list_nodes(call=None) Return a list of the VMs that are on the provider .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.parallels.list_nodes_full(call=None) Return a list of the VMs that are on the provider .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.parallels.list_nodes_select(call=None) Return a list of the VMs that are on the provider, with select fields .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.parallels.query(action=None, command=None, args=None, method=\(aqGET\(aq, data=None) Make a web call to a Parallels provider .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.parallels.script(vm_) Return the script deployment object .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.parallels.show_image(kwargs, call=None) Show the details from Parallels concerning an image .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.parallels.show_instance(name, call=None) Show the details from Parallels concerning an instance .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.parallels.start(name, call=None) Start a node. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-a start mymachine .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.parallels.stop(name, call=None) Stop a node. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-a stop mymachine .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.parallels.wait_until(name, state, timeout=300) Wait until a specific state has been reached on a node .UNINDENT .SS salt.cloud.clouds.profitbricks .SS ProfitBricks Cloud Module .sp The ProfitBricks SaltStack cloud module allows a ProfitBricks server to be automatically deployed and bootstraped with Salt. .INDENT 0.0 .TP .B depends profitbrick >= 3.1.0 .UNINDENT .sp The module requires ProfitBricks credentials to be supplied along with an existing virtual datacenter UUID where the server resources will reside. The server should also be assigned a public LAN, a private LAN, or both along with SSH key pairs. \&... .sp Set up the cloud configuration at \fB/etc/salt/cloud.providers\fP or \fB/etc/salt/cloud.providers.d/profitbricks.conf\fP: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C my\-profitbricks\-config: driver: profitbricks # The ProfitBricks login username username: user@example.com # The ProfitBricks login password password: secretpassword # The ProfitBricks virtual datacenter UUID datacenter_id: # SSH private key filename ssh_private_key: /path/to/private.key # SSH public key filename ssh_public_key: /path/to/public.key .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C my\-profitbricks\-profile: provider: my\-profitbricks\-config # Name of a predefined server size. size: Micro Instance # Assign CPU family to server. cpu_family: INTEL_XEON # Number of CPU cores to allocate to node (overrides server size). cores: 4 # Amount of RAM in multiples of 256 MB (overrides server size). ram: 4096 # The server availability zone. availability_zone: ZONE_1 # Name or UUID of the HDD image to use. image: # Image alias could be provided instead of image. # Example \(aqubuntu:latest\(aq #image_alias: # Size of the node disk in GB (overrides server size). disk_size: 40 # Type of disk (HDD or SSD). disk_type: SSD # Storage availability zone to use. disk_availability_zone: ZONE_2 # Assign the server to the specified public LAN. public_lan: # Assign firewall rules to the network interface. public_firewall_rules: SSH: protocol: TCP port_range_start: 22 port_range_end: 22 # Assign the server to the specified private LAN. private_lan: # Enable NAT on the private NIC. nat: true # Assign additional volumes to the server. volumes: data\-volume: disk_size: 500 disk_availability_zone: ZONE_3 log\-volume: disk_size: 50 disk_type: SSD .ft P .fi .UNINDENT .UNINDENT .sp To use a private IP for connecting and bootstrapping node: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C my\-profitbricks\-profile: ssh_interface: private_lan .ft P .fi .UNINDENT .UNINDENT .sp Set \fBdeploy\fP to False if Salt should not be installed on the node. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C my\-profitbricks\-profile: deploy: False .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.profitbricks.avail_images(call=None) Return a list of the images that are on the provider .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.profitbricks.avail_locations(call=None) Return a dict of all available VM locations on the cloud provider with relevant data .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.profitbricks.avail_sizes(call=None) Return a dict of all available VM sizes on the cloud provider with relevant data. Latest version can be found at: .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.profitbricks.create(vm_) Create a single VM from a data dict .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.profitbricks.create_datacenter(call=None, kwargs=None) Creates a virtual datacenter based on supplied parameters. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-f create_datacenter profitbricks name=mydatacenter location=us/las description="my description" .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.profitbricks.create_loadbalancer(call=None, kwargs=None) Creates a loadbalancer within the datacenter from the provider config. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-f create_loadbalancer profitbricks name=mylb .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.profitbricks.destroy(name, call=None) destroy a machine by name .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBname\fP \-\- name given to the machine .IP \(bu 2 \fBcall\fP \-\- call value in this case is \(aqaction\(aq .UNINDENT .TP .B Returns array of booleans , true if successfully stopped and true if successfully removed .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-d vm_name .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.profitbricks.get_configured_provider() Return the first configured instance. .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.profitbricks.get_conn() Return a conn object for the passed VM data .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.profitbricks.get_datacenter(conn) Return the datacenter from the config provider datacenter ID .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.profitbricks.get_datacenter_id() Return datacenter ID from provider configuration .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.profitbricks.get_dependencies() Warn if dependencies are not met. .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.profitbricks.get_disk_type(vm_) Return the type of disk to use. Either \(aqHDD\(aq (default) or \(aqSSD\(aq. .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.profitbricks.get_image(vm_) Return the image object to use .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.profitbricks.get_key_filename(vm_) Check SSH private key file and return absolute path if exists. .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.profitbricks.get_node(conn, name) Return a node for the named VM .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.profitbricks.get_public_keys(vm_) Retrieve list of SSH public keys. .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.profitbricks.get_size(vm_) Return the VM\(aqs size object .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.profitbricks.get_wait_timeout(vm_) Return the wait_for_timeout for resource provisioning. .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.profitbricks.list_datacenters(conn=None, call=None) List all the data centers .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-f list_datacenters my\-profitbricks\-config .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.profitbricks.list_images(call=None, kwargs=None) List all the images with alias by location .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-f list_images my\-profitbricks\-config location=us/las .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.profitbricks.list_loadbalancers(call=None) Return a list of the loadbalancers that are on the provider .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.profitbricks.list_nodes(conn=None, call=None) Return a list of VMs that are on the provider .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.profitbricks.list_nodes_full(conn=None, call=None) Return a list of the VMs that are on the provider, with all fields .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.profitbricks.reboot(name, call=None) reboot a machine by name :param name: name given to the machine :param call: call value in this case is \(aqaction\(aq :return: true if successful .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-a reboot vm_name .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.profitbricks.reserve_ipblock(call=None, kwargs=None) Reserve the IP Block .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.profitbricks.set_public_lan(lan_id) Enables public Internet access for the specified public_lan. If no public LAN is available, then a new public LAN is created. .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.profitbricks.show_instance(name, call=None) Show the details from the provider concerning an instance .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.profitbricks.signal_event(vm_, event, description) .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.profitbricks.ssh_interface(vm_) Return the ssh_interface type to connect to. Either \(aqpublic_ips\(aq (default) or \(aqprivate_ips\(aq. .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.profitbricks.start(name, call=None) start a machine by name :param name: name given to the machine :param call: call value in this case is \(aqaction\(aq :return: true if successful .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-a start vm_name .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.profitbricks.stop(name, call=None) stop a machine by name :param name: name given to the machine :param call: call value in this case is \(aqaction\(aq :return: true if successful .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-a stop vm_name .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.profitbricks.version_compatible(version) Checks profitbricks version .UNINDENT .SS salt.cloud.clouds.proxmox .SS Proxmox Cloud Module .sp New in version 2014.7.0. .sp The Proxmox cloud module is used to control access to cloud providers using the Proxmox system (KVM / OpenVZ / LXC). .INDENT 0.0 .TP .B 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: # Proxmox account information user: myuser@pam or myuser@pve password: mypassword url: hypervisor.domain.tld port: 8006 driver: proxmox verify_ssl: True .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .TP .B maintainer Frank Klaassen <\fI\%frank@cloudright.nl\fP> .TP .B depends requests >= 2.2.1 .TP .B depends IPy >= 0.81 .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.proxmox.avail_images(call=None, location=\(aqlocal\(aq) Return a list of the images that are on the provider .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-\-list\-images my\-proxmox\-config .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.proxmox.avail_locations(call=None) Return a list of the hypervisors (nodes) which this Proxmox PVE machine manages .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-\-list\-locations my\-proxmox\-config .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.proxmox.create(vm_) Create a single VM from a data dict .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-p proxmox\-ubuntu vmhostname .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.proxmox.create_node(vm_, newid) Build and submit the requestdata to create a new node .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.proxmox.destroy(name, call=None) Destroy a node. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-\-destroy mymachine .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.proxmox.get_configured_provider() Return the first configured instance. .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.proxmox.get_dependencies() Warn if dependencies aren\(aqt met. .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.proxmox.get_resources_nodes(call=None, resFilter=None) Retrieve all hypervisors (nodes) available on this environment CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-f get_resources_nodes my\-proxmox\-config .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.proxmox.get_resources_vms(call=None, resFilter=None, includeConfig=True) Retrieve all VMs available on this environment .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-f get_resources_vms my\-proxmox\-config .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.proxmox.get_vm_status(vmid=None, name=None) Get the status for a VM, either via the ID or the hostname .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.proxmox.get_vmconfig(vmid, node=None, node_type=\(aqopenvz\(aq) Get VM configuration .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.proxmox.list_nodes(call=None) Return a list of the VMs that are managed by the provider .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-Q my\-proxmox\-config .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.proxmox.list_nodes_full(call=None) Return a list of the VMs that are on the provider .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-F my\-proxmox\-config .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.proxmox.list_nodes_select(call=None) Return a list of the VMs that are on the provider, with select fields .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-S my\-proxmox\-config .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.proxmox.query(conn_type, option, post_data=None) Execute the HTTP request to the API .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.proxmox.script(vm_) Return the script deployment object .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.proxmox.set_vm_status(status, name=None, vmid=None) Convenience function for setting VM status .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.proxmox.show_instance(name, call=None) Show the details from Proxmox concerning an instance .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.proxmox.shutdown(name=None, vmid=None, call=None) Shutdown a node via ACPI. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-a shutdown mymachine .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.proxmox.start(name, vmid=None, call=None) Start a node. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-a start mymachine .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.proxmox.stop(name, vmid=None, call=None) Stop a node ("pulling the plug"). .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-a stop mymachine .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.proxmox.wait_for_created(upid, timeout=300) Wait until a the vm has been created successfully .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.proxmox.wait_for_state(vmid, state, timeout=300) Wait until a specific state has been reached on a node .UNINDENT .SS salt.cloud.clouds.pyrax .SS Pyrax Cloud Module .sp PLEASE NOTE: This module is currently in early development, and considered to be experimental and unstable. It is not recommended for production use. Unless you are actively developing code in this module, you should use the OpenStack module instead. .INDENT 0.0 .TP .B salt.cloud.clouds.pyrax.get_configured_provider() Return the first configured instance. .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.pyrax.get_conn(conn_type) Return a conn object for the passed VM data .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.pyrax.get_dependencies() Warn if dependencies aren\(aqt met. .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.pyrax.queues_create(call, kwargs) .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.pyrax.queues_delete(call, kwargs) .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.pyrax.queues_exists(call, kwargs) .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.pyrax.queues_show(call, kwargs) .UNINDENT .SS salt.cloud.clouds.qingcloud .SS QingCloud Cloud Module .sp New in version 2015.8.0. .sp The QingCloud cloud module is used to control access to the QingCloud. \fI\%http://www.qingcloud.com/\fP .sp Use of this module requires the \fBaccess_key_id\fP, \fBsecret_access_key\fP, \fBzone\fP and \fBkey_filename\fP parameter to be set. .sp Set up the cloud configuration at \fB/etc/salt/cloud.providers\fP or \fB/etc/salt/cloud.providers.d/qingcloud.conf\fP: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C my\-qingcloud: driver: qingcloud access_key_id: AKIDMRTGYONNLTFFRBQJ secret_access_key: clYwH21U5UOmcov4aNV2V2XocaHCG3JZGcxEczFu zone: pek2 key_filename: /path/to/your.pem .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .TP .B depends requests .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.qingcloud.avail_images(kwargs=None, call=None) Return a list of the images that are on the provider. .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-\-list\-images my\-qingcloud salt\-cloud \-f avail_images my\-qingcloud zone=gd1 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.qingcloud.avail_locations(call=None) Return a dict of all available locations on the provider with relevant data. .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-\-list\-locations my\-qingcloud .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.qingcloud.avail_sizes(kwargs=None, call=None) Return a list of the instance sizes that are on the provider. .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-\-list\-sizes my\-qingcloud salt\-cloud \-f avail_sizes my\-qingcloud zone=pek2 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.qingcloud.create(vm_) Create a single instance from a data dict. .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-p qingcloud\-ubuntu\-c1m1 hostname1 salt\-cloud \-m /path/to/mymap.sls \-P .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.qingcloud.destroy(instance_id, call=None) Destroy an instance. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-a destroy i\-2f733r5n salt\-cloud \-d i\-2f733r5n .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.qingcloud.get_configured_provider() Return the first configured instance. .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.qingcloud.get_dependencies() Warn if dependencies aren\(aqt met. .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.qingcloud.list_nodes(call=None) Return a list of the instances that are on the provider. .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-Q my\-qingcloud .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.qingcloud.list_nodes_full(call=None) Return a list of the instances that are on the provider. .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-F my\-qingcloud .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.qingcloud.list_nodes_min(call=None) Return a list of the instances that are on the provider. Only a list of instances names, and their state, is returned. .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-f list_nodes_min my\-qingcloud .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.qingcloud.list_nodes_select(call=None) Return a list of the instances that are on the provider, with selected fields. .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-S my\-qingcloud .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.qingcloud.query(params=None) Make a web call to QingCloud IaaS API. .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.qingcloud.reboot(instance_id, call=None) Reboot an instance. .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-a reboot i\-2f733r5n .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.qingcloud.script(vm_) Return the script deployment object. .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.qingcloud.show_image(kwargs, call=None) Show the details from QingCloud concerning an image. .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-f show_image my\-qingcloud image=trustysrvx64c salt\-cloud \-f show_image my\-qingcloud image=trustysrvx64c,coreos4 salt\-cloud \-f show_image my\-qingcloud image=trustysrvx64c zone=ap1 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.qingcloud.show_instance(instance_id, call=None, kwargs=None) Show the details from QingCloud concerning an instance. .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-a show_instance i\-2f733r5n .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.qingcloud.start(instance_id, call=None) Start an instance. .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-a start i\-2f733r5n .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.qingcloud.stop(instance_id, force=False, call=None) Stop an instance. .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-a stop i\-2f733r5n salt\-cloud \-a stop i\-2f733r5n force=True .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.cloud.clouds.saltify .SS Saltify Module .sp The Saltify module is designed to install Salt on a remote machine, virtual or bare metal, using SSH. This module is useful for provisioning machines which are already installed, but not Salted. .sp Changed in version 2018.3.0: The wake_on_lan capability, and actions destroy, reboot, and query functions were added. .sp Use of this module requires some configuration in cloud profile and provider files as described in the Getting Started with Saltify documentation. .INDENT 0.0 .TP .B salt.cloud.clouds.saltify.avail_images(call=None) This function returns a list of images available for this cloud provider. .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-\-list\-images saltify .ft P .fi .UNINDENT .UNINDENT .sp returns a list of available profiles. .sp New in version 2018.3.0. .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.saltify.avail_locations(call=None) This function returns a list of locations available. .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-\-list\-locations my\-cloud\-provider .ft P .fi .UNINDENT .UNINDENT .sp [ saltify will always return an empty dictionary ] .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.saltify.avail_sizes(call=None) This function returns a list of sizes available for this cloud provider. .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-\-list\-sizes saltify .ft P .fi .UNINDENT .UNINDENT .sp [ saltify always returns an empty dictionary ] .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.saltify.create(vm_) if configuration parameter \fBdeploy\fP is \fBTrue\fP, .INDENT 7.0 .INDENT 3.5 Provision a single machine, adding its keys to the salt master .UNINDENT .UNINDENT .sp else, .INDENT 7.0 .INDENT 3.5 Test ssh connections to the machine .UNINDENT .UNINDENT .sp Configuration parameters: .INDENT 7.0 .IP \(bu 2 deploy: (see above) .IP \(bu 2 provider: name of entry in \fBsalt/cloud.providers.d/???\fP file .IP \(bu 2 ssh_host: IP address or DNS name of the new machine .IP \(bu 2 ssh_username: name used to log in to the new machine .IP \(bu 2 ssh_password: password to log in (unless key_filename is used) .IP \(bu 2 key_filename: (optional) SSH private key for passwordless login .IP \(bu 2 ssh_port: (default=22) TCP port for SSH connection .IP \(bu 2 wake_on_lan_mac: (optional) hardware (MAC) address for wake on lan .IP \(bu 2 wol_sender_node: (optional) salt minion to send wake on lan command .IP \(bu 2 wol_boot_wait: (default=30) seconds to delay while client boots .IP \(bu 2 force_minion_config: (optional) replace the minion configuration files on the new machine .UNINDENT .sp See also Miscellaneous Salt Cloud Options and Getting Started with Saltify .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-p mymachine my_new_id .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.saltify.destroy(name, call=None) Destroy a node. .sp New in version 2018.3.0. .sp Disconnect a minion from the master, and remove its keys. .INDENT 7.0 .TP .B Optionally, (if \fBremove_config_on_destroy\fP is \fBTrue\fP), disables salt\-minion from running on the minion, and erases the Salt configuration files from it. .TP .B Optionally, (if \fBshutdown_on_destroy\fP is \fBTrue\fP), orders the minion to halt. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-\-destroy mymachine .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.saltify.get_configured_provider() Return the first configured instance. .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.saltify.list_nodes(call=None) List the nodes which have salt\-cloud:driver:saltify grains. .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-Q .ft P .fi .UNINDENT .UNINDENT .sp returns a list of dictionaries of defined standard fields. .sp New in version 2018.3.0. .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.saltify.list_nodes_full(call=None) Lists complete information for all nodes. .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-F .ft P .fi .UNINDENT .UNINDENT .sp returns a list of dictionaries. .sp for \(aqsaltify\(aq minions, returns dict of grains (enhanced). .sp New in version 2018.3.0. .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.saltify.list_nodes_select(call=None) Return a list of the minions that have salt\-cloud grains, with select fields. .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.saltify.reboot(name, call=None) Reboot a saltify minion. .sp New in version 2018.3.0. .INDENT 7.0 .TP .B name The name of the VM to reboot. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-a reboot vm_name .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.saltify.show_instance(name, call=None) List the a single node, return dict of grains. .UNINDENT .SS salt.cloud.clouds.scaleway .SS Scaleway Cloud Module .sp New in version 2015.8.0. .sp The Scaleway cloud module is used to interact with your Scaleway BareMetal Servers. .sp Use of this module only requires the \fBapi_key\fP parameter to be set. Set up the cloud configuration at \fB/etc/salt/cloud.providers\fP or \fB/etc/salt/cloud.providers.d/scaleway.conf\fP: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C scaleway\-config: # Scaleway organization and token access_key: 0e604a2c\-aea6\-4081\-acb2\-e1d1258ef95c token: be8fd96b\-04eb\-4d39\-b6ba\-a9edbcf17f12 driver: scaleway .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.scaleway.avail_images(call=None) Return a list of the images that are on the provider. .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.scaleway.create(server_) Create a single BareMetal server from a data dict. .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.scaleway.create_node(args) Create a node. .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.scaleway.destroy(name, call=None) Destroy a node. Will check termination protection and warn if enabled. .sp CLI Example: \&.. code\-block:: bash .INDENT 7.0 .INDENT 3.5 salt\-cloud \-\-destroy mymachine .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.scaleway.get_configured_provider() Return the first configured instance. .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.scaleway.get_image(server_) Return the image object to use. .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.scaleway.list_nodes(call=None) Return a list of the BareMetal servers that are on the provider. .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.scaleway.list_nodes_full(call=None) Return a list of the BareMetal servers that are on the provider. .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.scaleway.list_nodes_select(call=None) Return a list of the BareMetal servers that are on the provider, with select fields. .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.scaleway.query(method=\(aqservers\(aq, server_id=None, command=None, args=None, http_method=\(aqGET\(aq, root=\(aqapi_root\(aq) Make a call to the Scaleway API. .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.scaleway.script(server_) Return the script deployment object. .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.scaleway.show_instance(name, call=None) Show the details from a Scaleway BareMetal server. .UNINDENT .SS salt.cloud.clouds.softlayer .SS SoftLayer Cloud Module .sp The SoftLayer cloud module is used to control access to the SoftLayer VPS system. .sp Use of this module only requires the \fBapikey\fP parameter. Set up the cloud configuration at: .sp \fB/etc/salt/cloud.providers\fP or \fB/etc/salt/cloud.providers.d/softlayer.conf\fP: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C my\-softlayer\-config: # SoftLayer account api key user: MYLOGIN apikey: JVkbSJDGHSDKUKSDJfhsdklfjgsjdkflhjlsdfffhgdgjkenrtuinv driver: softlayer .ft P .fi .UNINDENT .UNINDENT .sp The SoftLayer Python Library needs to be installed in order to use the SoftLayer salt.cloud modules. See: \fI\%https://pypi.python.org/pypi/SoftLayer\fP .INDENT 0.0 .TP .B depends softlayer .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.softlayer.avail_images(call=None) Return a dict of all available VM images on the cloud provider. .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.softlayer.avail_locations(call=None) List all available locations .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.softlayer.avail_sizes(call=None) Return a dict of all available VM sizes on the cloud provider with relevant data. This data is provided in three dicts. .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.softlayer.create(vm_) Create a single VM from a data dict .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.softlayer.destroy(name, call=None) Destroy a node. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-\-destroy mymachine .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.softlayer.get_configured_provider() Return the first configured instance. .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.softlayer.get_conn(service=\(aqSoftLayer_Virtual_Guest\(aq) Return a conn object for the passed VM data .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.softlayer.get_dependencies() Warn if dependencies aren\(aqt met. .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.softlayer.get_location(vm_=None) .INDENT 7.0 .TP .B Return the location to use, in this order: .INDENT 7.0 .IP \(bu 2 CLI parameter .IP \(bu 2 VM parameter .IP \(bu 2 Cloud profile setting .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.softlayer.list_custom_images(call=None) Return a dict of all custom VM images on the cloud provider. .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.softlayer.list_nodes(call=None) Return a list of the VMs that are on the provider .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.softlayer.list_nodes_full(mask=\(aqmask[id]\(aq, call=None) Return a list of the VMs that are on the provider .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.softlayer.list_nodes_select(call=None) Return a list of the VMs that are on the provider, with select fields .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.softlayer.list_vlans(call=None) List all VLANs associated with the account .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.softlayer.script(vm_) Return the script deployment object .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.softlayer.show_instance(name, call=None) Show the details from SoftLayer concerning a guest .UNINDENT .SS salt.cloud.clouds.softlayer_hw .SS SoftLayer HW Cloud Module .sp The SoftLayer HW cloud module is used to control access to the SoftLayer hardware cloud system .sp Use of this module only requires the \fBapikey\fP parameter. Set up the cloud configuration at: .sp \fB/etc/salt/cloud.providers\fP or \fB/etc/salt/cloud.providers.d/softlayer.conf\fP: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C my\-softlayer\-config: # SoftLayer account api key user: MYLOGIN apikey: JVkbSJDGHSDKUKSDJfhsdklfjgsjdkflhjlsdfffhgdgjkenrtuinv driver: softlayer_hw .ft P .fi .UNINDENT .UNINDENT .sp The SoftLayer Python Library needs to be installed in order to use the SoftLayer salt.cloud modules. See: \fI\%https://pypi.python.org/pypi/SoftLayer\fP .INDENT 0.0 .TP .B depends softlayer .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.softlayer_hw.avail_images(call=None) Return a dict of all available VM images on the cloud provider. .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.softlayer_hw.avail_locations(call=None) List all available locations .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.softlayer_hw.avail_sizes(call=None) Return a dict of all available VM sizes on the cloud provider with relevant data. This data is provided in three dicts. .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.softlayer_hw.create(vm_) Create a single VM from a data dict .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.softlayer_hw.destroy(name, call=None) Destroy a node. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-\-destroy mymachine .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.softlayer_hw.get_configured_provider() Return the first configured instance. .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.softlayer_hw.get_conn(service=\(aqSoftLayer_Hardware\(aq) Return a conn object for the passed VM data .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.softlayer_hw.get_dependencies() Warn if dependencies aren\(aqt met. .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.softlayer_hw.get_location(vm_=None) .INDENT 7.0 .TP .B Return the location to use, in this order: .INDENT 7.0 .IP \(bu 2 CLI parameter .IP \(bu 2 VM parameter .IP \(bu 2 Cloud profile setting .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.softlayer_hw.list_nodes(call=None) Return a list of the VMs that are on the provider .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.softlayer_hw.list_nodes_full(mask=\(aqmask[id, hostname, primaryIpAddress, primaryBackendIpAddress, processorPhysicalCoreAmount, memoryCount]\(aq, call=None) Return a list of the VMs that are on the provider .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.softlayer_hw.list_nodes_select(call=None) Return a list of the VMs that are on the provider, with select fields .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.softlayer_hw.list_vlans(call=None) List all VLANs associated with the account .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.softlayer_hw.script(vm_) Return the script deployment object .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.softlayer_hw.show_all_categories(call=None) Return a dict of all available categories on the cloud provider. .sp New in version 2016.3.0. .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.softlayer_hw.show_all_prices(call=None, kwargs=None) Return a dict of all prices on the cloud provider. .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.softlayer_hw.show_instance(name, call=None) Show the details from SoftLayer concerning a guest .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.softlayer_hw.show_pricing(kwargs=None, call=None) Show pricing for a particular profile. This is only an estimate, based on unofficial pricing sources. .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-f show_pricing my\-softlayerhw\-config profile=my\-profile .ft P .fi .UNINDENT .UNINDENT .sp If pricing sources have not been cached, they will be downloaded. Once they have been cached, they will not be updated automatically. To manually update all prices, use the following command: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-f update_pricing .ft P .fi .UNINDENT .UNINDENT .sp New in version 2015.8.0. .UNINDENT .SS salt.cloud.clouds.tencentcloud .SS Tencent Cloud Cloud Module .sp New in version 3000. .sp The Tencent Cloud Cloud Module is used to control access to the Tencent Cloud instance. \fI\%https://intl.cloud.tencent.com/\fP .INDENT 0.0 .TP .B To use this module, set up the cloud configuration at \fB/etc/salt/cloud.providers\fP or \fB/etc/salt/cloud.providers.d/*.conf\fP: .UNINDENT .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C my\-tencentcloud\-config: driver: tencentcloud # Tencent Cloud Secret Id id: AKIDA64pOio9BMemkApzevX0HS169S4b750A # Tencent Cloud Secret Key key: 8r2xmPn0C5FDvRAlmcJimiTZKVRsk260 # Tencent Cloud Region location: ap\-guangzhou .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .TP .B depends tencentcloud\-sdk\-python .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.tencentcloud.avail_images(call=None) Return Tencent Cloud available image .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-\-list\-images my\-tencentcloud\-config salt\-cloud \-f avail_images my\-tencentcloud\-config .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.tencentcloud.avail_locations(call=None) Return Tencent Cloud available region .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-\-list\-locations my\-tencentcloud\-config salt\-cloud \-f avail_locations my\-tencentcloud\-config .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.tencentcloud.avail_sizes(call=None) Return Tencent Cloud available instance type .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-\-list\-sizes my\-tencentcloud\-config salt\-cloud \-f avail_sizes my\-tencentcloud\-config .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.tencentcloud.create(vm_) Create a single Tencent Cloud instance from a data dict. .sp Tencent Cloud profiles require a \fBprovider\fP, \fBavailability_zone\fP, \fBimage\fP and \fBsize\fP\&. Set up profile at \fB/etc/salt/cloud.profiles\fP or \fB/etc/salt/cloud.profiles.d/*.conf\fP: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C tencentcloud\-guangzhou\-s1sm1: provider: my\-tencentcloud\-config availability_zone: ap\-guangzhou\-3 image: img\-31tjrtph size: S1.SMALL1 allocate_public_ip: True internet_max_bandwidth_out: 1 password: \(aq153e41ec96140152\(aq securitygroups: \- sg\-5e90804b .ft P .fi .UNINDENT .UNINDENT .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-p tencentcloud\-guangzhou\-s1 myinstance .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.tencentcloud.destroy(name, call=None) Destroy a Tencent Cloud instance .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-a destroy myinstance salt\-cloud \-d myinstance .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.tencentcloud.get_configured_provider() Return the first configured instance. .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.tencentcloud.get_dependencies() Warn if dependencies aren\(aqt met. .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.tencentcloud.get_provider_client(name=None) Return a new provider client .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.tencentcloud.list_availability_zones(call=None) Return all Tencent Cloud availability zones in current region .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-f list_availability_zones my\-tencentcloud\-config .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.tencentcloud.list_custom_images(call=None) Return all Tencent Cloud images in current region .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-f list_custom_images my\-tencentcloud\-config .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.tencentcloud.list_nodes(call=None) Return a list of instances that are on the provider .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-Q .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.tencentcloud.list_nodes_full(call=None) Return a list of instances that are on the provider, with full details .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-F .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.tencentcloud.list_nodes_min(call=None) Return a list of instances that are on the provider, Only names, and their state, is returned. .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-f list_nodes_min my\-tencentcloud\-config .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.tencentcloud.list_nodes_select(call=None) Return a list of instances that are on the provider, with select fields .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-S .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.tencentcloud.list_securitygroups(call=None) Return all Tencent Cloud security groups in current region .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-f list_securitygroups my\-tencentcloud\-config .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.tencentcloud.reboot(name, call=None) Reboot a Tencent Cloud instance .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-a reboot myinstance .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.tencentcloud.script(vm_) Return the script deployment object .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.tencentcloud.show_disk(name, call=None) Show the disk details of Tencent Cloud instance .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-a show_disk myinstance .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.tencentcloud.show_image(kwargs, call=None) Show the details of Tencent Cloud image .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-f show_image tencentcloud image=img\-31tjrtph .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.tencentcloud.show_instance(name, call=None) Show the details of Tencent Cloud instance .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-a show_instance myinstance .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.tencentcloud.start(name, call=None) Start a Tencent Cloud instance Notice: the instance state must be stopped .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-a start myinstance .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.tencentcloud.stop(name, force=False, call=None) Stop a Tencent Cloud running instance Note: use \fIforce=True\fP to make force stop .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-a stop myinstance salt\-cloud \-a stop myinstance force=True .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.cloud.clouds.vagrant .SS Vagrant Cloud Driver .sp The Vagrant cloud is designed to "vagrant up" a virtual machine as a Salt minion. .sp Use of this module requires some configuration in cloud profile and provider files as described in the Getting Started with Vagrant documentation. .sp New in version 2018.3.0. .INDENT 0.0 .TP .B salt.cloud.clouds.vagrant.avail_images(call=None) This function returns a list of images available for this cloud provider. vagrant will return a list of profiles. salt\-cloud \-\-list\-images my\-cloud\-provider .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.vagrant.avail_locations(call=None) This function returns a list of locations available. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-\-list\-locations my\-cloud\-provider # \e[ vagrant will always returns an empty dictionary \e] .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.vagrant.avail_sizes(call=None) This function returns a list of sizes available for this cloud provider. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-\-list\-sizes my\-cloud\-provider # \e[ vagrant always returns an empty dictionary \e] .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.vagrant.create(vm_) Provision a single machine .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-p my_profile new_node_1 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.vagrant.destroy(name, call=None) Destroy a node. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-\-destroy mymachine .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.vagrant.get_configured_provider() Return the first configured instance. .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.vagrant.list_nodes(call=None) List the nodes which have salt\-cloud:driver:vagrant grains. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-Q .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.vagrant.list_nodes_full(call=None) List the nodes, ask all \(aqvagrant\(aq minions, return dict of grains (enhanced). .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-call \-F .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.vagrant.list_nodes_select(call=None) Return a list of the minions that have salt\-cloud grains, with select fields. .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.vagrant.reboot(name, call=None) Reboot a vagrant minion. .INDENT 7.0 .TP .B name The name of the VM to reboot. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-a reboot vm_name .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.vagrant.show_instance(name, call=None) List the a single node, return dict of grains. .UNINDENT .SS salt.cloud.clouds.virtualbox .sp A salt cloud provider that lets you use virtualbox on your machine and act as a cloud. .INDENT 0.0 .TP .B depends vboxapi .UNINDENT .sp For now this will only clone existing VMs. It\(aqs best to create a template from which we will clone. .sp Followed \fI\%https://docs.saltstack.com/en/latest/topics/cloud/cloud.html#non\-libcloud\-based\-modules\fP to create this. .INDENT 0.0 .TP .B Dicts provided by salt: .INDENT 7.0 .TP .B __opts__ contains the options used to run Salt Cloud, as well as a set of configuration and environment variables .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.virtualbox.create(vm_info) Creates a virtual machine from the given VM information .sp This is what is used to request a virtual machine to be created by the cloud provider, wait for it to become available, and then (optionally) log in and install Salt on it. .sp Events fired: .sp This function fires the event \fBsalt/cloud/vm_name/creating\fP, with the payload containing the names of the VM, profile, and provider. .sp @param vm_info .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C { name: profile: driver: : clonefrom: clonemode: (default: state, choices: state, child, all) } .ft P .fi .UNINDENT .UNINDENT .sp @type vm_info dict @return dict of resulting vm. !!!Passwords can and should be included!!! .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.virtualbox.destroy(name, call=None) This function irreversibly destroys a virtual machine on the cloud provider. Before doing so, it should fire an event on the Salt event bus. .sp The tag for this event is \fIsalt/cloud//destroying\fP\&. Once the virtual machine has been destroyed, another event is fired. The tag for that event is \fIsalt/cloud//destroyed\fP\&. .INDENT 7.0 .TP .B Dependencies: list_nodes .UNINDENT .sp @param name: @type name: str @param call: @type call: @return: True if all went well, otherwise an error message @rtype: bool|str .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.virtualbox.get_configured_provider() Return the first configured instance. .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.virtualbox.list_nodes(kwargs=None, call=None) This function returns a list of nodes available on this cloud provider, using the following fields: .sp id (str) image (str) size (str) state (str) private_ips (list) public_ips (list) .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 \-Q option: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-Q .ft P .fi .UNINDENT .UNINDENT .sp @param kwargs: @type kwargs: @param call: @type call: @return: @rtype: .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.virtualbox.list_nodes_full(kwargs=None, call=None) 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. .sp 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 \-F option: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-F .ft P .fi .UNINDENT .UNINDENT .sp @param kwargs: @type kwargs: @param call: @type call: @return: @rtype: .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.virtualbox.list_nodes_select(call=None) Return a list of the VMs that are on the provider, with select fields .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.virtualbox.map_clonemode(vm_info) Convert the virtualbox config file values for clone_mode into the integers the API requires .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.virtualbox.show_image(kwargs, call=None) Show the details of an image .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.virtualbox.start(name, call=None) Start a machine. @param name: Machine to start @type name: str @param call: Must be "action" @type call: str .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.virtualbox.stop(name, call=None) Stop a running machine. @param name: Machine to stop @type name: str @param call: Must be "action" @type call: str .UNINDENT .SS salt.cloud.clouds.vmware .SS VMware Cloud Module .sp New in version 2015.5.4. .sp The VMware cloud module allows you to manage VMware ESX, ESXi, and vCenter. .sp See Getting started with VMware to get started. .INDENT 0.0 .TP .B codeauthor Nitin Madhok <\fI\%nmadhok@clemson.edu\fP> .UNINDENT .SS Dependencies .INDENT 0.0 .IP \(bu 2 pyVmomi Python Module .UNINDENT .SS pyVmomi .sp 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, Python 2.6, Python 2.7.9, or newer must be present. This is due to an upstream dependency in pyVmomi 6.0 that is not supported in Python versions 2.7 to 2.7.8. If the version of Python 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 this original VMware cloud driver was developed against. .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 Ensure python pyVmomi module is installed by running following one\-liner check. The output should be 0. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C python \-c "import pyVmomi" ; echo $? .ft P .fi .UNINDENT .UNINDENT .UNINDENT .UNINDENT .SS Configuration .sp To use this module, set up the vCenter or ESX/ESXi URL, username and password 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 .sp To test the connection for \fBmy\-vmware\-config\fP specified in the cloud configuration, run \fI\%test_vcenter_connection()\fP .INDENT 0.0 .TP .B salt.cloud.clouds.vmware.add_host(kwargs=None, call=None) Add a host system to the specified cluster or datacenter in this VMware environment .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 To use this function, you need to specify \fBesxi_host_user\fP and \fBesxi_host_password\fP under your provider configuration set up 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 vcenter01: driver: vmware user: \(aqDOMAIN\euser\(aq password: \(aqverybadpass\(aq url: \(aqvcenter01.domain.com\(aq # Required when adding a host system esxi_host_user: \(aqroot\(aq esxi_host_password: \(aqmyhostpassword\(aq # Optional fields that can be specified when adding a host system esxi_host_ssl_thumbprint: \(aq12:A3:45:B6:CD:7E:F8:90:A1:BC:23:45:D6:78:9E:FA:01:2B:34:CD\(aq .ft P .fi .UNINDENT .UNINDENT .sp The SSL thumbprint of the host system can be optionally specified by setting \fBesxi_host_ssl_thumbprint\fP under your provider configuration. To get the SSL thumbprint of the host system, execute the following command from a remote server: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C echo \-n | openssl s_client \-connect :443 2>/dev/null | openssl x509 \-noout \-fingerprint \-sha1 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-f add_host my\-vmware\-config host="myHostSystemName" cluster="myClusterName" salt\-cloud \-f add_host my\-vmware\-config host="myHostSystemName" datacenter="myDatacenterName" .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.vmware.avail_images(call=None) Return a list of all the templates present in this VMware environment with basic details .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-\-list\-images my\-vmware\-config .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.vmware.avail_locations(call=None) Return a list of all the available locations/datacenters in this VMware environment .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-\-list\-locations my\-vmware\-config .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.vmware.avail_sizes(call=None) Return a list of all the available sizes in this VMware environment. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-\-list\-sizes my\-vmware\-config .ft P .fi .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 Since sizes are built into templates, this function will return an empty dictionary. .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.vmware.build_clonespec(config_spec, object_ref, reloc_spec, template) Returns the clone spec .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.vmware.connect_host(kwargs=None, call=None) Connect the specified host system in this VMware environment .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-f connect_host my\-vmware\-config host="myHostSystemName" .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.vmware.convert_to_template(name, kwargs=None, call=None) Convert the specified virtual machine to template. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-a convert_to_template vmname .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.vmware.create(vm_) To create a single VM in the VMware environment. .sp Sample profile and arguments that can be specified in it can be found here. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-p vmware\-centos6.5 vmname .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.vmware.create_cluster(kwargs=None, call=None) Create a new cluster under the specified datacenter in this VMware environment .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-f create_cluster my\-vmware\-config name="myNewCluster" datacenter="datacenterName" .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.vmware.create_datacenter(kwargs=None, call=None) Create a new data center in this VMware environment .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-f create_datacenter my\-vmware\-config name="MyNewDatacenter" .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.vmware.create_datastore_cluster(kwargs=None, call=None) Create a new datastore cluster for the specified datacenter in this VMware environment .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-f create_datastore_cluster my\-vmware\-config name="datastoreClusterName" datacenter="datacenterName" .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.vmware.create_folder(kwargs=None, call=None) Create the specified folder path in this VMware environment .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 To create a Host and Cluster Folder under a Datacenter, specify \fBpath="/yourDatacenterName/host/yourFolderName"\fP .sp To create a Network Folder under a Datacenter, specify \fBpath="/yourDatacenterName/network/yourFolderName"\fP .sp To create a Storage Folder under a Datacenter, specify \fBpath="/yourDatacenterName/datastore/yourFolderName"\fP .sp To create a VM and Template Folder under a Datacenter, specify \fBpath="/yourDatacenterName/vm/yourFolderName"\fP .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-f create_folder my\-vmware\-config path="/Local/a/b/c" salt\-cloud \-f create_folder my\-vmware\-config path="/MyDatacenter/vm/MyVMFolder" salt\-cloud \-f create_folder my\-vmware\-config path="/MyDatacenter/host/MyHostFolder" salt\-cloud \-f create_folder my\-vmware\-config path="/MyDatacenter/network/MyNetworkFolder" salt\-cloud \-f create_folder my\-vmware\-config path="/MyDatacenter/storage/MyStorageFolder" .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.vmware.create_snapshot(name, kwargs=None, call=None) Create a snapshot of the specified virtual machine in this VMware environment .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 If the VM is powered on, the internal state of the VM (memory dump) is included in the snapshot by default which will also set the power state of the snapshot to "powered on". You can set \fBmemdump=False\fP to override this. This field is ignored if the virtual machine is powered off or if the VM does not support snapshots with memory dumps. Default is \fBmemdump=True\fP .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 If the VM is powered on when the snapshot is taken, VMware Tools can be used to quiesce the file system in the virtual machine by setting \fBquiesce=True\fP\&. This field is ignored if the virtual machine is powered off; if VMware Tools are not available or if \fBmemdump=True\fP\&. Default is \fBquiesce=False\fP .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-a create_snapshot vmname snapshot_name="mySnapshot" salt\-cloud \-a create_snapshot vmname snapshot_name="mySnapshot" [description="My snapshot"] [memdump=False] [quiesce=True] .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.vmware.destroy(name, call=None) To destroy a VM from the VMware environment .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-d vmname salt\-cloud \-\-destroy vmname salt\-cloud \-a destroy vmname .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.vmware.disconnect_host(kwargs=None, call=None) Disconnect the specified host system in this VMware environment .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-f disconnect_host my\-vmware\-config host="myHostSystemName" .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.vmware.enter_maintenance_mode(kwargs=None, call=None) To put the specified host system in maintenance mode in this VMware environment .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-f enter_maintenance_mode my\-vmware\-config host="myHostSystemName" .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.vmware.exit_maintenance_mode(kwargs=None, call=None) To take the specified host system out of maintenance mode in this VMware environment .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-f exit_maintenance_mode my\-vmware\-config host="myHostSystemName" .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.vmware.get_clonespec_for_valid_snapshot(config_spec, object_ref, reloc_spec, template, vm_) return clonespec only if values are valid .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.vmware.get_configured_provider() Return the first configured instance. .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.vmware.get_dependencies() Warn if dependencies aren\(aqt met. .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.vmware.get_vcenter_version(kwargs=None, call=None) Show the vCenter Server version with build number. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-f get_vcenter_version my\-vmware\-config .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.vmware.handle_snapshot(config_spec, object_ref, reloc_spec, template, vm_) Returns a clone spec for cloning from shapshots :rtype vim.vm.CloneSpec .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.vmware.list_clusters(kwargs=None, call=None) List all the clusters for this VMware environment .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-f list_clusters my\-vmware\-config .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.vmware.list_clusters_by_datacenter(kwargs=None, call=None) List clusters for each datacenter; or clusters for a specified datacenter in this VMware environment .sp To list clusters for each datacenter: .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-f list_clusters_by_datacenter my\-vmware\-config .ft P .fi .UNINDENT .UNINDENT .sp To list clusters for a specified datacenter: .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-f list_clusters_by_datacenter my\-vmware\-config datacenter="datacenterName" .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.vmware.list_datacenters(kwargs=None, call=None) List all the data centers for this VMware environment .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-f list_datacenters my\-vmware\-config .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.vmware.list_datastore_clusters(kwargs=None, call=None) List all the datastore clusters for this VMware environment .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-f list_datastore_clusters my\-vmware\-config .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.vmware.list_datastores(kwargs=None, call=None) List all the datastores for this VMware environment .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-f list_datastores my\-vmware\-config .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.vmware.list_dvs(kwargs=None, call=None) List all the distributed virtual switches for this VMware environment .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-f list_dvs my\-vmware\-config .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.vmware.list_folders(kwargs=None, call=None) List all the folders for this VMware environment .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-f list_folders my\-vmware\-config .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.vmware.list_hbas(kwargs=None, call=None) List all HBAs for each host system; or all HBAs for a specified host system; or HBAs of specified type for each host system; or HBAs of specified type for a specified host system in this VMware environment .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 You can specify type as either \fBparallel\fP, \fBiscsi\fP, \fBblock\fP or \fBfibre\fP\&. .UNINDENT .UNINDENT .sp To list all HBAs for each host system: .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-f list_hbas my\-vmware\-config .ft P .fi .UNINDENT .UNINDENT .sp To list all HBAs for a specified host system: .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-f list_hbas my\-vmware\-config host="hostSystemName" .ft P .fi .UNINDENT .UNINDENT .sp To list HBAs of specified type for each host system: .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-f list_hbas my\-vmware\-config type="HBAType" .ft P .fi .UNINDENT .UNINDENT .sp To list HBAs of specified type for a specified host system: .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-f list_hbas my\-vmware\-config host="hostSystemName" type="HBAtype" .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.vmware.list_hosts(kwargs=None, call=None) List all the hosts for this VMware environment .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-f list_hosts my\-vmware\-config .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.vmware.list_hosts_by_cluster(kwargs=None, call=None) List hosts for each cluster; or hosts for a specified cluster in this VMware environment .sp To list hosts for each cluster: .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-f list_hosts_by_cluster my\-vmware\-config .ft P .fi .UNINDENT .UNINDENT .sp To list hosts for a specified cluster: .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-f list_hosts_by_cluster my\-vmware\-config cluster="clusterName" .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.vmware.list_hosts_by_datacenter(kwargs=None, call=None) List hosts for each datacenter; or hosts for a specified datacenter in this VMware environment .sp To list hosts for each datacenter: .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-f list_hosts_by_datacenter my\-vmware\-config .ft P .fi .UNINDENT .UNINDENT .sp To list hosts for a specified datacenter: .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-f list_hosts_by_datacenter my\-vmware\-config datacenter="datacenterName" .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.vmware.list_networks(kwargs=None, call=None) List all the standard networks for this VMware environment .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-f list_networks my\-vmware\-config .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.vmware.list_nodes(kwargs=None, call=None) Return a list of all VMs and templates that are on the specified provider, with basic fields .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-f list_nodes my\-vmware\-config .ft P .fi .UNINDENT .UNINDENT .sp To return a list of all VMs and templates present on ALL configured providers, with basic fields: .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-Q .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.vmware.list_nodes_full(kwargs=None, call=None) Return a list of all VMs and templates that are on the specified provider, with full details .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-f list_nodes_full my\-vmware\-config .ft P .fi .UNINDENT .UNINDENT .sp To return a list of all VMs and templates present on ALL configured providers, with full details: .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-F .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.vmware.list_nodes_min(kwargs=None, call=None) Return a list of all VMs and templates that are on the specified provider, with no details .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-f list_nodes_min my\-vmware\-config .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.vmware.list_nodes_select(call=None) Return a list of all VMs and templates that are on the specified provider, with fields specified under \fBquery.selection\fP in \fB/etc/salt/cloud\fP .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-f list_nodes_select my\-vmware\-config .ft P .fi .UNINDENT .UNINDENT .sp To return a list of all VMs and templates present on ALL configured providers, with fields specified under \fBquery.selection\fP in \fB/etc/salt/cloud\fP: .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-S .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.vmware.list_portgroups(kwargs=None, call=None) List all the distributed virtual portgroups for this VMware environment .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-f list_portgroups my\-vmware\-config .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.vmware.list_resourcepools(kwargs=None, call=None) List all the resource pools for this VMware environment .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-f list_resourcepools my\-vmware\-config .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.vmware.list_snapshots(kwargs=None, call=None) List snapshots either for all VMs and templates or for a specific VM/template in this VMware environment .sp To list snapshots for all VMs and templates: .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-f list_snapshots my\-vmware\-config .ft P .fi .UNINDENT .UNINDENT .sp To list snapshots for a specific VM/template: .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-f list_snapshots my\-vmware\-config name="vmname" .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.vmware.list_templates(kwargs=None, call=None) List all the templates present in this VMware environment .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-f list_templates my\-vmware\-config .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.vmware.list_vapps(kwargs=None, call=None) List all the vApps for this VMware environment .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-f list_vapps my\-vmware\-config .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.vmware.reboot_host(kwargs=None, call=None) Reboot the specified host system in this VMware environment .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 If the host system is not in maintenance mode, it will not be rebooted. If you want to reboot the host system regardless of whether it is in maintenance mode, set \fBforce=True\fP\&. Default is \fBforce=False\fP\&. .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-f reboot_host my\-vmware\-config host="myHostSystemName" [force=True] .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.vmware.remove_all_snapshots(name, kwargs=None, call=None) Remove all the snapshots present for the specified virtual machine. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 All the snapshots higher up in the hierarchy of the current snapshot tree are consolidated and their virtual disks are merged. To override this behavior and only remove all snapshots, set \fBmerge_snapshots=False\fP\&. Default is \fBmerge_snapshots=True\fP .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-a remove_all_snapshots vmname [merge_snapshots=False] .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.vmware.remove_host(kwargs=None, call=None) Remove the specified host system from this VMware environment .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-f remove_host my\-vmware\-config host="myHostSystemName" .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.vmware.remove_snapshot(name, kwargs=None, call=None) Remove a snapshot of the specified virtual machine in this VMware environment .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-a remove_snapshot vmname snapshot_name="mySnapshot" salt\-cloud \-a remove_snapshot vmname snapshot_name="mySnapshot" [remove_children="True"] .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.vmware.rescan_hba(kwargs=None, call=None) To rescan a specified HBA or all the HBAs on the Host System .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-f rescan_hba my\-vmware\-config host="hostSystemName" salt\-cloud \-f rescan_hba my\-vmware\-config hba="hbaDeviceName" host="hostSystemName" .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.vmware.reset(name, soft=False, call=None) To reset a VM using its name .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 If \fBsoft=True\fP then issues a command to the guest operating system asking it to perform a reboot. Otherwise hypervisor will terminate VM and start it again. Default is soft=False .sp For \fBsoft=True\fP vmtools should be installed on guest system. .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-a reset vmname salt\-cloud \-a reset vmname soft=True .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.vmware.revert_to_snapshot(name, kwargs=None, call=None) Revert virtual machine to its current snapshot. If no snapshot exists, the state of the virtual machine remains unchanged .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 The virtual machine will be powered on if the power state of the snapshot when it was created was set to "Powered On". Set \fBpower_off=True\fP so that the virtual machine stays powered off regardless of the power state of the snapshot when it was created. Default is \fBpower_off=False\fP\&. .sp If the power state of the snapshot when it was created was "Powered On" and if \fBpower_off=True\fP, the VM will be put in suspended state after it has been reverted to the snapshot. .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-a revert_to_snapshot vmame [power_off=True] salt\-cloud \-a revert_to_snapshot vmame snapshot_name="selectedSnapshot" [power_off=True] .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.vmware.script(vm_) Return the script deployment object .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.vmware.show_instance(name, call=None) List all available details of the specified VM .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-a show_instance vmname .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.vmware.shutdown_host(kwargs=None, call=None) Shut down the specified host system in this VMware environment .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 If the host system is not in maintenance mode, it will not be shut down. If you want to shut down the host system regardless of whether it is in maintenance mode, set \fBforce=True\fP\&. Default is \fBforce=False\fP\&. .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-f shutdown_host my\-vmware\-config host="myHostSystemName" [force=True] .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.vmware.start(name, call=None) To start/power on a VM using its name .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-a start vmname .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.vmware.stop(name, soft=False, call=None) To stop/power off a VM using its name .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 If \fBsoft=True\fP then issues a command to the guest operating system asking it to perform a clean shutdown of all services. Default is soft=False .sp For \fBsoft=True\fP vmtools should be installed on guest system. .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-a stop vmname salt\-cloud \-a stop vmname soft=True .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.vmware.suspend(name, call=None) To suspend a VM using its name .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-a suspend vmname .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.vmware.terminate(name, call=None) To do an immediate power off of a VM using its name. A \fBSIGKILL\fP is issued to the vmx process of the VM .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-a terminate vmname .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.vmware.test_vcenter_connection(kwargs=None, call=None) Test if the connection can be made to the vCenter server using the specified credentials inside \fB/etc/salt/cloud.providers\fP or \fB/etc/salt/cloud.providers.d/vmware.conf\fP .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-f test_vcenter_connection my\-vmware\-config .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.vmware.upgrade_tools(name, reboot=False, call=None) To upgrade VMware Tools on a specified virtual machine. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 If the virtual machine is running Windows OS, use \fBreboot=True\fP to reboot the virtual machine after VMware tools upgrade. Default is \fBreboot=False\fP .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-a upgrade_tools vmname salt\-cloud \-a upgrade_tools vmname reboot=True .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.vmware.upgrade_tools_all(call=None) To upgrade VMware Tools on all virtual machines present in the specified provider .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 If the virtual machine is running Windows OS, this function will attempt to suppress the automatic reboot caused by a VMware Tools upgrade. .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-f upgrade_tools_all my\-vmware\-config .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.cloud.clouds.vultrpy .SS Vultr Cloud Module using python\-vultr bindings .sp New in version 2016.3.0. .sp The Vultr cloud module is used to control access to the Vultr VPS system. .sp Use of this module only requires the \fBapi_key\fP parameter. .sp Set up the cloud configuration at \fB/etc/salt/cloud.providers\fP or \fB/etc/salt/cloud.providers.d/vultr.conf\fP: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C my\-vultr\-config: # Vultr account api key api_key: driver: vultr .ft P .fi .UNINDENT .UNINDENT .sp Set up the cloud profile at \fB/etc/salt/cloud.profiles\fP or \fB/etc/salt/cloud.profiles.d/vultr.conf\fP: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C nyc\-4gb\-4cpu\-ubuntu\-14\-04: location: 1 provider: my\-vultr\-config image: 160 size: 95 enable_private_network: True .ft P .fi .UNINDENT .UNINDENT .sp This driver also supports Vultr\(aqs \fIstartup script\fP feature. You can list startup scripts in your account with .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-f list_scripts .ft P .fi .UNINDENT .UNINDENT .sp That list will include the IDs of the scripts in your account. Thus, if you have a script called \(aqsetup\-networking\(aq with an ID of 493234 you can specify that startup script in a profile like so: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C nyc\-2gb\-1cpu\-ubuntu\-17\-04: location: 1 provider: my\-vultr\-config image: 223 size: 13 startup_script_id: 493234 .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.vultrpy.avail_images(conn=None) Return available images .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.vultrpy.avail_locations(conn=None) return available datacenter locations .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.vultrpy.avail_scripts(conn=None) return available startup scripts .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.vultrpy.avail_sizes(conn=None) Return available sizes ("plans" in VultrSpeak) .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.vultrpy.create(vm_) Create a single VM from a data dict .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.vultrpy.destroy(name) Remove a node from Vultr .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.vultrpy.get_configured_provider() Return the first configured instance .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.vultrpy.list_nodes(**kwargs) Return basic data on nodes .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.vultrpy.list_nodes_full(**kwargs) Return all data on nodes .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.vultrpy.list_nodes_select(conn=None, call=None) Return a list of the VMs that are on the provider, with select fields .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.vultrpy.list_scripts(conn=None, call=None) return list of Startup Scripts .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.vultrpy.show_instance(name, call=None) Show the details from the provider concerning an instance .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.vultrpy.start(*args, **kwargs) Execute a "start" action on a VM .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.vultrpy.stop(*args, **kwargs) Execute a "stop" action on a VM .UNINDENT .SS salt.cloud.clouds.xen .SS XenServer Cloud Driver .sp The XenServer driver is designed to work with a Citrix XenServer. .sp Requires XenServer SDK (can be downloaded from \fI\%https://www.citrix.com/downloads/xenserver/product\-software/\fP ) .sp Place a copy of the XenAPI.py in the Python site\-packages folder. .INDENT 0.0 .TP .B depends XenAPI .UNINDENT .sp Example provider configuration: .INDENT 0.0 .INDENT 3.5 .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C # /etc/salt/cloud.providers.d/myxen.conf myxen: driver: xen url: http://10.0.0.120 user: root password: p@ssw0rd .ft P .fi .UNINDENT .UNINDENT .UNINDENT .UNINDENT .sp Example profile configuration: .INDENT 0.0 .INDENT 3.5 .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C # /etc/salt/cloud.profiles.d/myxen.conf suse: provider: myxen user: root password: p@ssw0rd image: opensuseleap42_2\-template storage_repo: \(aqLocal storage\(aq resource_pool: default_pool clone: True minion: master: 10.0.0.18 sles: provider: myxen user: root clone: False image: sles12sp2\-template deploy: False w2k12: provider: myxen image: w2k12svr\-template clone: True userdata_file: /srv/salt/win/files/windows\-firewall.ps1 win_installer: /srv/salt/win/files/Salt\-Minion\-2016.11.3\-AMD64\-Setup.exe win_username: Administrator win_password: p@ssw0rd use_winrm: False ipv4_cidr: 10.0.0.215/24 ipv4_gw: 10.0.0.1 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.xen.avail_images(call=None) Get a list of images from Xen .sp If called with the \fI\-\-list\-images\fP then it returns images with all details. .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-\-list\-images myxen .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.xen.avail_locations(session=None, call=None) Return available Xen locations (not implemented) .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-\-list\-locations myxen .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.xen.avail_sizes(session=None, call=None) Return a list of Xen template definitions .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-\-list\-sizes myxen .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.xen.create(vm_) Create a VM in Xen .sp The configuration for this function is read from the profile settings. .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-p some_profile xenvm01 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.xen.destroy(name=None, call=None) Destroy Xen VM or template instance .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-d xenvm01 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.xen.destroy_template(name=None, call=None, kwargs=None) Destroy Xen VM or template instance .INDENT 7.0 .INDENT 3.5 .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-f destroy_template myxen name=testvm2 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.xen.destroy_vm_vdis(name=None, session=None, call=None) Get virtual block devices on VM .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-a destroy_vm_vdis xenvm01 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.xen.get_configured_provider() Return the first configured instance. .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.xen.get_pv_args(name, session=None, call=None) Get PV arguments for a VM .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-a get_pv_args xenvm01 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.xen.get_vm_ip(name=None, session=None, call=None) Get the IP address of the VM .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-a get_vm_ip xenvm01 .ft P .fi .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 Requires xen guest tools to be installed in VM .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.xen.host_list(call=None) Get a list of Xen Servers .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-f host_list myxen .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.xen.list_nodes() List virtual machines .INDENT 7.0 .INDENT 3.5 .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-Q .ft P .fi .UNINDENT .UNINDENT .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.xen.list_nodes_full(session=None) List full virtual machines .INDENT 7.0 .INDENT 3.5 .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-F .ft P .fi .UNINDENT .UNINDENT .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.xen.list_nodes_select(call=None) Perform a select query on Xen VM instances .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-S .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.xen.pause(name, call=None, session=None) Pause a vm .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-a pause xenvm01 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.xen.pif_list(call=None) Get a list of Resource Pools .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-f pool_list myxen .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.xen.pool_list(call=None) Get a list of Resource Pools .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-f pool_list myxen .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.xen.reboot(name, call=None, session=None) Reboot a vm .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-a reboot xenvm01 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.xen.resume(name, call=None, session=None) Resume a vm from disk .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-a resume xenvm01 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.xen.set_pv_args(name, kwargs=None, session=None, call=None) Set PV arguments for a VM .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-a set_pv_args xenvm01 pv_args="utf\-8 graphical" .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.xen.set_vm_ip(name=None, ipv4_cidr=None, ipv4_gw=None, session=None, call=None) Set the IP address on a virtual interface (vif) .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.xen.show_instance(name, session=None, call=None) Show information about a specific VM or template .INDENT 7.0 .INDENT 3.5 .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-a show_instance xenvm01 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 memory is memory_dynamic_max .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.xen.shutdown(name, call=None, session=None) Shutdown a vm .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-a shutdown xenvm01 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.xen.sr_list(call=None) Geta list of storage repositories .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-f sr_list myxen .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.xen.start(name, call=None, session=None) Start a vm .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-a start xenvm01 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.xen.stop(name, call=None, session=None) Stop a vm .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-a stop xenvm01 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.xen.suspend(name, call=None, session=None) Suspend a vm to disk .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-a suspend xenvm01 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.xen.template_list(call=None) Return available Xen template information. .sp This returns the details of each template to show number cores, memory sizes, etc.. .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-f template_list myxen .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.xen.unpause(name, call=None, session=None) UnPause a vm .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-a unpause xenvm01 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.xen.vbd_list(name=None, call=None) Get a list of VBDs on a VM .sp \fBrequires\fP: the name of the vm with the vbd definition .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-a vbd_list xenvm01 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.xen.vdi_list(call=None, kwargs=None) Return available Xen VDI images .sp If this function is called with the \fB\-f\fP or \fB\-\-function\fP then it can return a list with minimal deatil using the \fBterse=True\fP keyword argument. .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-f vdi_list myxen terse=True .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.cloud.clouds.xen.vif_list(name, call=None, kwargs=None) Get a list of virtual network interfaces on a VM .sp \fBrequires\fP: the name of the vm with the vbd definition .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-cloud \-a vif_list xenvm01 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS engine modules .TS center; |l|l|. _ T{ \fBdocker_events\fP T} T{ Send events from Docker events :Depends: Docker API >= 1.22 T} _ T{ \fBfluent\fP T} T{ An engine that reads messages from the salt event bus and pushes them onto a fluent endpoint. T} _ T{ \fBhttp_logstash\fP T} T{ HTTP Logstash engine T} _ T{ \fBircbot\fP T} T{ IRC Bot engine T} _ T{ \fBjunos_syslog\fP T} T{ Junos Syslog Engine T} _ T{ \fBlibvirt_events\fP T} T{ An engine that listens for libvirt events and resends them to the salt event bus. T} _ T{ \fBlogentries\fP T} T{ An engine that sends events to the Logentries logging service. T} _ T{ \fBlogstash_engine\fP T} T{ An engine that reads messages from the salt event bus and pushes them onto a logstash endpoint. T} _ T{ \fBnapalm_syslog\fP T} T{ NAPALM syslog engine 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{ \fBscript\fP T} T{ Send events based on a script\(aqs stdout T} _ T{ \fBslack\fP T} T{ An engine that reads messages from Slack and can act on them T} _ T{ \fBsqs_events\fP T} T{ An engine that continuously reads messages from SQS and fires them as events. T} _ T{ \fBstalekey\fP T} T{ An engine that uses presence detection to keep track of which minions have been recently connected and remove their keys if they have not been connected for a certain period of time. 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} _ T{ \fBwebhook\fP T} T{ Send events from webhook api 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, filters=None) 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 filters: event: \- start \- stop \- die \- oom .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. .sp For filter reference, see \fI\%https://docs.docker.com/engine/reference/commandline/events/\fP .UNINDENT .SS salt.engines.fluent .sp An engine that reads messages from the salt event bus and pushes them onto a fluent endpoint. .sp New in version 3000. .INDENT 0.0 .TP .B Configuration .UNINDENT .sp All arguments are optional .INDENT 0.0 .INDENT 3.5 Example configuration of default settings .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C engines: \- fluent: host: localhost port: 24224 app: engine .ft P .fi .UNINDENT .UNINDENT .sp Example fluentd configuration .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C @type forward port 24224 @type file path /var/log/td\-agent/saltstack .ft P .fi .UNINDENT .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B depends fluent\-logger .UNINDENT .INDENT 0.0 .TP .B salt.engines.fluent.start(host=\(aqlocalhost\(aq, port=24224, app=\(aqengine\(aq) Listen to salt events and forward them to fluent .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBhost\fP (\fI\%str\fP) \-\- Host running fluentd agent. Default is localhost .IP \(bu 2 \fBport\fP (\fI\%int\fP) \-\- Port of fluentd agent. Default is 24224 .IP \(bu 2 \fBapp\fP (\fI\%str\fP) \-\- Text sent as fluentd tag. Default is "engine". This text is appended to "saltstack." to form a fluentd tag, ex: "saltstack.engine" .UNINDENT .UNINDENT .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. .sp Changed in version 2018.3.0. .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 By default, this engine take everything from the Salt bus and exports into Logstash. For a better selection of the events that you want to publish, you can use the \fBtags\fP and \fBfuns\fP options. .UNINDENT .UNINDENT .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. .INDENT 7.0 .TP .B url The Logstash endpoint. .TP .B funs: \fBNone\fP A list of functions to be compared against, looking into the \fBfun\fP field from the event data. This option helps to select the events generated by one or more functions. If an event does not have the \fBfun\fP field in the data section, it will be published. For a better selection, consider using the \fBtags\fP option. By default, this option accepts any event to be submitted to Logstash. .TP .B tags: \fBNone\fP A list of pattern to compare the event tag against. By default, this option accepts any event to be submitted to Logstash. .UNINDENT .UNINDENT .SS salt.engines.ircbot .sp IRC Bot engine .sp New in version 2017.7.0. .sp Example Configuration .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C engines: \- ircbot: nick: username: password: host: chat.freenode.net port: 7000 channels: \- salt\-test \- \(aq##something\(aq use_ssl: True use_sasl: True disable_query: True allow_hosts: \- salt/engineer/.* allow_nicks: \- gtmanfred .ft P .fi .UNINDENT .UNINDENT .sp Available commands on irc are: .INDENT 0.0 .TP .B ping return pong .TP .B echo return targeted at the user who sent the commands .TP .B event [, ] fire event on the master or minion event stream with the tag \fIsalt/engines/ircbot/\fP and a data object with a list of everything else sent in the message .UNINDENT .sp Example of usage .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C 08:33:57 @gtmanfred > !ping 08:33:57 gtmanbot > gtmanfred: pong 08:34:02 @gtmanfred > !echo ping 08:34:02 gtmanbot > ping 08:34:17 @gtmanfred > !event test/tag/ircbot irc is useful 08:34:17 gtmanbot > gtmanfred: TaDa! .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C [DEBUG ] Sending event: tag = salt/engines/ircbot/test/tag/ircbot; data = {\(aq_stamp\(aq: \(aq2016\-11\-28T14:34:16.633623\(aq, \(aqdata\(aq: [\(aqirc\(aq, \(aqis\(aq, \(aquseful\(aq]} .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .TP .B class salt.engines.ircbot.Event(source, code, line) .INDENT 7.0 .TP .B code Alias for field number 1 .UNINDENT .INDENT 7.0 .TP .B line Alias for field number 2 .UNINDENT .INDENT 7.0 .TP .B source Alias for field number 0 .UNINDENT .UNINDENT .INDENT 0.0 .TP .B class salt.engines.ircbot.IRCClient(nick, host, port=6667, username=None, password=None, channels=None, use_ssl=False, use_sasl=False, char=\(aq!\(aq, allow_hosts=False, allow_nicks=False, disable_query=True) .INDENT 7.0 .TP .B join_channel(channel) .UNINDENT .INDENT 7.0 .TP .B on_closed() .UNINDENT .INDENT 7.0 .TP .B on_connect() .UNINDENT .INDENT 7.0 .TP .B read_messages() .UNINDENT .INDENT 7.0 .TP .B send_message(line) .UNINDENT .UNINDENT .INDENT 0.0 .TP .B class salt.engines.ircbot.PrivEvent(source, nick, user, host, code, channel, command, line) .INDENT 7.0 .TP .B channel Alias for field number 5 .UNINDENT .INDENT 7.0 .TP .B code Alias for field number 4 .UNINDENT .INDENT 7.0 .TP .B command Alias for field number 6 .UNINDENT .INDENT 7.0 .TP .B host Alias for field number 3 .UNINDENT .INDENT 7.0 .TP .B line Alias for field number 7 .UNINDENT .INDENT 7.0 .TP .B nick Alias for field number 1 .UNINDENT .INDENT 7.0 .TP .B source Alias for field number 0 .UNINDENT .INDENT 7.0 .TP .B user Alias for field number 2 .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.engines.ircbot.start(nick, host, port=6667, username=None, password=None, channels=None, use_ssl=False, use_sasl=False, char=\(aq!\(aq, allow_hosts=False, allow_nicks=False, disable_query=True) IRC Bot for interacting with salt. .INDENT 7.0 .TP .B nick Nickname of the connected Bot. .TP .B host irc server (example \- chat.freenode.net). .TP .B port irc port. Default: 6667 .TP .B password password for authenticating. If not provided, user will not authenticate on the irc server. .TP .B channels channels to join. .TP .B use_ssl connect to server using ssl. Default: False .TP .B use_sasl authenticate using sasl, instead of messaging NickServ. Default: False .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 This will allow the bot user to be fully authenticated before joining any channels .UNINDENT .UNINDENT .TP .B char command character to look for. Default: ! .TP .B allow_hosts hostmasks allowed to use commands on the bot. Default: False True to allow all False to allow none List of regexes to allow matching .TP .B allow_nicks Nicks that are allowed to use commands on the bot. Default: False True to allow all False to allow none List of regexes to allow matching .TP .B disable_query Disable commands from being sent through private queries. Require they be sent to a channel, so that all communication can be controlled by access to the channel. Default: True .UNINDENT .sp \fBWARNING:\fP .INDENT 7.0 .INDENT 3.5 Unauthenticated Access to event stream .sp This engine sends events calls to the event stream without authenticating them in salt. Authentication will need to be configured and enforced on the irc server or enforced in the irc channel. The engine only accepts commands from channels, so non authenticated users could be banned or quieted in the channel. .sp /mode +q $~a # quiet all users who are not authenticated /mode +r # do not allow unauthenticated users into the channel .sp It would also be possible to add a password to the irc channel, or only allow invited users to join. .UNINDENT .UNINDENT .UNINDENT .SS salt.engines.junos_syslog module .SS Junos Syslog Engine .sp New in version 2017.7.0. .INDENT 0.0 .TP .B depends pyparsing, twisted .UNINDENT .sp An engine that listens to syslog message from Junos devices, extract event information and generate message on SaltStack bus. .sp The event topic sent to salt is dynamically generated according to the topic title specified by the user. The incoming event data (from the junos device) consists of the following fields: .INDENT 0.0 .IP 1. 4 hostname .IP 2. 4 hostip .IP 3. 4 daemon .IP 4. 4 event .IP 5. 4 severity .IP 6. 4 priority .IP 7. 4 timestamp .IP 8. 4 message .IP 9. 4 pid .IP 10. 4 raw (the raw event data forwarded from the device) .UNINDENT .sp The topic title can consist of any of the combination of above fields, but the topic has to start with \(aqjnpr/syslog\(aq. So, we can have different combinations: .INDENT 0.0 .INDENT 3.5 .INDENT 0.0 .IP \(bu 2 jnpr/syslog/hostip/daemon/event .IP \(bu 2 jnpr/syslog/daemon/severity .UNINDENT .UNINDENT .UNINDENT .sp The corresponding dynamic topic sent on salt event bus would look something like: .INDENT 0.0 .INDENT 3.5 .INDENT 0.0 .IP \(bu 2 jnpr/syslog/1.1.1.1/mgd/UI_COMMIT_COMPLETED .IP \(bu 2 jnpr/syslog/sshd/7 .UNINDENT .UNINDENT .UNINDENT .sp The default topic title is \(aqjnpr/syslog/hostname/event\(aq. .sp The user can choose the type of data they wants of the event bus. Like, if one wants only events pertaining to a particular daemon, they can specify that in the configuration file: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C daemon: mgd .ft P .fi .UNINDENT .UNINDENT .sp One can even have a list of daemons like: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C daemon: \- mgd \- sshd .ft P .fi .UNINDENT .UNINDENT .sp Example configuration (to be written in master config file) .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C engines: \- junos_syslog: port: 9999 topic: jnpr/syslog/hostip/daemon/event daemon: \- mgd \- sshd .ft P .fi .UNINDENT .UNINDENT .sp For junos_syslog engine to receive events, syslog must be set on the junos device. This can be done via following configuration: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C set system syslog host port 516 any any .ft P .fi .UNINDENT .UNINDENT .sp Below is a sample syslog event which is received from the junos device: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C \(aq<30>May 29 05:18:12 bng\-ui\-vm\-9 mspd[1492]: No chassis configuration found\(aq .ft P .fi .UNINDENT .UNINDENT .sp The source for parsing the syslog messages is taken from: \fI\%https://gist.github.com/leandrosilva/3651640#file\-xlog\-py\fP .INDENT 0.0 .TP .B salt.engines.junos_syslog.start(port=516, **kwargs) .UNINDENT .SS salt.engines.libvirt_events module .sp An engine that listens for libvirt events and resends them to the salt event bus. .sp The minimal configuration is the following and will listen to all events on the local hypervisor and send them with a tag starting with \fBsalt/engines/libvirt_events\fP: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C engines: \- libvirt_events .ft P .fi .UNINDENT .UNINDENT .sp Note that the automatically\-picked libvirt connection will depend on the value of \fBuri_default\fP in \fB/etc/libvirt/libvirt.conf\fP\&. To force using another connection like the local LXC libvirt driver, set the \fBuri\fP property as in the following example configuration. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C engines: \- libvirt_events: uri: lxc:/// tag_prefix: libvirt filters: \- domain/lifecycle \- domain/reboot \- pool .ft P .fi .UNINDENT .UNINDENT .sp Filters is a list of event types to relay to the event bus. Items in this list can be either one of the main types (\fBdomain\fP, \fBnetwork\fP, \fBpool\fP, \fBnodedev\fP, \fBsecret\fP), \fBall\fP or a more precise filter. These can be done with values like /. The possible values are in the CALLBACK_DEFS constant. If the filters list contains \fBall\fP, all events will be relayed. .sp Be aware that the list of events increases with libvirt versions, for example network events have been added in libvirt 1.2.1 and storage events in 2.0.0. .SS Running the engine on non\-root .sp Running this engine as non\-root requires a special attention, which is surely the case for the master running as user \fIsalt\fP\&. The engine is likely to fail to connect to libvirt with an error like this one: .INDENT 0.0 .INDENT 3.5 [ERROR ] authentication unavailable: no polkit agent available to authenticate action \(aqorg.libvirt.unix.monitor\(aq .UNINDENT .UNINDENT .sp To fix this, the user running the engine, for example the salt\-master, needs to have the rights to connect to libvirt in the machine polkit config. A polkit rule like the following one will allow \fIsalt\fP user to connect to libvirt: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C polkit.addRule(function(action, subject) { if (action.id.indexOf("org.libvirt") == 0 && subject.user == "salt") { return polkit.Result.YES; } }); .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .TP .B depends libvirt 1.0.0+ python binding .UNINDENT .sp New in version 2019.2.0. .INDENT 0.0 .TP .B salt.engines.libvirt_events.start(uri=None, tag_prefix=\(aqsalt/engines/libvirt_events\(aq, filters=None) Listen to libvirt events and forward them to salt. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBuri\fP \-\- libvirt URI to listen on. Defaults to None to pick the first available local hypervisor .IP \(bu 2 \fBtag_prefix\fP \-\- the beginning of the salt event tag to use. Defaults to \(aqsalt/engines/libvirt_events\(aq .IP \(bu 2 \fBfilters\fP \-\- the list of event of listen on. Defaults to \(aqall\(aq .UNINDENT .UNINDENT .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 Example configuration .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C engines: \- logentries: endpoint: data.logentries.com port: 10000 token: 057af3e2\-1c05\-47c5\-882a\-5cd644655dbf .ft P .fi .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 class salt.engines.logentries.PlainTextSocketAppender(verbose=True, LE_API=\(aqdata.logentries.com\(aq, LE_PORT=80, LE_TLS_PORT=443) .INDENT 7.0 .TP .B close_connection() .UNINDENT .INDENT 7.0 .TP .B open_connection() .UNINDENT .INDENT 7.0 .TP .B put(data) .UNINDENT .INDENT 7.0 .TP .B reopen_connection() .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.engines.logentries.SocketAppender alias of \fI\%salt.engines.logentries.TLSSocketAppender\fP .UNINDENT .INDENT 0.0 .TP .B class salt.engines.logentries.TLSSocketAppender(verbose=True, LE_API=\(aqdata.logentries.com\(aq, LE_PORT=80, LE_TLS_PORT=443) .INDENT 7.0 .TP .B open_connection() .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.engines.logentries.event_bus_context(opts) .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_engine .sp An engine that reads messages from the salt event bus and pushes them onto a logstash endpoint. .INDENT 0.0 .TP .B configuration Example configuration .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C engines: \- logstash: host: log.my_network.com port: 5959 proto: tcp .ft P .fi .UNINDENT .UNINDENT .TP .B depends logstash .UNINDENT .INDENT 0.0 .TP .B salt.engines.logstash_engine.event_bus_context(opts) .UNINDENT .INDENT 0.0 .TP .B salt.engines.logstash_engine.start(host, port=5959, tag=\(aqsalt/engine/logstash\(aq, proto=\(aqudp\(aq) Listen to salt events and forward them to logstash .UNINDENT .SS salt.engines.napalm_syslog .SS NAPALM syslog engine .sp New in version 2017.7.0. .sp An engine that takes syslog messages structured in \fI\%OpenConfig\fP or IETF format and fires Salt events. .sp As there can be many messages pushed into the event bus, the user is able to filter based on the object structure. .SS Requirements .INDENT 0.0 .IP \(bu 2 \fI\%napalm\-logs\fP .UNINDENT .sp This engine transfers objects from the napalm\-logs library into the event bus. The top dictionary has the following keys: .INDENT 0.0 .IP \(bu 2 \fBip\fP .IP \(bu 2 \fBhost\fP .IP \(bu 2 \fBtimestamp\fP .IP \(bu 2 \fBos\fP: the network OS identified .IP \(bu 2 \fBmodel_name\fP: the OpenConfig or IETF model name .IP \(bu 2 \fBerror\fP: the error name (consult the documentation) .IP \(bu 2 \fBmessage_details\fP: details extracted from the syslog message .IP \(bu 2 \fBopen_config\fP: the OpenConfig model .UNINDENT .sp The napalm\-logs transfers the messages via widely used transport mechanisms such as: ZeroMQ (default), Kafka, etc. .sp The user can select the right transport using the \fBtransport\fP option in the configuration. .INDENT 0.0 .TP .B configuration Example configuration .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C engines: \- napalm_syslog: transport: zmq address: 1.2.3.4 port: 49018 .ft P .fi .UNINDENT .UNINDENT .TP .B configuration Configuration example, excluding messages from IOS\-XR devices: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C engines: \- napalm_syslog: transport: kafka address: 1.2.3.4 port: 49018 os_blacklist: \- iosxr .ft P .fi .UNINDENT .UNINDENT .UNINDENT .sp Event example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C { "_stamp": "2017\-05\-26T10:03:18.653045", "error": "BGP_PREFIX_THRESH_EXCEEDED", "host": "vmx01", "ip": "192.168.140.252", "message_details": { "date": "May 25", "host": "vmx01", "message": "192.168.140.254 (External AS 65001): Configured maximum prefix\-limit threshold(22) exceeded for inet\-unicast nlri: 28 (instance master)", "pri": "28", "processId": "2957", "processName": "rpd", "tag": "BGP_PREFIX_THRESH_EXCEEDED", "time": "20:50:41" }, "model_name": "openconfig_bgp", "open_config": { "bgp": { "neighbors": { "neighbor": { "192.168.140.254": { "afi_safis": { "afi_safi": { "inet": { "afi_safi_name": "inet", "ipv4_unicast": { "prefix_limit": { "state": { "max_prefixes": 22 } } }, "state": { "prefixes": { "received": 28 } } } } }, "neighbor_address": "192.168.140.254", "state": { "peer_as": 65001 } } } } } }, "os": "junos", "timestamp": "1495741841" } .ft P .fi .UNINDENT .UNINDENT .sp To consume the events and eventually react and deploy a configuration changes on the device(s) firing the event, one is able to identify the minion ID, using one of the following alternatives, but not limited to: .INDENT 0.0 .IP \(bu 2 \fBHost grains\fP to match the event tag .IP \(bu 2 \fBHost DNS grain\fP to match the IP address in the event data .IP \(bu 2 \fBHostname grains\fP to match the event tag .IP \(bu 2 Define static grains .IP \(bu 2 Write a grains module .IP \(bu 2 Targeting minions using pillar data \- The user can configure certain information in the Pillar data and then use it to identify minions .UNINDENT .sp Master configuration example, to match the event and react: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C reactor: \- \(aqnapalm/syslog/*/BGP_PREFIX_THRESH_EXCEEDED/*\(aq: \- salt://increase_prefix_limit_on_thresh_exceeded.sls .ft P .fi .UNINDENT .UNINDENT .sp Which matches the events having the error code \fBBGP_PREFIX_THRESH_EXCEEDED\fP from any network operating system, from any host and reacts, executing the \fBincrease_prefix_limit_on_thresh_exceeded.sls\fP reactor, found under one of the \fBfile_roots\fP paths. .sp Reactor example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C increase_prefix_limit_on_thresh_exceeded: local.net.load_template: \- tgt: "hostname:{{ data[\(aqhost\(aq] }}" \- tgt_type: grain \- kwarg: template_name: salt://increase_prefix_limit.jinja openconfig_structure: {{ data[\(aqopen_config\(aq] }} .ft P .fi .UNINDENT .UNINDENT .sp The reactor in the example increases the BGP prefix limit when triggered by an event as above. The minion is matched using the \fBhost\fP field from the \fBdata\fP (which is the body of the event), compared to the \fBhostname grain\fP field. When the event occurs, the reactor will execute the \fBnet.load_template\fP function, sending as arguments the template \fBsalt://increase_prefix_limit.jinja\fP defined by the user in their environment and the complete OpenConfig object under the variable name \fBopenconfig_structure\fP\&. Inside the Jinja template, the user can process the object from \fBopenconfig_structure\fP and define the bussiness logic as required. .INDENT 0.0 .TP .B salt.engines.napalm_syslog.start(transport=\(aqzmq\(aq, address=\(aq0.0.0.0\(aq, port=49017, auth_address=\(aq0.0.0.0\(aq, auth_port=49018, disable_security=False, certificate=None, os_whitelist=None, os_blacklist=None, error_whitelist=None, error_blacklist=None, host_whitelist=None, host_blacklist=None) Listen to napalm\-logs and publish events into the Salt event bus. .INDENT 7.0 .TP .B transport: \fBzmq\fP Choose the desired transport. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 Currently \fBzmq\fP is the only valid option. .UNINDENT .UNINDENT .TP .B address: \fB0.0.0.0\fP The address of the publisher, as configured on napalm\-logs. .TP .B port: \fB49017\fP The port of the publisher, as configured on napalm\-logs. .TP .B auth_address: \fB0.0.0.0\fP The address used for authentication when security is not disabled. .TP .B auth_port: \fB49018\fP Port used for authentication. .TP .B disable_security: \fBFalse\fP Trust unencrypted messages. Strongly discouraged in production. .TP .B certificate: \fBNone\fP Absolute path to the SSL certificate. .TP .B os_whitelist: \fBNone\fP List of operating systems allowed. By default everything is allowed. .TP .B os_blacklist: \fBNone\fP List of operating system to be ignored. Nothing ignored by default. .TP .B error_whitelist: \fBNone\fP List of errors allowed. .TP .B error_blacklist: \fBNone\fP List of errors ignored. .TP .B host_whitelist: \fBNone\fP List of hosts or IPs to be allowed. .TP .B host_blacklist: \fBNone\fP List of hosts of IPs to be ignored. .UNINDENT .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 .INDENT 0.0 .TP .B salt.engines.reactor.start(refresh_interval=None, worker_threads=None, worker_hwm=None) .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 Example configuration .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C engines: \- redis_sentinel: hosts: matching: \(aqboard*\(aq port: 26379 interface: eth2 channels: \- \(aq+switch\-master\(aq \- \(aq+odown\(aq \- \(aq\-odown\(aq .ft P .fi .UNINDENT .UNINDENT .TP .B depends redis .UNINDENT .INDENT 0.0 .TP .B class salt.engines.redis_sentinel.Listener(host=None, port=None, channels=None, tag=None) .INDENT 7.0 .TP .B run() .UNINDENT .INDENT 7.0 .TP .B work(item) .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.engines.redis_sentinel.start(hosts, channels, tag=None) .UNINDENT .SS salt.engines.script module .sp Send events based on a script\(aqs stdout .sp Example Config .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C engines: \- script: cmd: /some/script.py \-a 1 \-b 2 output: json interval: 5 .ft P .fi .UNINDENT .UNINDENT .sp Script engine configs: .INDENT 0.0 .INDENT 3.5 cmd: Script or command to execute output: Any available saltstack deserializer interval: How often in seconds to execute the command .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.engines.script.start(cmd, output=\(aqjson\(aq, interval=1) Parse stdout of a command and generate an event .sp The script engine will scrap stdout of the given script and generate an event based on the presence of the \(aqtag\(aq key and its value. .sp If there is a data obj available, that will also be fired along with the tag. .sp Example .sp Given the following json output from a script: .INDENT 7.0 .INDENT 3.5 .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C { "tag" : "lots/of/tacos", "data" : { "toppings" : "cilantro" } } .ft P .fi .UNINDENT .UNINDENT .UNINDENT .UNINDENT .sp This will fire the event \(aqlots/of/tacos\(aq on the event bus with the data obj as is. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBcmd\fP \-\- The command to execute .IP \(bu 2 \fBoutput\fP \-\- How to deserialize stdout of the script .IP \(bu 2 \fBinterval\fP \-\- How often to execute the script .UNINDENT .UNINDENT .UNINDENT .SS salt.engines.slack module .sp An engine that reads messages from Slack and can act on them .INDENT 0.0 .TP .B depends \fI\%slackclient\fP Python module .UNINDENT .sp \fBIMPORTANT:\fP .INDENT 0.0 .INDENT 3.5 This engine requires a bot user. To create a bot user, first go to the \fBCustom Integrations\fP page in your Slack Workspace. Copy and paste the following URL, and replace \fBmyworkspace\fP with the proper value for your workspace: .sp \fBhttps://myworkspace.slack.com/apps/manage/custom\-integrations\fP .sp Next, click on the \fBBots\fP integration and request installation. Once approved by an admin, you will be able to proceed with adding the bot user. Once the bot user has been added, you can configure it by adding an avatar, setting the display name, etc. You will also at this time have access to your API token, which will be needed to configure this engine. .sp Finally, add this bot user to a channel by switching to the channel and using \fB/invite @mybotuser\fP\&. Keep in mind that this engine will process messages from each channel in which the bot is a member, so it is recommended to narrowly define the commands which can be executed, and the Slack users which are allowed to run commands. .UNINDENT .UNINDENT .sp This engine has two boolean configuration parameters that toggle specific features (both default to \fBFalse\fP): .INDENT 0.0 .IP 1. 3 \fBcontrol\fP \- If set to \fBTrue\fP, then any message which starts with the trigger string (which defaults to \fB!\fP and can be overridden by setting the \fBtrigger\fP option in the engine configuration) will be interpreted as a Salt CLI command and the engine will attempt to run it. The permissions defined in the various \fBgroups\fP will determine if the Slack user is allowed to run the command. The \fBtargets\fP and \fBdefault_target\fP options can be used to set targets for a given command, but the engine can also read the following two keyword arguments: .INDENT 3.0 .IP \(bu 2 \fBtarget\fP \- The target expression to use for the command .IP \(bu 2 \fBtgt_type\fP \- The match type, can be one of \fBglob\fP, \fBlist\fP, \fBpcre\fP, \fBgrain\fP, \fBgrain_pcre\fP, \fBpillar\fP, \fBnodegroup\fP, \fBrange\fP, \fBipcidr\fP, or \fBcompound\fP\&. The default value is \fBglob\fP\&. .UNINDENT .sp Here are a few examples: .INDENT 3.0 .INDENT 3.5 .sp .nf .ft C !test.ping target=* !state.apply foo target=os:CentOS tgt_type=grain !pkg.version mypkg target=role:database tgt_type=pillar .ft P .fi .UNINDENT .UNINDENT .IP 2. 3 \fBfire_all\fP \- If set to \fBTrue\fP, all messages which are not prefixed with the trigger string will fired as events onto Salt\(aqs ref:\fIevent bus \fP\&. The tag for these veents will be prefixed with the string specified by the \fBtag\fP config option (default: \fBsalt/engines/slack\fP). .UNINDENT .sp The \fBgroups_pillar_name\fP config option can be used to pull group configuration from the specified pillar key. .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 In order to use \fBgroups_pillar_name\fP, the engine must be running as a minion running on the master, so that the \fBCaller\fP client can be used to retrieve that minions pillar data, because the master process does not have pillar data. .UNINDENT .UNINDENT .SS Configuration Examples .sp Changed in version 2017.7.0: Access control group support added .sp This example uses a single group called \fBdefault\fP\&. In addition, other groups are being loaded from pillar data. The group names do not have any significance, it is the users and commands defined within them that are used to determine whether the Slack user has permission to run the desired command. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C engines: \- slack: token: \(aqxoxb\-xxxxxxxxxx\-xxxxxxxxxxxxxxxxxxxxxxxx\(aq control: True fire_all: False groups_pillar_name: \(aqslack_engine:groups_pillar\(aq groups: default: users: \- \(aq*\(aq commands: \- test.ping \- cmd.run \- list_jobs \- list_commands aliases: list_jobs: cmd: jobs.list_jobs list_commands: cmd: \(aqpillar.get salt:engines:slack:valid_commands target=saltmaster tgt_type=list\(aq default_target: target: saltmaster tgt_type: glob targets: test.ping: target: \(aq*\(aq tgt_type: glob cmd.run: target: saltmaster tgt_type: list .ft P .fi .UNINDENT .UNINDENT .sp This example shows multiple groups applying to different users, with all users having access to run test.ping. Keep in mind that when using \fB*\fP, the value must be quoted, or else PyYAML will fail to load the configuration. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C engines: \- slack: groups_pillar: slack_engine_pillar token: \(aqxoxb\-xxxxxxxxxx\-xxxxxxxxxxxxxxxxxxxxxxxx\(aq control: True fire_all: True tag: salt/engines/slack groups_pillar_name: \(aqslack_engine:groups_pillar\(aq groups: default: users: \- \(aq*\(aq commands: \- test.ping aliases: list_jobs: cmd: jobs.list_jobs list_commands: cmd: \(aqpillar.get salt:engines:slack:valid_commands target=saltmaster tgt_type=list\(aq gods: users: \- garethgreenaway commands: \- \(aq*\(aq .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .TP .B class salt.engines.slack.SlackClient(token) .INDENT 7.0 .TP .B can_user_run(user, command, groups) Break out the permissions into the following: .sp Check whether a user is in any group, including whether a group has the \(aq*\(aq membership .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBuser\fP (\fI\%str\fP) \-\- The username being checked against .IP \(bu 2 \fBcommand\fP (\fI\%str\fP) \-\- The command that is being invoked (e.g. test.ping) .IP \(bu 2 \fBgroups\fP (\fI\%dict\fP) \-\- the dictionary with groups permissions structure. .UNINDENT .TP .B Return type \fI\%tuple\fP .TP .B Returns On a successful permitting match, returns 2\-element tuple that contains the name of the group that successfully matched, and a dictionary containing the configuration of the group so it can be referenced. .sp On failure it returns an empty tuple .UNINDENT .UNINDENT .INDENT 7.0 .TP .B commandline_to_list(cmdline_str, trigger_string) cmdline_str is the string of the command line trigger_string is the trigger string, to be removed .UNINDENT .INDENT 7.0 .TP .B control_message_target(slack_user_name, text, loaded_groups, trigger_string) Returns a tuple of (target, cmdline,) for the response .sp Raises IndexError if a user can\(aqt be looked up from all_slack_users .sp Returns (False, False) if the user doesn\(aqt have permission .sp These are returned together because the commandline and the targeting interact with the group config (specifically aliases and targeting configuration) so taking care of them together works out. .sp The cmdline that is returned is the actual list that should be processed by salt, and not the alias. .UNINDENT .INDENT 7.0 .TP .B fire(tag, msg) This replaces a function in main called \(aqfire\(aq .sp It fires an event into the salt bus. .UNINDENT .INDENT 7.0 .TP .B format_return_text(data, function, **kwargs) Print out YAML using the block mode .UNINDENT .INDENT 7.0 .TP .B generate_triggered_messages(token, trigger_string, groups, groups_pillar_name) slack_token = string trigger_string = string input_valid_users = set input_valid_commands = set .sp When the trigger_string prefixes the message text, yields a dictionary of: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C { \(aqmessage_data\(aq: m_data, \(aqcmdline\(aq: cmdline_list, # this is a list \(aqchannel\(aq: channel, \(aquser\(aq: m_data[\(aquser\(aq], \(aqslack_client\(aq: sc } .ft P .fi .UNINDENT .UNINDENT .sp else yields {\(aqmessage_data\(aq: m_data} and the caller can handle that .sp When encountering an error (e.g. invalid message), yields {}, the caller can proceed to the next message .sp When the websocket being read from has given up all its messages, yields {\(aqdone\(aq: True} to indicate that the caller has read all of the relevant data for now, and should continue its own processing and check back for more data later. .sp This relies on the caller sleeping between checks, otherwise this could flood .UNINDENT .INDENT 7.0 .TP .B get_config_groups(groups_conf, groups_pillar_name) get info from groups in config, and from the named pillar .sp todo: add specification for the minion to use to recover pillar .UNINDENT .INDENT 7.0 .TP .B get_jobs_from_runner(outstanding_jids) Given a list of job_ids, return a dictionary of those job_ids that have completed and their results. .sp Query the salt event bus via the jobs runner. jobs.list_job will show a job in progress, jobs.lookup_jid will return a job that has completed. .sp returns a dictionary of job id: result .UNINDENT .INDENT 7.0 .TP .B get_slack_channels(token) Get all channel names from Slack .UNINDENT .INDENT 7.0 .TP .B get_slack_users(token) Get all users from Slack .UNINDENT .INDENT 7.0 .TP .B get_target(permitted_group, cmdline, alias_cmdline) When we are permitted to run a command on a target, look to see what the default targeting is for that group, and for that specific command (if provided). .sp It\(aqs possible for None or False to be the result of either, which means that it\(aqs expected that the caller provide a specific target. .sp If no configured target is provided, the command line will be parsed for target=foo and tgt_type=bar .sp Test for this: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C h = {\(aqaliases\(aq: {}, \(aqcommands\(aq: {\(aqcmd.run\(aq, \(aqpillar.get\(aq}, \(aqdefault_target\(aq: {\(aqtarget\(aq: \(aq*\(aq, \(aqtgt_type\(aq: \(aqglob\(aq}, \(aqtargets\(aq: {\(aqpillar.get\(aq: {\(aqtarget\(aq: \(aqyou_momma\(aq, \(aqtgt_type\(aq: \(aqlist\(aq}}, \(aqusers\(aq: {\(aqdmangot\(aq, \(aqjmickle\(aq, \(aqpcn\(aq}} f = {\(aqaliases\(aq: {}, \(aqcommands\(aq: {\(aqcmd.run\(aq, \(aqpillar.get\(aq}, \(aqdefault_target\(aq: {}, \(aqtargets\(aq: {},\(aqusers\(aq: {\(aqdmangot\(aq, \(aqjmickle\(aq, \(aqpcn\(aq}} g = {\(aqaliases\(aq: {}, \(aqcommands\(aq: {\(aqcmd.run\(aq, \(aqpillar.get\(aq}, \(aqdefault_target\(aq: {\(aqtarget\(aq: \(aq*\(aq, \(aqtgt_type\(aq: \(aqglob\(aq}, \(aqtargets\(aq: {}, \(aqusers\(aq: {\(aqdmangot\(aq, \(aqjmickle\(aq, \(aqpcn\(aq}} .ft P .fi .UNINDENT .UNINDENT .sp Run each of them through \fBget_configured_target((\(aqfoo\(aq, f), \(aqpillar.get\(aq)\fP and confirm a valid target .UNINDENT .INDENT 7.0 .TP .B message_text(m_data) Raises ValueError if a value doesn\(aqt work out, and TypeError if this isn\(aqt a message type .UNINDENT .INDENT 7.0 .TP .B parse_args_and_kwargs(cmdline) cmdline: list .sp returns tuple of: args (list), kwargs (dict) .UNINDENT .INDENT 7.0 .TP .B run_command_async(msg) .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBmessage_generator\fP (\fIgenerator of dict\fP) \-\- Generates messages from slack that should be run .IP \(bu 2 \fBfire_all\fP (\fI\%bool\fP) \-\- Whether to also fire messages to the event bus .IP \(bu 2 \fBtag\fP (\fI\%str\fP) \-\- The tag to send to use to send to the event bus .IP \(bu 2 \fBinterval\fP (\fI\%int\fP) \-\- time to wait between ending a loop and beginning the next .UNINDENT .UNINDENT .UNINDENT .INDENT 7.0 .TP .B run_commands_from_slack_async(message_generator, fire_all, tag, control, interval=1) Pull any pending messages from the message_generator, sending each one to either the event bus, the command_async or both, depending on the values of fire_all and command .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.engines.slack.start(token, control=False, trigger=\(aq!\(aq, groups=None, groups_pillar_name=None, fire_all=False, tag=\(aqsalt/engines/slack\(aq) Listen to slack events and forward them to salt, new version .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.stalekey module .sp An engine that uses presence detection to keep track of which minions have been recently connected and remove their keys if they have not been connected for a certain period of time. .sp Requires that the \fBminion_data_cache\fP option be enabled. .INDENT 0.0 .TP .B configuration Example configuration: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C engines: \- stalekey: interval: 3600 expire: 86400 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.engines.stalekey.start(interval=3600, expire=604800) Start the engine .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.event_bus_context(opts) .UNINDENT .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 salt.engines.webhook .sp Send events from webhook api .INDENT 0.0 .TP .B salt.engines.webhook.start(address=None, port=5000, ssl_crt=None, ssl_key=None) Api to listen for webhooks to send to the reactor. .sp Implement the webhook behavior in an engine. \fBrest_cherrypy Webhook docs\fP .sp Unlike the rest_cherrypy Webhook, this is only an unauthenticated webhook endpoint. If an authenticated webhook endpoint is needed, use the salt\-api webhook which runs on the master and authenticates through eauth. .sp \fBWARNING:\fP .INDENT 7.0 .INDENT 3.5 Unauthenticated endpoint .sp This engine sends webhook calls to the event stream. If the engine is running on a minion with \fIfile_client: local\fP the event is sent to the minion event stream. Otherwise it is sent to the master event stream. .UNINDENT .UNINDENT .sp Example Config .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C engines: \- webhook: {} .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C engines: \- webhook: port: 8000 address: 10.128.1.145 ssl_crt: /etc/pki/tls/certs/localhost.crt ssl_key: /etc/pki/tls/certs/localhost.key .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS executors modules .TS center; |l|l|. _ T{ \fBdirect_call\fP T} T{ Direct call executor module T} _ T{ \fBdocker\fP T} T{ Docker executor module T} _ T{ \fBsplay\fP T} T{ Splay function calls across targeted minions T} _ T{ \fBsudo\fP T} T{ Sudo executor module T} _ .TE .SS salt.executors.direct_call module .sp Direct call executor module .INDENT 0.0 .TP .B salt.executors.direct_call.execute(opts, data, func, args, kwargs) Directly calls the given function with arguments .UNINDENT .SS salt.executors.docker module .sp Docker executor module .sp Used with the docker proxy minion. .INDENT 0.0 .TP .B salt.executors.docker.allow_missing_func(function) Allow all calls to be passed through to docker container. .sp The docker call will use direct_call, which will return back if the module was unable to be run. .UNINDENT .INDENT 0.0 .TP .B salt.executors.docker.execute(opts, data, func, args, kwargs) Directly calls the given function with arguments .UNINDENT .SS salt.executors.splay module .sp Splay function calls across targeted minions .INDENT 0.0 .TP .B salt.executors.splay.execute(opts, data, func, args, kwargs) Splay a salt function call execution time across minions over a number of seconds (default: 300) .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 You \fIprobably\fP want to use \-\-async here and look up the job results later. If you\(aqre dead set on getting the output from the CLI command, then make sure to set the timeout (with the \-t flag) to something greater than the splaytime (max splaytime + time to execute job). Otherwise, it\(aqs very likely that the cli will time out before the job returns. .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C # With default splaytime salt \-\-async \-\-module\-executors=\(aq[splay, direct_call]\(aq \(aq*\(aq pkg.install cowsay version=3.03\-8.el6 .ft P .fi .UNINDENT .UNINDENT .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C # With specified splaytime (5 minutes) and timeout with 10 second buffer salt \-t 310 \-\-module\-executors=\(aq[splay, direct_call]\(aq \-\-executor\-opts=\(aq{splaytime: 300}\(aq \(aq*\(aq pkg.version cowsay .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.executors.sudo module .sp Sudo executor module .INDENT 0.0 .TP .B salt.executors.sudo.execute(opts, data, func, args, kwargs) Allow for the calling of execution modules via sudo. .sp This module is invoked by the minion if the \fBsudo_user\fP minion config is present. .sp Example minion config: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C sudo_user: saltdev .ft P .fi .UNINDENT .UNINDENT .sp Once this setting is made, any execution module call done by the minion will be run under \fBsudo \-u salt\-call\fP\&. For example, with the above minion config, .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt sudo_minion cmd.run \(aqcat /etc/sudoers\(aq .ft P .fi .UNINDENT .UNINDENT .sp is equivalent to .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C sudo \-u saltdev salt\-call cmd.run \(aqcat /etc/sudoers\(aq .ft P .fi .UNINDENT .UNINDENT .sp being run on \fBsudo_minion\fP\&. .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 New in version 2015.8.0. .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 Starting in Salt 2018.3.0, this fileserver requires the standalone Azure Storage SDK for Python. Theoretically any version >= v0.20.0 should work, but it was developed against the v0.33.0 version. .sp Each storage container will be mapped to an environment. By default, containers will be mapped to the \fBbase\fP environment. You can override this behavior with the \fBsaltenv\fP configuration option. You can have an unlimited number of storage containers, and can have a storage container serve multiple environments, or have multiple storage containers mapped to the same environment. Normal first\-found rules apply, and storage containers are searched in the order they are defined. .sp You must have either an account_key or a sas_token defined for each container, if it is private. If you use a sas_token, it must have READ and LIST permissions. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C azurefs: \- account_name: my_storage account_key: \(aqfNH9cRp0+qVIVYZ+5rnZAhHc9ycOUcJnHtzpfOr0W0sxrtL2KVLuMe1xDfLwmfed+JJInZaEdWVCPHD4d/oqeA==\(aq container_name: my_container \- account_name: my_storage sas_token: \(aqss=b&sp=&sv=2015\-07\-08&sig=cohxXabx8FQdXsSEHyUXMjsSfNH2tZ2OB97Ou44pkRE%3D&srt=co&se=2017\-04\-18T21%3A38%3A01Z\(aq container_name: my_dev_container saltenv: dev \- account_name: my_storage container_name: my_public_container .ft P .fi .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 Do not include the leading ? for sas_token if generated from the web .UNINDENT .UNINDENT .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 \fBgitfs\fP to the \fBfileserver_backend\fP option in the Master config file. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C fileserver_backend: \- gitfs .ft P .fi .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 \fBgit\fP also works here. Prior to the 2018.3.0 release, \fIonly\fP \fBgit\fP would work. .UNINDENT .UNINDENT .sp The Git fileserver backend supports both \fI\%pygit2\fP and \fI\%GitPython\fP, to provide the Python interface to git. If both are present, the order of preference for which one will be chosen is the same as the order in which they were listed: pygit2, then GitPython. .sp An optional master config parameter (\fBgitfs_provider\fP) can be used to specify which provider should be used, in the event that compatible versions of both \fI\%pygit2\fP and \fI\%GitPython\fP are installed. .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\%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 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 clear stale refs the git CLI utility must also be installed. .UNINDENT .UNINDENT .SS salt.fileserver.hgfs .sp Mercurial Fileserver Backend .sp To enable, add \fBhgfs\fP to the \fBfileserver_backend\fP option in the Master config file. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C fileserver_backend: \- hgfs .ft P .fi .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 \fBhg\fP also works here. Prior to the 2018.3.0 release, \fIonly\fP \fBhg\fP would work. .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 \fBminionfs\fP must be added to the \fBfileserver_backends\fP list. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C fileserver_backend: \- minionfs .ft P .fi .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 \fBminion\fP also works here. Prior to the 2018.3.0 release, \fIonly\fP \fBminion\fP would work. .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 New in version 0.16.0. .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 .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 This fileserver back\-end is only compatible with MD5 ETag hashes in the S3 metadata. This means that you must use SSE\-S3 or plaintext for bucket encryption, and that you must not use multipart upload when uploading to your bucket. More information here: \fI\%https://docs.aws.amazon.com/AmazonS3/latest/API/RESTCommonResponseHeaders.html\fP .sp Objects without an MD5 ETag will be fetched on every fileserver update. .sp If you deal with objects greater than 8MB, then you should use the following AWS CLI config to avoid mutipart upload: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C s3 = multipart_threshold = 1024MB .ft P .fi .UNINDENT .UNINDENT .sp More info here: \fI\%https://docs.aws.amazon.com/cli/latest/topic/s3\-config.html\fP .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 \fBsvnfs\fP to the \fBfileserver_backend\fP option in the Master config file. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C fileserver_backend: \- svnfs .ft P .fi .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 \fBsvn\fP also works here. Prior to the 2018.3.0 release, \fIonly\fP \fBsvn\fP would work. .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{ \fBcimc\fP T} T{ Generate baseline proxy minion grains for cimc hosts. 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{ \fBfibre_channel\fP T} T{ Grains for Fibre Channel WWN\(aqs. T} _ T{ \fBfx2\fP T} T{ Generate baseline proxy minion grains for Dell FX2 chassis. T} _ T{ \fBiscsi\fP T} T{ Grains for iSCSI Qualified Names (IQN). T} _ T{ \fBjunos\fP T} T{ Grains for junos. T} _ T{ \fBlvm\fP T} T{ Detect LVM Volumes T} _ T{ \fBmarathon\fP T} T{ Generate marathon proxy minion grains. T} _ T{ \fBmdadm\fP T} T{ Detect MDADM RAIDs T} _ T{ \fBmdata\fP T} T{ SmartOS Metadata grain provider T} _ T{ \fBmetadata\fP T} T{ Grains from cloud metadata servers at 169.254.169.254 T} _ T{ \fBminion_process\fP T} T{ Set grains describing the minion process. T} _ T{ \fBnapalm\fP T} T{ NAPALM Grains T} _ T{ \fBnvme\fP T} T{ Grains for NVMe Qualified Names (NQN). T} _ T{ \fBnxos\fP T} T{ Grains for Cisco NX\-OS minions T} _ T{ \fBopts\fP T} T{ Simple grain to merge the opts into the grains directly if the grain_opts configuration value is set. T} _ T{ \fBpanos\fP T} T{ Generate baseline proxy minion grains for panos hosts. T} _ T{ \fBpending_reboot\fP T} T{ Grain that indicates the system is pending a reboot See functions in salt.utils.win_system to see what conditions would indicate a reboot is pending 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} _ T{ \fBsmartos\fP T} T{ SmartOS grain provider T} _ T{ \fBssh_sample\fP T} T{ Generate baseline proxy minion grains T} _ T{ \fBzfs\fP T} T{ ZFS grain provider T} _ .TE .SS salt.grains.chronos .sp Generate chronos proxy minion grains. .sp New in version 2015.8.2. .INDENT 0.0 .TP .B salt.grains.chronos.kernel() .UNINDENT .INDENT 0.0 .TP .B salt.grains.chronos.os() .UNINDENT .INDENT 0.0 .TP .B salt.grains.chronos.os_data() .UNINDENT .INDENT 0.0 .TP .B salt.grains.chronos.os_family() .UNINDENT .SS salt.grains.cimc .sp Generate baseline proxy minion grains for cimc hosts. .INDENT 0.0 .TP .B salt.grains.cimc.cimc(proxy=None) .UNINDENT .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.cwd() Current working directory .UNINDENT .INDENT 0.0 .TP .B salt.grains.core.default_gateway() Populates grains which describe whether a server has a default gateway configured or not. Uses \fIip \-4 route show\fP and \fIip \-6 route show\fP and greps for a \fIdefault\fP at the beginning of any line. Assuming the standard \fIdefault via \fP format for default gateways, it will also parse out the ip address of the default gateway, and put it in ip4_gw or ip6_gw. .sp If the \fIip\fP command is unavailable, no grains will be populated. .sp Currently does not support multiple default gateways. The grains will be set to the first default gateway found. .sp List of grains: .INDENT 7.0 .INDENT 3.5 ip4_gw: True # ip/True/False if default ipv4 gateway ip6_gw: True # ip/True/False if default ipv6 gateway ip_gw: True # True if either of the above is True, False otherwise .UNINDENT .UNINDENT .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.fqdns() Return all known FQDNs for the system by enumerating all interfaces and then trying to reverse resolve them (excluding \(aqlo\(aq interface). To disable the fqdns grain, set enable_fqdns_grains: False in the minion configuration file. .UNINDENT .INDENT 0.0 .TP .B salt.grains.core.get_machine_id() Provide the machine\-id for machine/virtualization combination .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 .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 On Windows the \fBdomain\fP grain may refer to the dns entry for the host instead of the Windows domain to which the host is joined. It may also be empty if not a part of any domain. Refer to the \fBwindowsdomain\fP grain instead .UNINDENT .UNINDENT .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.kernelparams() Return the kernel boot parameters .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 New in version 2015.8.4. .INDENT 0.0 .TP .B salt.grains.esxi.esxi() .UNINDENT .INDENT 0.0 .TP .B salt.grains.esxi.kernel() .UNINDENT .INDENT 0.0 .TP .B salt.grains.esxi.os() .UNINDENT .INDENT 0.0 .TP .B salt.grains.esxi.os_family() .UNINDENT .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.fibre_channel .sp Grains for Fibre Channel WWN\(aqs. On Windows this runs a PowerShell command that queries WMI to get the Fibre Channel WWN\(aqs available. .sp New in version 2018.3.0. .sp To enable these grains set \fBfibre_channel_grains: True\fP in the minion config. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C fibre_channel_grains: True .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.grains.fibre_channel.fibre_channel_wwns() Return list of fiber channel HBA WWNs .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. .INDENT 0.0 .TP .B salt.grains.fx2.fx2() .UNINDENT .INDENT 0.0 .TP .B salt.grains.fx2.kernel() .UNINDENT .INDENT 0.0 .TP .B salt.grains.fx2.location() .UNINDENT .INDENT 0.0 .TP .B salt.grains.fx2.os_data() .UNINDENT .INDENT 0.0 .TP .B salt.grains.fx2.os_family() .UNINDENT .SS salt.grains.iscsi .sp Grains for iSCSI Qualified Names (IQN). .sp New in version 2018.3.0. .sp To enable these grains set \fIiscsi_grains: True\fP in the minion config. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C iscsi_grains: True .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.grains.iscsi.iscsi_iqn() Return iSCSI IQN .UNINDENT .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) .INDENT 0.0 .TP .B salt.grains.junos.defaults() .UNINDENT .INDENT 0.0 .TP .B salt.grains.junos.facts(proxy=None) .UNINDENT .INDENT 0.0 .TP .B salt.grains.junos.os_family() .UNINDENT .SS salt.grains.lvm .sp Detect LVM Volumes .INDENT 0.0 .TP .B salt.grains.lvm.lvm() Return list of LVM devices .UNINDENT .SS salt.grains.marathon .sp Generate marathon proxy minion grains. .sp New in version 2015.8.2. .INDENT 0.0 .TP .B salt.grains.marathon.kernel() .UNINDENT .INDENT 0.0 .TP .B salt.grains.marathon.marathon() .UNINDENT .INDENT 0.0 .TP .B salt.grains.marathon.os() .UNINDENT .INDENT 0.0 .TP .B salt.grains.marathon.os_data() .UNINDENT .INDENT 0.0 .TP .B salt.grains.marathon.os_family() .UNINDENT .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.mdata .sp SmartOS Metadata grain provider .INDENT 0.0 .TP .B maintainer Jorge Schrauwen <\fI\%sjorge@blackdot.be\fP> .TP .B maturity new .TP .B depends salt.utils, salt.module.cmdmod .TP .B platform SmartOS .UNINDENT .sp New in version nitrogen. .INDENT 0.0 .TP .B salt.grains.mdata.mdata() Provide grains from the SmartOS metadata .UNINDENT .SS salt.grains.metadata .sp Grains from cloud metadata servers at 169.254.169.254 .sp New in version 2017.7.0. .INDENT 0.0 .TP .B depends requests .UNINDENT .sp To enable these grains that pull from the \fI\%http://169.254.169.254/latest\fP metadata server set \fImetadata_server_grains: True\fP in the minion config. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C metadata_server_grains: True .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.grains.metadata.metadata() .UNINDENT .SS salt.grains.minion_process .sp Set grains describing the minion process. .INDENT 0.0 .TP .B salt.grains.minion_process.grains() Return the grains dictionary .UNINDENT .SS salt.grains.napalm .SS NAPALM Grains .INDENT 0.0 .TP .B codeauthor Mircea Ulinic <\fI\%ping@mirceaulinic.net\fP> .TP .B maturity new .TP .B depends napalm .TP .B platform unix .UNINDENT .SS Dependencies .INDENT 0.0 .IP \(bu 2 \fBNAPALM proxy module\fP .UNINDENT .sp New in version 2016.11.0. .INDENT 0.0 .TP .B salt.grains.napalm.getos(proxy=None) Returns the Operating System name running on the network device. .sp Example: junos, iosxr, eos, ios etc. .sp CLI Example \- select all network devices running JunOS: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \-G \(aqos:junos\(aq test.ping .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.grains.napalm.host(proxy=None) This grain is set by the NAPALM grain module only when running in a proxy minion. When Salt is installed directly on the network device, thus running a regular minion, the \fBhost\fP grain provides the physical hostname of the network device, as it would be on an ordinary minion server. When running in a proxy minion, \fBhost\fP points to the value configured in the pillar: \fBNAPALM proxy module\fP\&. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 The diference between \fBhost\fP and \fBhostname\fP is that \fBhost\fP provides the physical location \- either domain name or IP address, while \fBhostname\fP provides the hostname as configured on the device. They are not necessarily the same. .UNINDENT .UNINDENT .sp New in version 2017.7.0. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aqdevice*\(aq grains.get host .ft P .fi .UNINDENT .UNINDENT .sp Output: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C device1: ip\-172\-31\-13\-136.us\-east\-2.compute.internal device2: ip\-172\-31\-11\-193.us\-east\-2.compute.internal device3: ip\-172\-31\-2\-181.us\-east\-2.compute.internal .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.grains.napalm.host_dns(proxy=None) Return the DNS information of the host. This grain is a dictionary having two keys: .INDENT 7.0 .IP \(bu 2 \fBA\fP .IP \(bu 2 \fBAAAA\fP .UNINDENT .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 This grain is disabled by default, as the proxy startup may be slower when the lookup fails. The user can enable it using the \fBnapalm_host_dns_grain\fP option (in the pillar or proxy configuration file): .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C napalm_host_dns_grain: true .ft P .fi .UNINDENT .UNINDENT .UNINDENT .UNINDENT .sp New in version 2017.7.0. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aqdevice*\(aq grains.get host_dns .ft P .fi .UNINDENT .UNINDENT .sp Output: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C device1: A: \- 172.31.9.153 AAAA: \- fd52:188c:c068::1 device2: A: \- 172.31.46.249 AAAA: \- fdca:3b17:31ab::17 device3: A: \- 172.31.8.167 AAAA: \- fd0f:9fd6:5fab::1 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.grains.napalm.hostname(proxy=None) Return the hostname as configured on the network device. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aqdevice*\(aq grains.get hostname .ft P .fi .UNINDENT .UNINDENT .sp Output: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C device1: edge01.yyz01 device2: edge01.bjm01 device3: edge01.flw01 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.grains.napalm.interfaces(proxy=None) Returns the complete interfaces list of the network device. .sp Example: [\(aqlc\-0/0/0\(aq, \(aqpfe\-0/0/0\(aq, \(aqxe\-1/3/0\(aq, \(aqlo0\(aq, \(aqirb\(aq, \(aqdemux0\(aq, \(aqfxp0\(aq] .sp CLI Example \- select all devices that have a certain interface, e.g.: xe\-1/1/1: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \-G \(aqinterfaces:xe\-1/1/1\(aq test.ping .ft P .fi .UNINDENT .UNINDENT .sp Output: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C edge01.yyz01: True edge01.maa01: True edge01.syd01: True edge01.del01: True edge01.dus01: True edge01.kix01: True .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.grains.napalm.model(proxy=None) Returns the network device chassis model. .sp Example: MX480, ASR\-9904\-AC etc. .sp CLI Example \- select all Juniper MX480 routers and execute traceroute to 8.8.8.8: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \-G \(aqmodel:MX480\(aq net.traceroute 8.8.8.8 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.grains.napalm.optional_args(proxy=None) Return the connection optional args. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 Sensible data will not be returned. .UNINDENT .UNINDENT .sp New in version 2017.7.0. .sp CLI Example \- select all devices connecting via port 1234: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \-G \(aqoptional_args:port:1234\(aq test.ping .ft P .fi .UNINDENT .UNINDENT .sp Output: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C device1: True device2: True .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.grains.napalm.serial(proxy=None) Returns the chassis serial number. .sp Example: FOX1234W00F .sp CLI Example \- select all devices whose serial number begins with \fIFOX\fP and display the serial number value: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \-G \(aqserial:FOX*\(aq grains.get serial .ft P .fi .UNINDENT .UNINDENT .sp Output: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C edge01.icn01: FOXW00F001 edge01.del01: FOXW00F002 edge01.yyz01: FOXW00F003 edge01.mrs01: FOXW00F004 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.grains.napalm.uptime(proxy=None) Returns the uptime in seconds. .sp CLI Example \- select all devices started/restarted within the last hour: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \-G \(aquptime<3600\(aq test.ping .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.grains.napalm.username(proxy=None) Return the username. .sp New in version 2017.7.0. .sp CLI Example \- select all devices using \fIfoobar\fP as username for connection: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \-G \(aqusername:foobar\(aq test.ping .ft P .fi .UNINDENT .UNINDENT .sp Output: .UNINDENT .INDENT 0.0 .TP .B salt.grains.napalm.vendor(proxy=None) Returns the network device vendor. .sp Example: juniper, cisco, arista etc. .sp CLI Example \- select all devices produced by Cisco and shutdown: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \-G \(aqvendor:cisco\(aq net.cli "shut" .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.grains.napalm.version(proxy=None) Returns the OS version. .sp Example: 13.3R6.5, 6.0.2 etc. .sp CLI Example \- select all network devices running JunOS 13.3R6.5 and return the model: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \-G \(aqos:junos and version:13.3R6.5\(aq grains.get model .ft P .fi .UNINDENT .UNINDENT .sp Output: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C edge01.bjm01: MX2000 edge01.sjc01: MX960 edge01.mrs01: MX480 edge01.muc01: MX240 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.grains.nvme .sp Grains for NVMe Qualified Names (NQN). .sp New in version 3000. .sp To enable these grains set \fInvme_grains: True\fP in the minion config. .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C nvme_grains: True .ft P .fi .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.grains.nvme.nvme_nqn() Return NVMe NQN .UNINDENT .SS salt.grains.nxos .sp Grains for Cisco NX\-OS minions .sp For documentation on setting up the nxos proxy minion look in the documentation for \fBsalt.proxy.nxos\fP\&. .INDENT 0.0 .TP .B salt.grains.nxos.system_information(proxy=None) .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.panos .sp Generate baseline proxy minion grains for panos hosts. .INDENT 0.0 .TP .B salt.grains.panos.panos(proxy=None) .UNINDENT .SS salt.grains.pending_reboot .sp Grain that indicates the system is pending a reboot See functions in salt.utils.win_system to see what conditions would indicate a reboot is pending .INDENT 0.0 .TP .B salt.grains.pending_reboot.pending_reboot() A grain that indicates that a Windows system is pending a reboot. .UNINDENT .SS salt.grains.philips_hue .sp Static grains for the Philips HUE lamps .sp New in version 2015.8.3. .INDENT 0.0 .TP .B salt.grains.philips_hue.kernel() .UNINDENT .INDENT 0.0 .TP .B salt.grains.philips_hue.os() .UNINDENT .INDENT 0.0 .TP .B salt.grains.philips_hue.os_family() .UNINDENT .INDENT 0.0 .TP .B salt.grains.philips_hue.product() .UNINDENT .INDENT 0.0 .TP .B salt.grains.philips_hue.vendor() .UNINDENT .SS salt.grains.rest_sample .sp Generate baseline proxy minion grains .INDENT 0.0 .TP .B salt.grains.rest_sample.kernel() .UNINDENT .INDENT 0.0 .TP .B salt.grains.rest_sample.location() .UNINDENT .INDENT 0.0 .TP .B salt.grains.rest_sample.os() .UNINDENT .INDENT 0.0 .TP .B salt.grains.rest_sample.os_data() .UNINDENT .INDENT 0.0 .TP .B salt.grains.rest_sample.os_family() .UNINDENT .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 salt.grains.smartos .sp SmartOS grain provider .INDENT 0.0 .TP .B maintainer Jorge Schrauwen <\fI\%sjorge@blackdot.be\fP> .TP .B maturity new .TP .B depends salt.utils, salt.ext.six, salt.module.cmdmod .TP .B platform SmartOS .UNINDENT .sp New in version nitrogen. .INDENT 0.0 .TP .B salt.grains.smartos.smartos() Provide grains for SmartOS .UNINDENT .SS salt.grains.ssh_sample .sp Generate baseline proxy minion grains .INDENT 0.0 .TP .B salt.grains.ssh_sample.kernel() .UNINDENT .INDENT 0.0 .TP .B salt.grains.ssh_sample.location() .UNINDENT .INDENT 0.0 .TP .B salt.grains.ssh_sample.os_data() .UNINDENT .INDENT 0.0 .TP .B salt.grains.ssh_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 salt.grains.zfs .sp ZFS grain provider .INDENT 0.0 .TP .B maintainer Jorge Schrauwen <\fI\%sjorge@blackdot.be\fP> .TP .B maturity new .TP .B depends salt.module.cmdmod .TP .B platform illumos,freebsd,linux .UNINDENT .sp New in version 2018.3.0. .INDENT 0.0 .TP .B salt.grains.zfs.zfs() Provide grains for zfs/zpool .UNINDENT .SS execution modules .INDENT 0.0 .INDENT 3.5 .IP "Virtual modules" .SS salt.modules.group .sp \fBgroup\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{ \fBgroupadd\fP T} T{ Linux, NetBSD, and OpenBSD systems using \fBgroupadd(8)\fP, \fBgroupdel(8)\fP, and \fBgroupmod(8)\fP T} _ T{ \fBpw_group\fP T} T{ FreeBSD\-based OSes using \fBpw(8)\fP T} _ T{ \fBsolaris_group\fP T} T{ Solaris\-based OSes using \fBgroupadd(1M)\fP, \fBgroupdel(1M)\fP, and \fBgroupmod(1M)\fP T} _ T{ \fBwin_groupadd\fP T} T{ Windows T} _ .TE .SS salt.modules.kernelpkg .sp \fBkernelpkg\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{ \fBkernelpkg_linux_apt\fP T} T{ Debian/Ubuntu\-based distros which use \fBapt\-get\fP for package management T} _ T{ \fBkernelpkg_linux_yum\fP T} T{ RedHat\-based distros and derivatives using \fByum\fP or \fBdnf\fP T} _ .TE .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{ \fBaixpkg\fP T} T{ AIX OS using \fBinstallp\fP and \fBrpm\fP T} _ T{ \fBaptpkg\fP T} T{ Debian/Ubuntu\-based distros which use \fBapt\-get(8)\fP for package management T} _ T{ \fBmac_brew_pkg\fP T} T{ Mac OS software management using \fI\%Homebrew\fP T} _ T{ \fBebuildpkg\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{ \fBpacmanpkg\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{ \fBsolarisipspkg\fP T} T{ Solaris\-based OSes using IPS \fBpkg(1)\fP T} _ T{ \fBwin_pkg\fP T} T{ Salt\(aqs Windows Package Manager T} _ T{ \fByumpkg\fP T} T{ RedHat\-based distros and derivatives using \fByum(8)\fP or \fBdnf(8)\fP T} _ T{ \fBzypperpkg\fP T} T{ SUSE\-based distros using \fBzypper(8)\fP T} _ .TE .SS salt.modules.service .sp \fBservice\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{ \fBdebian_service\fP T} T{ Debian Wheezy and earlier T} _ T{ \fBfreebsdservice\fP T} T{ FreeBSD\-based OSes using \fBservice(8)\fP T} _ T{ \fBgentoo_service\fP T} T{ Gentoo Linux using \fBsysvinit\fP and \fBrc\-update(8)\fP T} _ T{ \fBmac_service\fP T} T{ Mac OS hosts using \fBlaunchctl(1)\fP T} _ T{ \fBnetbsdservice\fP T} T{ NetBSD\-based OSes T} _ T{ \fBopenbsdservice\fP T} T{ OpenBSD\-based OSes T} _ T{ \fBrh_service\fP T} T{ RedHat\-based distros and derivatives using \fBservice(8)\fP and \fBchkconfig(8)\fP\&. Supports both pure sysvinit and mixed sysvinit/upstart systems. T} _ T{ \fI\%service\fP T} T{ Fallback which simply wraps sysvinit scripts T} _ T{ \fBsmf_service\fP T} T{ Solaris\-based OSes which use SMF T} _ T{ \fBsystemd_service\fP T} T{ Linux distros which use systemd T} _ T{ \fBupstart_service\fP T} T{ Ubuntu\-based distros using upstart T} _ T{ \fBwin_service\fP T} T{ Windows T} _ .TE .SS salt.modules.shadow .sp \fBshadow\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{ \fBaix_shadow\fP T} T{ AIX T} _ T{ \fBlinux_shadow\fP T} T{ Linux T} _ T{ \fBbsd_shadow\fP T} T{ FreeBSD, OpenBSD, NetBSD T} _ T{ \fBsolaris_shadow\fP T} T{ Solaris\-based OSes T} _ T{ \fBwin_shadow\fP T} T{ Windows T} _ .TE .SS salt.modules.sysctl .sp \fBsysctl\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{ \fBfreebsd_sysctl\fP T} T{ FreeBSD T} _ T{ \fBlinux_sysctl\fP T} T{ Linux T} _ T{ \fBmac_sysctl\fP T} T{ macOS T} _ T{ \fBnetbsd_sysctl\fP T} T{ NetBSD T} _ T{ \fBopenbsd_sysctl\fP T} T{ OpenBSD T} _ .TE .SS salt.modules.user .sp \fBuser\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{ \fBuseradd\fP T} T{ Linux, NetBSD, and OpenBSD systems using \fBuseradd(8)\fP, \fBuserdel(8)\fP, and \fBusermod(8)\fP T} _ T{ \fBpw_user\fP T} T{ FreeBSD\-based OSes using \fBpw(8)\fP T} _ T{ \fBsolaris_user\fP T} T{ Solaris\-based OSes using \fBuseradd(1M)\fP, \fBuserdel(1M)\fP, and \fBusermod(1M)\fP T} _ T{ \fBmac_user\fP T} T{ MacOS T} _ T{ \fBwin_useradd\fP T} T{ Windows T} _ .TE .UNINDENT .UNINDENT .TS center; |l|l|. _ T{ \fBacme\fP T} T{ ACME / Let\(aqs Encrypt module T} _ T{ \fBaix_group\fP T} T{ Manage groups on Solaris T} _ T{ \fBaix_shadow\fP T} T{ Manage account locks on AIX systems T} _ T{ \fBaixpkg\fP T} T{ Package support for AIX T} _ T{ \fBaliases\fP T} T{ Manage the information in the aliases file T} _ T{ \fBalternatives\fP T} T{ Support for Alternatives system T} _ T{ \fBansiblegate\fP T} T{ Ansible Support T} _ T{ \fBapache\fP T} T{ Support for Apache T} _ T{ \fBapcups\fP T} T{ Module for apcupsd T} _ T{ \fBapf\fP T} T{ Support for Advanced Policy Firewall (APF) T} _ T{ \fBapkpkg\fP T} T{ Support for apk T} _ T{ \fBaptly\fP T} T{ Aptly Debian repository manager. T} _ T{ \fBaptpkg\fP T} T{ Support for APT (Advanced Packaging Tool) T} _ T{ \fBarchive\fP T} T{ A module to wrap (non\-Windows) archive calls T} _ T{ \fBarista_pyeapi\fP T} T{ Arista pyeapi T} _ T{ \fBartifactory\fP T} T{ Module for fetching artifacts from Artifactory T} _ T{ \fBat\fP T} T{ Wrapper module for at(1) T} _ T{ \fBat_solaris\fP T} T{ Wrapper for at(1) on Solaris\-like systems T} _ T{ \fBaugeas_cfg\fP T} T{ Manages configuration files via augeas T} _ T{ \fBaws_sqs\fP T} T{ Support for the Amazon Simple Queue Service. T} _ T{ \fBazurearm_compute\fP T} T{ Azure (ARM) Compute Execution Module T} _ T{ \fBazurearm_dns\fP T} T{ Azure (ARM) DNS Execution Module T} _ T{ \fBazurearm_network\fP T} T{ Azure (ARM) Network Execution Module T} _ T{ \fBazurearm_resource\fP T} T{ Azure (ARM) Resource Execution Module T} _ T{ \fBbamboohr\fP T} T{ Support for BambooHR T} _ T{ \fBbaredoc\fP T} T{ Baredoc walks the installed module and state directories and generates dictionaries and lists of the function names and their arguments. T} _ T{ \fBbcache\fP T} T{ Module for managing BCache sets T} _ T{ \fBbeacons\fP T} T{ Module for managing the Salt beacons on a minion T} _ T{ \fBbigip\fP T} T{ An execution module which can manipulate an f5 bigip via iControl REST T} _ T{ \fBbluez_bluetooth\fP T} T{ Support for Bluetooth (using BlueZ in Linux). T} _ T{ \fBboto3_elasticache\fP T} T{ Execution module for Amazon Elasticache using boto3 T} _ T{ \fBboto3_elasticsearch\fP T} T{ Connection module for Amazon Elasticsearch Service T} _ T{ \fBboto3_route53\fP T} T{ Execution module for Amazon Route53 written against Boto 3 T} _ T{ \fBboto3_sns\fP T} T{ Connection module for Amazon SNS T} _ T{ \fBboto_apigateway\fP T} T{ Connection module for Amazon APIGateway T} _ T{ \fBboto_asg\fP T} T{ Connection module for Amazon Autoscale Groups T} _ T{ \fBboto_cfn\fP T} T{ Connection module for Amazon Cloud Formation T} _ T{ \fBboto_cloudfront\fP T} T{ Connection module for Amazon CloudFront T} _ T{ \fBboto_cloudtrail\fP T} T{ Connection module for Amazon CloudTrail T} _ T{ \fBboto_cloudwatch\fP T} T{ Connection module for Amazon CloudWatch T} _ T{ \fBboto_cloudwatch_event\fP T} T{ Connection module for Amazon CloudWatch Events T} _ T{ \fBboto_cognitoidentity\fP T} T{ Connection module for Amazon CognitoIdentity T} _ T{ \fBboto_datapipeline\fP T} T{ Connection module for Amazon Data Pipeline T} _ T{ \fBboto_dynamodb\fP T} T{ Connection module for Amazon DynamoDB T} _ T{ \fBboto_ec2\fP T} T{ Connection module for Amazon EC2 T} _ T{ \fBboto_efs\fP T} T{ Connection module for Amazon EFS T} _ T{ \fBboto_elasticache\fP T} T{ Connection module for Amazon Elasticache T} _ T{ \fBboto_elasticsearch_domain\fP T} T{ Connection module for Amazon Elasticsearch Service T} _ T{ \fBboto_elb\fP T} T{ Connection module for Amazon ELB T} _ T{ \fBboto_elbv2\fP T} T{ Connection module for Amazon ALB T} _ T{ \fBboto_iam\fP T} T{ Connection module for Amazon IAM T} _ T{ \fBboto_iot\fP T} T{ Connection module for Amazon IoT T} _ T{ \fBboto_kinesis\fP T} T{ Connection module for Amazon Kinesis T} _ T{ \fBboto_kms\fP T} T{ Connection module for Amazon KMS T} _ T{ \fBboto_lambda\fP T} T{ Connection module for Amazon Lambda T} _ T{ \fBboto_rds\fP T} T{ Connection module for Amazon RDS T} _ T{ \fBboto_route53\fP T} T{ Connection module for Amazon Route53 T} _ T{ \fBboto_s3\fP T} T{ Connection module for Amazon S3 using boto3 T} _ T{ \fBboto_s3_bucket\fP T} T{ Connection module for Amazon S3 Buckets T} _ T{ \fBboto_secgroup\fP T} T{ Connection module for Amazon Security Groups T} _ T{ \fBboto_sns\fP T} T{ Connection module for Amazon SNS T} _ T{ \fBboto_sqs\fP T} T{ Connection module for Amazon SQS T} _ T{ \fBboto_ssm\fP T} T{ Connection module for Amazon SSM T} _ T{ \fBboto_vpc\fP T} T{ Connection module for Amazon VPC T} _ T{ \fBbower\fP T} T{ Manage and query Bower packages T} _ T{ \fBbridge\fP T} T{ Module for gathering and managing bridging information T} _ T{ \fBbsd_shadow\fP T} T{ Manage the password database on BSD systems T} _ T{ \fBbtrfs\fP T} T{ Module for managing BTRFS file systems. T} _ T{ \fBcabal\fP T} T{ Manage and query Cabal packages T} _ T{ \fBcapirca_acl\fP T} T{ Capirca ACL T} _ T{ \fBcassandra_cql\fP T} T{ Cassandra Database Module T} _ T{ \fBcassandra_mod\fP T} T{ Cassandra NoSQL Database Module T} _ T{ \fBcelery\fP T} T{ Support for scheduling celery tasks. T} _ T{ \fBceph\fP T} T{ Module to provide ceph control with salt. T} _ T{ \fBchassis\fP T} T{ Glue execution module to link to the \fBfx2 proxymodule\fP\&. T} _ T{ \fBchef\fP T} T{ Execute chef in server or solo mode T} _ T{ \fBchocolatey\fP T} T{ A dead simple module wrapping calls to the Chocolatey package manager (\fI\%http://chocolatey.org\fP) T} _ T{ \fBchronos\fP T} T{ Module providing a simple management interface to a chronos cluster. T} _ T{ \fBchroot\fP T} T{ .INDENT 0.0 .TP .B maintainer Alberto Planas <\fI\%aplanas@suse.com\fP> .UNINDENT T} _ T{ \fBcimc\fP T} T{ Module to provide Cisco UCS compatibility to Salt T} _ T{ \fBciscoconfparse_mod\fP T} T{ Execution module for \fI\%ciscoconfparse\fP T} _ T{ \fBcisconso\fP T} T{ Execution module for Cisco Network Services Orchestrator Proxy minions T} _ T{ \fBcloud\fP T} T{ Salt\-specific interface for calling Salt Cloud directly T} _ T{ \fBcmdmod\fP T} T{ A module for shelling out. T} _ T{ \fBcomposer\fP T} T{ Use composer to install PHP dependencies for a directory T} _ T{ \fBconfig\fP T} T{ Return config information T} _ T{ \fBconsul\fP T} T{ Interact with Consul T} _ T{ \fBcontainer_resource\fP T} T{ Common resources for LXC and systemd\-nspawn containers T} _ T{ \fBcp\fP T} T{ Minion side functions for salt\-cp T} _ T{ \fBcpan\fP T} T{ Manage Perl modules using CPAN T} _ T{ \fBcron\fP T} T{ Work with cron T} _ T{ \fBcryptdev\fP T} T{ Salt module to manage Unix cryptsetup jobs and the crypttab file T} _ T{ \fBcsf\fP T} T{ Support for Config Server Firewall (CSF) T} _ T{ \fBcyg\fP T} T{ Manage cygwin packages. T} _ T{ \fBdaemontools\fP T} T{ daemontools service module. T} _ T{ \fBdata\fP T} T{ Manage a local persistent data structure that can hold any arbitrary data specific to the minion T} _ T{ \fBdatadog_api\fP T} T{ An execution module that interacts with the Datadog API T} _ T{ \fBddns\fP T} T{ Support for RFC 2136 dynamic DNS updates. T} _ T{ \fBdeb_apache\fP T} T{ Support for Apache T} _ T{ \fBdeb_postgres\fP T} T{ Module to provide Postgres compatibility to salt for debian family specific tools. T} _ T{ \fBdebconfmod\fP T} T{ Support for Debconf T} _ T{ \fBdebian_ip\fP T} T{ The networking module for Debian\-based distros T} _ T{ \fBdebian_service\fP T} T{ Service support for Debian systems (uses update\-rc.d and /sbin/service) T} _ T{ \fBdebuild_pkgbuild\fP T} T{ Debian Package builder system T} _ T{ \fBdefaults\fP T} T{ Module to work with salt formula defaults files T} _ T{ \fBdevinfo\fP T} T{ .INDENT 0.0 .TP .B maintainer Alberto Planas <\fI\%aplanas@suse.com\fP> .UNINDENT T} _ T{ \fBdevmap\fP T} T{ Device\-Mapper module T} _ T{ \fBdig\fP T} T{ Compendium of generic DNS utilities. T} _ T{ \fBdisk\fP T} T{ Module for managing disks and blockdevices T} _ T{ \fBdjangomod\fP T} T{ Manage Django sites T} _ T{ \fBdnsmasq\fP T} T{ Module for managing dnsmasq T} _ T{ \fBdnsutil\fP T} T{ Compendium of generic DNS utilities. T} _ T{ \fBdockercompose\fP T} T{ Module to import docker\-compose via saltstack T} _ T{ \fBdockermod\fP T} T{ Management of Docker Containers T} _ T{ \fBdpkg_lowpkg\fP T} T{ Support for DEB packages T} _ T{ \fBdrac\fP T} T{ Manage Dell DRAC T} _ T{ \fBdracr\fP T} T{ Manage Dell DRAC. T} _ T{ \fBdrbd\fP T} T{ DRBD administration module T} _ T{ \fBdummyproxy_pkg\fP T} T{ Package support for the dummy proxy used by the test suite T} _ T{ \fBdummyproxy_service\fP T} T{ Provide the service module for the dummy proxy used in integration tests T} _ T{ \fBebuildpkg\fP T} T{ Support for Portage T} _ T{ \fBeix\fP T} T{ Support for Eix T} _ T{ \fBelasticsearch\fP T} T{ Elasticsearch \- A distributed RESTful search and analytics server T} _ T{ \fBenviron\fP T} T{ Support for getting and setting the environment variables of the current salt process. T} _ T{ \fBeselect\fP T} T{ Support for eselect, Gentoo\(aqs configuration and management tool. T} _ T{ \fBesxcluster\fP T} T{ Module used to access the esxcluster proxy connection methods T} _ T{ \fBesxdatacenter\fP T} T{ Module used to access the esxdatacenter proxy connection methods T} _ T{ \fBesxi\fP T} T{ Glues the VMware vSphere Execution Module to the VMware ESXi Proxy Minions to the \fBesxi proxymodule\fP\&. T} _ T{ \fBesxvm\fP T} T{ Module used to access the esx proxy connection methods T} _ T{ \fBetcd_mod\fP T} T{ Execution module to work with etcd T} _ T{ \fBethtool\fP T} T{ Module for running ethtool command T} _ T{ \fBevent\fP T} T{ Use the Salt Event System to fire events from the master to the minion and vice\-versa. T} _ T{ \fBextfs\fP T} T{ Module for managing ext2/3/4 file systems T} _ T{ \fBfile\fP T} T{ Manage information about regular files, directories, and special files on the minion, set/read user, group, mode, and data T} _ T{ \fBfirewalld\fP T} T{ Support for firewalld. T} _ T{ \fBfreebsd_sysctl\fP T} T{ Module for viewing and modifying sysctl parameters T} _ T{ \fBfreebsd_update\fP T} T{ Support for freebsd\-update utility on FreeBSD. T} _ T{ \fBfreebsdjail\fP T} T{ The jail module for FreeBSD T} _ T{ \fBfreebsdkmod\fP T} T{ Module to manage FreeBSD kernel modules T} _ T{ \fBfreebsdpkg\fP T} T{ Remote package support using \fBpkg_add(1)\fP T} _ T{ \fBfreebsdports\fP T} T{ Install software from the FreeBSD \fBports(7)\fP system T} _ T{ \fBfreebsdservice\fP T} T{ The service module for FreeBSD T} _ T{ \fBfreezer\fP T} T{ .INDENT 0.0 .TP .B maintainer Alberto Planas <\fI\%aplanas@suse.com\fP> .UNINDENT T} _ T{ \fBgcp_addon\fP T} T{ A route is a rule that specifies how certain packets should be handled by the virtual network. T} _ T{ \fBgem\fP T} T{ Manage ruby gems. T} _ T{ \fBgenesis\fP T} T{ Module for managing container and VM images T} _ T{ \fBgentoo_service\fP T} T{ Top level package command wrapper, used to translate the os detected by grains to the correct service manager T} _ T{ \fBgentoolkitmod\fP T} T{ Support for Gentoolkit T} _ T{ \fBgit\fP T} T{ Support for the Git SCM T} _ T{ \fBgithub\fP T} T{ Module for interacting with the GitHub v3 API. T} _ T{ \fBglance\fP T} T{ Module for handling openstack glance calls. T} _ T{ \fBglanceng\fP T} T{ Glance module for interacting with OpenStack Glance T} _ T{ \fBglassfish\fP T} T{ Module for working with the Glassfish/Payara 4.x management API . T} _ T{ \fBglusterfs\fP T} T{ Manage a glusterfs pool T} _ T{ \fBgnomedesktop\fP T} T{ GNOME implementations T} _ T{ \fBgoogle_chat\fP T} T{ Module for sending messages to google chat. T} _ T{ \fBgpg\fP T} T{ Manage a GPG keychains, add keys, create keys, retrieve keys from keyservers. T} _ T{ \fBgrafana4\fP T} T{ Module for working with the Grafana v4 API T} _ T{ \fBgrains\fP T} T{ Return/control aspects of the grains data T} _ T{ \fBgroupadd\fP T} T{ Manage groups on Linux, OpenBSD and NetBSD T} _ T{ \fBgrub_legacy\fP T} T{ Support for GRUB Legacy T} _ T{ \fBguestfs\fP T} T{ Interact with virtual machine images via libguestfs T} _ T{ \fBhadoop\fP T} T{ Support for hadoop T} _ T{ \fBhaproxyconn\fP T} T{ Support for haproxy T} _ T{ \fBhashutil\fP T} T{ A collection of hashing and encoding functions T} _ T{ \fBheat\fP T} T{ Module for handling OpenStack Heat calls T} _ T{ \fBhelm\fP T} T{ Interface with Helm T} _ T{ \fBhg\fP T} T{ Support for the Mercurial SCM T} _ T{ \fBhighstate_doc\fP T} T{ This module renders highstate configuration into a more human readable format. T} _ T{ \fBhosts\fP T} T{ Manage the information in the hosts file T} _ T{ \fBhttp\fP T} T{ Module for making various web calls. T} _ T{ \fBicinga2\fP T} T{ Module to provide icinga2 compatibility to salt. T} _ T{ \fBidem\fP T} T{ Idem Support T} _ T{ \fBifttt\fP T} T{ Support for IFTTT T} _ T{ \fBilo\fP T} T{ Manage HP ILO T} _ T{ \fBincron\fP T} T{ Work with incron T} _ T{ \fBinfluxdb08mod\fP T} T{ InfluxDB \- A distributed time series database T} _ T{ \fBinfluxdbmod\fP T} T{ InfluxDB \- A distributed time series database T} _ T{ \fBinfoblox\fP T} T{ This module have been tested on infoblox API v1.2.1, other versions of the API are likly workable. T} _ T{ \fBini_manage\fP T} T{ Edit ini files T} _ T{ \fBinspectlib\fP T} T{ T} _ T{ \fBinspectlib.collector\fP T} T{ T} _ T{ \fBinspectlib.dbhandle\fP T} T{ T} _ T{ \fBinspectlib.entities\fP T} T{ T} _ T{ \fBinspectlib.exceptions\fP T} T{ T} _ T{ \fBinspectlib.fsdb\fP T} T{ .INDENT 0.0 .TP .B codeauthor Bo Maryniuk <\fI\%bo@suse.de\fP> .UNINDENT T} _ T{ \fBinspectlib.kiwiproc\fP T} T{ T} _ T{ \fBinspectlib.query\fP T} T{ T} _ T{ \fBinspector\fP T} T{ Module for full system inspection. T} _ T{ \fBintrospect\fP T} T{ Functions to perform introspection on a minion, and return data in a format usable by Salt States T} _ T{ \fBiosconfig\fP T} T{ Cisco IOS configuration manipulation helpers T} _ T{ \fBipmi\fP T} T{ Support IPMI commands over LAN. T} _ T{ \fBipset\fP T} T{ Support for ipset T} _ T{ \fBiptables\fP T} T{ Support for iptables T} _ T{ \fBiwtools\fP T} T{ Support for Wireless Tools for Linux T} _ T{ \fBjboss7\fP T} T{ Module for managing JBoss AS 7 through the CLI interface. T} _ T{ \fBjboss7_cli\fP T} T{ Module for low\-level interaction with JbossAS7 through CLI. T} _ T{ \fBjenkinsmod\fP T} T{ Module for controlling Jenkins T} _ T{ \fBjinja\fP T} T{ Module for checking jinja maps and verifying the result of loading JSON/YAML files T} _ T{ \fBjira_mod\fP T} T{ JIRA Execution module T} _ T{ \fBjunos\fP T} T{ Module to interact with Junos devices. T} _ T{ \fBk8s\fP T} T{ Salt module to manage Kubernetes cluster T} _ T{ \fBkapacitor\fP T} T{ Kapacitor execution module. T} _ T{ \fBkerberos\fP T} T{ Manage Kerberos KDC T} _ T{ \fBkernelpkg_linux_apt\fP T} T{ Manage Linux kernel packages on APT\-based systems T} _ T{ \fBkernelpkg_linux_yum\fP T} T{ Manage Linux kernel packages on YUM\-based systems T} _ T{ \fBkey\fP T} T{ Functions to view the minion\(aqs public key information T} _ T{ \fBkeyboard\fP T} T{ Module for managing keyboards on supported POSIX\-like systems using systemd, or such as Redhat, Debian and Gentoo. T} _ T{ \fBkeystone\fP T} T{ Module for handling openstack keystone calls. T} _ T{ \fBkeystoneng\fP T} T{ Keystone module for interacting with OpenStack Keystone T} _ T{ \fBkeystore\fP T} T{ Module to interact with keystores T} _ T{ \fBkmod\fP T} T{ Module to manage Linux kernel modules T} _ T{ \fBkubeadm\fP T} T{ .INDENT 0.0 .TP .B maintainer Alberto Planas <\fI\%aplanas@suse.com\fP> .UNINDENT T} _ T{ \fBkubernetesmod\fP T} T{ Module for handling kubernetes calls. T} _ T{ \fBlaunchctl_service\fP T} T{ Module for the management of MacOS systems that use launchd/launchctl T} _ T{ \fBlayman\fP T} T{ Support for Layman T} _ T{ \fBldap3\fP T} T{ Query and modify an LDAP database (alternative interface) T} _ T{ \fBldapmod\fP T} T{ Salt interface to LDAP commands T} _ T{ \fBlibcloud_compute\fP T} T{ Apache Libcloud Compute Management T} _ T{ \fBlibcloud_dns\fP T} T{ Apache Libcloud DNS Management T} _ T{ \fBlibcloud_loadbalancer\fP T} T{ Apache Libcloud Load Balancer Management T} _ T{ \fBlibcloud_storage\fP T} T{ Apache Libcloud Storage Management T} _ T{ \fBlinux_acl\fP T} T{ Support for Linux File Access Control Lists T} _ T{ \fBlinux_ip\fP T} T{ The networking module for Non\-RH/Deb Linux distros T} _ T{ \fBlinux_lvm\fP T} T{ Support for Linux LVM2 T} _ T{ \fBlinux_service\fP T} T{ If Salt\(aqs OS detection does not identify a different virtual service module, the minion will fall back to using this basic module, which simply wraps sysvinit scripts. T} _ T{ \fBlinux_shadow\fP T} T{ Manage the shadow file on Linux systems T} _ T{ \fBlinux_sysctl\fP T} T{ Module for viewing and modifying sysctl parameters T} _ T{ \fBlocalemod\fP T} T{ Module for managing locales on POSIX\-like systems. T} _ T{ \fBlocate\fP T} T{ Module for using the locate utilities T} _ T{ \fBlogadm\fP T} T{ Module for managing Solaris logadm based log rotations. T} _ T{ \fBlogmod\fP T} T{ On\-demand logging T} _ T{ \fBlogrotate\fP T} T{ Module for managing logrotate. T} _ T{ \fBlvs\fP T} T{ Support for LVS (Linux Virtual Server) T} _ T{ \fBlxc\fP T} T{ Control Linux Containers via Salt T} _ T{ \fBlxd\fP T} T{ Module for managing the LXD daemon and its containers. T} _ T{ \fBmac_assistive\fP T} T{ This module allows you to manage assistive access on macOS minions with 10.9+ T} _ T{ \fBmac_brew_pkg\fP T} T{ Homebrew for macOS T} _ T{ \fBmac_desktop\fP T} T{ macOS implementations of various commands in the "desktop" interface T} _ T{ \fBmac_group\fP T} T{ Manage groups on Mac OS 10.7+ T} _ T{ \fBmac_keychain\fP T} T{ Install certificates into the keychain on Mac OS T} _ T{ \fBmac_pkgutil\fP T} T{ Installer support for macOS. T} _ T{ \fBmac_portspkg\fP T} T{ Support for MacPorts under macOS. T} _ T{ \fBmac_power\fP T} T{ Module for editing power settings on macOS T} _ T{ \fBmac_service\fP T} T{ The service module for macOS T} _ T{ \fBmac_shadow\fP T} T{ Manage macOS local directory passwords and policies T} _ T{ \fBmac_softwareupdate\fP T} T{ Support for the softwareupdate command on MacOS. T} _ T{ \fBmac_sysctl\fP T} T{ Module for viewing and modifying sysctl parameters T} _ T{ \fBmac_system\fP T} T{ System module for sleeping, restarting, and shutting down the system on Mac OS X T} _ T{ \fBmac_timezone\fP T} T{ Module for editing date/time settings on macOS T} _ T{ \fBmac_user\fP T} T{ Manage users on Mac OS 10.7+ T} _ T{ \fBmac_xattr\fP T} T{ This module allows you to manage extended attributes on files or directories T} _ T{ \fBmacdefaults\fP T} T{ Set defaults on Mac OS T} _ T{ \fBmacpackage\fP T} T{ Install pkg, dmg and .app applications on macOS minions. T} _ T{ \fBmakeconf\fP T} T{ Support for modifying make.conf under Gentoo T} _ T{ \fBmandrill\fP T} T{ Mandrill T} _ T{ \fBmarathon\fP T} T{ Module providing a simple management interface to a marathon cluster. T} _ T{ \fBmatch\fP T} T{ The match module allows for match routines to be run and determine target specs T} _ T{ \fBmattermost\fP T} T{ Module for sending messages to Mattermost T} _ T{ \fBmdadm_raid\fP T} T{ Salt module to manage RAID arrays with mdadm T} _ T{ \fBmdata\fP T} T{ Module for managaging metadata in SmartOS Zones T} _ T{ \fBmemcached\fP T} T{ Module for Management of Memcached Keys T} _ T{ \fBmine\fP T} T{ The function cache system allows for data to be stored on the master so it can be easily read by other minions T} _ T{ \fBminion\fP T} T{ Module to provide information about minions T} _ T{ \fBmod_random\fP T} T{ Provides access to randomness generators. T} _ T{ \fBmodjk\fP T} T{ Control Modjk via the Apache Tomcat "Status" worker (\fI\%http://tomcat.apache.org/connectors\-doc/reference/status.html\fP) T} _ T{ \fBmongodb\fP T} T{ Module to provide MongoDB functionality to Salt T} _ T{ \fBmonit\fP T} T{ Monit service module. T} _ T{ \fBmoosefs\fP T} T{ Module for gathering and managing information about MooseFS T} _ T{ \fBmount\fP T} T{ Salt module to manage Unix mounts and the fstab file T} _ T{ \fBmssql\fP T} T{ Module to provide MS SQL Server compatibility to salt. T} _ T{ \fBmsteams\fP T} T{ Module for sending messages to MS Teams T} _ T{ \fBmunin\fP T} T{ Run munin plugins/checks from salt and format the output as data. T} _ T{ \fBmysql\fP T} T{ Module to provide MySQL compatibility to salt. T} _ T{ \fBnacl\fP T} T{ This module helps include encrypted passwords in pillars, grains and salt state files. T} _ T{ \fBnagios\fP T} T{ Run nagios plugins/checks from salt and get the return as data. T} _ T{ \fBnagios_rpc\fP T} T{ Check Host & Service status from Nagios via JSON RPC. T} _ T{ \fBnamecheap_domains\fP T} T{ Namecheap Domain Management T} _ T{ \fBnamecheap_domains_dns\fP T} T{ Namecheap DNS Management T} _ T{ \fBnamecheap_domains_ns\fP T} T{ Namecheap Nameserver Management T} _ T{ \fBnamecheap_ssl\fP T} T{ Namecheap SSL Certificate Management T} _ T{ \fBnamecheap_users\fP T} T{ Namecheap User Management T} _ T{ \fBnapalm_bgp\fP T} T{ NAPALM BGP T} _ T{ \fBnapalm_formula\fP T} T{ NAPALM Formula helpers T} _ T{ \fBnapalm_mod\fP T} T{ NAPALM helpers T} _ T{ \fBnapalm_netacl\fP T} T{ NAPALM ACL T} _ T{ \fBnapalm_network\fP T} T{ NAPALM Network T} _ T{ \fBnapalm_ntp\fP T} T{ NAPALM NTP T} _ T{ \fBnapalm_probes\fP T} T{ NAPALM Probes T} _ T{ \fBnapalm_route\fP T} T{ NAPALM Route T} _ T{ \fBnapalm_snmp\fP T} T{ NAPALM SNMP T} _ T{ \fBnapalm_users\fP T} T{ NAPALM Users T} _ T{ \fBnapalm_yang_mod\fP T} T{ NAPALM YANG T} _ T{ \fBnetaddress\fP T} T{ Module for getting information about network addresses. T} _ T{ \fBnetbox\fP T} T{ NetBox T} _ T{ \fBnetbsd_sysctl\fP T} T{ Module for viewing and modifying sysctl parameters T} _ T{ \fBnetbsdservice\fP T} T{ The service module for NetBSD T} _ T{ \fBnetmiko_mod\fP T} T{ Netmiko Execution Module T} _ T{ \fBnetscaler\fP T} T{ Module to provide Citrix Netscaler compatibility to Salt (compatible with netscaler 9.2+) T} _ T{ \fBnetwork\fP T} T{ Module for gathering and managing network information T} _ T{ \fBneutron\fP T} T{ Module for handling OpenStack Neutron calls T} _ T{ \fBneutronng\fP T} T{ Neutron module for interacting with OpenStack Neutron T} _ T{ \fBnexus\fP T} T{ Module for fetching artifacts from Nexus 3.x T} _ T{ \fBnfs3\fP T} T{ Module for managing NFS version 3. T} _ T{ \fBnftables\fP T} T{ Support for nftables T} _ T{ \fBnginx\fP T} T{ Support for nginx T} _ T{ \fBnilrt_ip\fP T} T{ The networking module for NI Linux Real\-Time distro T} _ T{ \fBnix\fP T} T{ Work with Nix packages T} _ T{ \fBnova\fP T} T{ Module for handling OpenStack Nova calls T} _ T{ \fBnpm\fP T} T{ Manage and query NPM packages. T} _ T{ \fBnspawn\fP T} T{ Manage nspawn containers T} _ T{ \fBnxos\fP T} T{ Execution module for Cisco NX OS Switches. T} _ T{ \fBnxos_api\fP T} T{ Execution module to manage Cisco Nexus Switches (NX\-OS) over the NX\-API T} _ T{ \fBnxos_upgrade\fP T} T{ Execution module to upgrade Cisco NX\-OS Switches. T} _ T{ \fBomapi\fP T} T{ This module interacts with an ISC DHCP Server via OMAPI. T} _ T{ \fBopenbsd_sysctl\fP T} T{ Module for viewing and modifying OpenBSD sysctl parameters T} _ T{ \fBopenbsdpkg\fP T} T{ Package support for OpenBSD T} _ T{ \fBopenbsdrcctl_service\fP T} T{ The rcctl service module for OpenBSD T} _ T{ \fBopenbsdservice\fP T} T{ The service module for OpenBSD T} _ T{ \fBopenscap\fP T} T{ Module for OpenSCAP Management T} _ T{ \fBopenstack_config\fP T} T{ Modify, retrieve, or delete values from OpenStack configuration files. T} _ T{ \fBopenstack_mng\fP T} T{ Module for OpenStack Management T} _ T{ \fBopenvswitch\fP T} T{ Support for Open vSwitch \- module with basic Open vSwitch commands. T} _ T{ \fBopkg\fP T} T{ Support for Opkg T} _ T{ \fBopsgenie\fP T} T{ Module for sending data to OpsGenie T} _ T{ \fBoracle\fP T} T{ Oracle DataBase connection module T} _ T{ \fBosquery\fP T} T{ Support for OSQuery \- \fI\%https://osquery.io\fP\&. T} _ T{ \fBout\fP T} T{ Output Module T} _ T{ \fBpacmanpkg\fP T} T{ A module to wrap pacman calls, since Arch is the best (\fI\%https://wiki.archlinux.org/index.php/Arch_is_the_best\fP) T} _ T{ \fBpagerduty\fP T} T{ Module for Firing Events via PagerDuty T} _ T{ \fBpagerduty_util\fP T} T{ Module for manageing PagerDuty resource T} _ T{ \fBpam\fP T} T{ Support for pam T} _ T{ \fBpanos\fP T} T{ Module to provide Palo Alto compatibility to Salt T} _ T{ \fBparallels\fP T} T{ Manage Parallels Desktop VMs with \fBprlctl\fP and \fBprlsrvctl\fP\&. T} _ T{ \fBparted_partition\fP T} T{ Module for managing partitions on POSIX\-like systems. T} _ T{ \fBpcs\fP T} T{ Configure a Pacemaker/Corosync cluster with PCS T} _ T{ \fBpdbedit\fP T} T{ Manage accounts in Samba\(aqs passdb using pdbedit T} _ T{ \fBpecl\fP T} T{ Manage PHP pecl extensions. T} _ T{ \fBpeeringdb\fP T} T{ PeeringDB Module T} _ T{ \fBpf\fP T} T{ Control the OpenBSD packet filter (PF). T} _ T{ \fBphilips_hue\fP T} T{ Philips HUE lamps module for proxy. T} _ T{ \fBpillar\fP T} T{ Extract the pillar data for this minion T} _ T{ \fBpip\fP T} T{ Install Python packages with pip to either the system or a virtualenv T} _ T{ \fBpkg_resource\fP T} T{ Resources needed by pkg providers T} _ T{ \fBpkgin\fP T} T{ Package support for pkgin based systems, inspired from freebsdpkg module T} _ T{ \fBpkgng\fP T} T{ Support for \fBpkgng\fP, the new package manager for FreeBSD T} _ T{ \fBpkgutil\fP T} T{ Pkgutil support for Solaris T} _ T{ \fBportage_config\fP T} T{ Configure \fBportage(5)\fP T} _ T{ \fBpostfix\fP T} T{ Support for Postfix T} _ T{ \fBpostgres\fP T} T{ Module to provide Postgres compatibility to salt. T} _ T{ \fBpoudriere\fP T} T{ Support for poudriere T} _ T{ \fBpowerpath\fP T} T{ powerpath support. T} _ T{ \fBproxy\fP T} T{ This module allows you to manage proxy settings T} _ T{ \fBps\fP T} T{ A salt interface to psutil, a system and process library. T} _ T{ \fBpublish\fP T} T{ Publish a command from a minion to a target T} _ T{ \fBpuppet\fP T} T{ Execute puppet routines T} _ T{ \fBpurefa\fP T} T{ Management of Pure Storage FlashArray T} _ T{ \fBpurefb\fP T} T{ Management of Pure Storage FlashBlade T} _ T{ \fBpushbullet\fP T} T{ Module for sending messages to Pushbullet (\fI\%https://www.pushbullet.com\fP) T} _ T{ \fBpushover_notify\fP T} T{ Module for sending messages to Pushover (\fI\%https://www.pushover.net\fP) T} _ T{ \fBpw_group\fP T} T{ Manage groups on FreeBSD T} _ T{ \fBpw_user\fP T} T{ Manage users with the pw command T} _ T{ \fBpyenv\fP T} T{ Manage python installations with pyenv. T} _ T{ \fBqemu_img\fP T} T{ Qemu\-img Command Wrapper T} _ T{ \fBqemu_nbd\fP T} T{ Qemu Command Wrapper T} _ T{ \fBquota\fP T} T{ Module for managing quotas on POSIX\-like systems. T} _ T{ \fBrabbitmq\fP T} T{ Module to provide RabbitMQ compatibility to Salt. T} _ T{ \fBrallydev\fP T} T{ Support for RallyDev T} _ T{ \fBrandom_org\fP T} T{ Module for retrieving random information from Random.org T} _ T{ \fBrbac_solaris\fP T} T{ Module for Solaris\(aq Role\-Based Access Control T} _ T{ \fBrbenv\fP T} T{ Manage ruby installations with rbenv. T} _ T{ \fBrdp\fP T} T{ Manage RDP Service on Windows servers T} _ T{ \fBredismod\fP T} T{ Module to provide redis functionality to Salt T} _ T{ \fBreg\fP T} T{ Manage the Windows registry T} _ T{ \fBrest_pkg\fP T} T{ Package support for the REST example T} _ T{ \fBrest_sample_utils\fP T} T{ Utility functions for the rest_sample T} _ T{ \fBrest_service\fP T} T{ Provide the service module for the proxy\-minion REST sample T} _ T{ \fBrestartcheck\fP T} T{ checkrestart functionality for Debian and Red Hat Based systems T} _ T{ \fBret\fP T} T{ Module to integrate with the returner system and retrieve data sent to a salt returner T} _ T{ \fBrh_ip\fP T} T{ The networking module for RHEL/Fedora based distros T} _ T{ \fBrh_service\fP T} T{ Service support for RHEL\-based systems, including support for both upstart and sysvinit T} _ T{ \fBriak\fP T} T{ Riak Salt Module T} _ T{ \fBrpm_lowpkg\fP T} T{ Support for rpm T} _ T{ \fBrpmbuild_pkgbuild\fP T} T{ RPM Package builder system T} _ T{ \fBrsync\fP T} T{ Wrapper for rsync T} _ T{ \fBrunit\fP T} T{ runit service module (\fI\%http://smarden.org/runit\fP) T} _ T{ \fBrvm\fP T} T{ Manage ruby installations and gemsets with RVM, the Ruby Version Manager. T} _ T{ \fBs3\fP T} T{ Connection module for Amazon S3 T} _ T{ \fBs6\fP T} T{ s6 service module T} _ T{ \fBsalt_proxy\fP T} T{ Salt proxy module T} _ T{ \fBsalt_version\fP T} T{ Access Salt\(aqs elemental release code\-names. T} _ T{ \fBsaltcheck\fP T} T{ A module for testing the logic of states and highstates T} _ T{ \fBsaltcloudmod\fP T} T{ Control a salt cloud system T} _ T{ \fBsaltutil\fP T} T{ The Saltutil module is used to manage the state of the salt minion itself. T} _ T{ \fBschedule\fP T} T{ Module for managing the Salt schedule on a minion T} _ T{ \fBscp_mod\fP T} T{ SCP Module T} _ T{ \fBscsi\fP T} T{ SCSI administration module T} _ T{ \fBsdb\fP T} T{ Module for Manipulating Data via the Salt DB API T} _ T{ \fBseed\fP T} T{ Virtual machine image management tools T} _ T{ \fBselinux\fP T} T{ Execute calls on selinux T} _ T{ \fBsensehat\fP T} T{ Module for controlling the LED matrix or reading environment data on the SenseHat of a Raspberry Pi. T} _ T{ \fBsensors\fP T} T{ Read lm\-sensors T} _ T{ \fBserverdensity_device\fP T} T{ Wrapper around Server Density API T} _ T{ \fBservicenow\fP T} T{ Module for execution of ServiceNow CI (configuration items) T} _ T{ \fBslack_notify\fP T} T{ Module for sending messages to Slack T} _ T{ \fBslackware_service\fP T} T{ The service module for Slackware T} _ T{ \fBslsutil\fP T} T{ Utility functions for use with or in SLS files T} _ T{ \fBsmartos_imgadm\fP T} T{ Module for running imgadm command on SmartOS T} _ T{ \fBsmartos_nictagadm\fP T} T{ Module for running nictagadm command on SmartOS :maintainer: Jorge Schrauwen <\fI\%sjorge@blackdot.be\fP> :maturity: new :depends: nictagadm binary, dladm binary :platform: smartos T} _ T{ \fBsmartos_virt\fP T} T{ virst compatibility module for managing VMs on SmartOS T} _ T{ \fBsmartos_vmadm\fP T} T{ Module for running vmadm command on SmartOS T} _ T{ \fBsmbios\fP T} T{ Interface to SMBIOS/DMI T} _ T{ \fBsmf_service\fP T} T{ Service support for Solaris 10 and 11, should work with other systems that use SMF also. T} _ T{ \fBsmtp\fP T} T{ Module for Sending Messages via SMTP T} _ T{ \fBsnapper\fP T} T{ Module to manage filesystem snapshots with snapper T} _ T{ \fBsolaris_fmadm\fP T} T{ Module for running fmadm and fmdump on Solaris T} _ T{ \fBsolaris_group\fP T} T{ Manage groups on Solaris T} _ T{ \fBsolaris_shadow\fP T} T{ Manage the password database on Solaris systems T} _ T{ \fBsolaris_system\fP T} T{ Support for reboot, shutdown, etc T} _ T{ \fBsolaris_user\fP T} T{ Manage users with the useradd command T} _ T{ \fBsolarisipspkg\fP T} T{ IPS pkg support for Solaris T} _ T{ \fBsolarispkg\fP T} T{ Package support for Solaris T} _ T{ \fBsolr\fP T} T{ Apache Solr Salt Module T} _ T{ \fBsolrcloud\fP T} T{ Module for solrcloud configuration T} _ T{ \fBsplunk\fP T} T{ Module for interop with the Splunk API T} _ T{ \fBsplunk_search\fP T} T{ Module for interop with the Splunk API T} _ T{ \fBsqlite3\fP T} T{ Support for SQLite3 T} _ T{ \fBssh\fP T} T{ Manage client ssh components T} _ T{ \fBssh_pkg\fP T} T{ Service support for the REST example T} _ T{ \fBssh_service\fP T} T{ Provide the service module for the proxy\-minion SSH sample . T} _ T{ \fBstate\fP T} T{ Control the state system on the minion. T} _ T{ \fBstatus\fP T} T{ Module for returning various status data about a minion. T} _ T{ \fBstatuspage\fP T} T{ StatusPage T} _ T{ \fBsupervisord\fP T} T{ Provide the service module for system supervisord or supervisord in a virtualenv T} _ T{ \fBsuse_apache\fP T} T{ Support for Apache T} _ T{ \fBsvn\fP T} T{ Subversion SCM T} _ T{ \fBswarm\fP T} T{ Docker Swarm Module using Docker\(aqs Python SDK T} _ T{ \fBswift\fP T} T{ Module for handling OpenStack Swift calls Author: Anthony Stanton <\fI\%anthony.stanton@gmail.com\fP> T} _ T{ \fBsysbench\fP T} T{ The \(aqsysbench\(aq module is used to analyze the performance of the minions, right from the master! It measures various system parameters such as CPU, Memory, File I/O, Threads and Mutex. T} _ T{ \fBsysfs\fP T} T{ Module for interfacing with SysFS T} _ T{ \fBsyslog_ng\fP T} T{ Module for getting information about syslog\-ng T} _ T{ \fBsysmod\fP T} T{ The sys module provides information about the available functions on the minion T} _ T{ \fBsysrc\fP T} T{ sysrc module for FreeBSD T} _ T{ \fBsystem\fP T} T{ Support for reboot, shutdown, etc on POSIX\-like systems. T} _ T{ \fBsystem_profiler\fP T} T{ System Profiler Module T} _ T{ \fBsystemd_service\fP T} T{ Provides the service module for systemd T} _ T{ \fBtelegram\fP T} T{ Module for sending messages via Telegram. T} _ T{ \fBtelemetry\fP T} T{ Connection module for Telemetry T} _ T{ \fBtemp\fP T} T{ Simple module for creating temporary directories and files T} _ T{ \fBtest\fP T} T{ Module for running arbitrary tests T} _ T{ \fBtest_virtual\fP T} T{ Module for running arbitrary tests with a __virtual__ function T} _ T{ \fBtestinframod\fP T} T{ This module exposes the functionality of the TestInfra library for use with SaltStack in order to verify the state of your minions. T} _ T{ \fBtextfsm_mod\fP T} T{ TextFSM T} _ T{ \fBtimezone\fP T} T{ Module for managing timezone on POSIX\-like systems. T} _ T{ \fBtls\fP T} T{ A salt module for SSL/TLS. T} _ T{ \fBtomcat\fP T} T{ Support for Tomcat T} _ T{ \fBtrafficserver\fP T} T{ Apache Traffic Server execution module. T} _ T{ \fBtravisci\fP T} T{ Commands for working with travisci. T} _ T{ \fBtuned\fP T} T{ Interface to Red Hat tuned\-adm module T} _ T{ \fBtwilio_notify\fP T} T{ Module for notifications via Twilio T} _ T{ \fBudev\fP T} T{ Manage and query udev info T} _ T{ \fBupstart_service\fP T} T{ Module for the management of upstart systems. T} _ T{ \fBuptime\fP T} T{ Wrapper around uptime API T} _ T{ \fBuseradd\fP T} T{ Manage users with the useradd command T} _ T{ \fBuwsgi\fP T} T{ uWSGI stats server \fI\%https://uwsgi\-docs.readthedocs.io/en/latest/StatsServer.html\fP T} _ T{ \fBvagrant\fP T} T{ Work with virtual machines managed by Vagrant. T} _ T{ \fBvarnish\fP T} T{ Support for Varnish T} _ T{ \fBvault\fP T} T{ Functions to interact with Hashicorp Vault. T} _ T{ \fBvbox_guest\fP T} T{ VirtualBox Guest Additions installer T} _ T{ \fBvboxmanage\fP T} T{ Support for VirtualBox using the VBoxManage command T} _ T{ \fBvcenter\fP T} T{ Module used to access the vcenter proxy connection methods T} _ T{ \fBvictorops\fP T} T{ Support for VictorOps T} _ T{ \fBvirt\fP T} T{ Work with virtual machines managed by libvirt T} _ T{ \fBvirtualenv_mod\fP T} T{ Create virtualenv environments. T} _ T{ \fBvmctl\fP T} T{ Manage vms running on the OpenBSD VMM hypervisor using vmctl(8). T} _ T{ \fBvsphere\fP T} T{ Manage VMware vCenter servers and ESXi hosts. T} _ T{ \fBwebutil\fP T} T{ Support for htpasswd command. T} _ T{ \fBwin_auditpol\fP T} T{ A salt module for modifying the audit policies on the machine T} _ T{ \fBwin_autoruns\fP T} T{ Module for listing programs that automatically run on startup (very alpha...not tested on anything but my Win 7x64) T} _ T{ \fBwin_certutil\fP T} T{ This module allows you to install certificates into the windows certificate manager. T} _ T{ \fBwin_dacl\fP T} T{ Manage DACLs on Windows T} _ T{ \fBwin_disk\fP T} T{ Module for gathering disk information on Windows T} _ T{ \fBwin_dism\fP T} T{ Install features/packages for Windows using DISM, which is useful for minions not running server versions\ of Windows. T} _ T{ \fBwin_dns_client\fP T} T{ Module for configuring DNS Client on Windows systems T} _ T{ \fBwin_dsc\fP T} T{ Module for working with Windows PowerShell DSC (Desired State Configuration) T} _ T{ \fBwin_file\fP T} T{ Manage information about files on the minion, set/read user, group data, modify the ACL of files/directories T} _ T{ \fBwin_firewall\fP T} T{ Module for configuring Windows Firewall using \fBnetsh\fP T} _ T{ \fBwin_groupadd\fP T} T{ Manage groups on Windows T} _ T{ \fBwin_iis\fP T} T{ Microsoft IIS site management via WebAdministration powershell module T} _ T{ \fBwin_ip\fP T} T{ The networking module for Windows based systems T} _ T{ \fBwin_lgpo\fP T} T{ Manage Local Policy on Windows T} _ T{ \fBwin_license\fP T} T{ This module allows you to manage windows licensing via slmgr.vbs T} _ T{ \fBwin_network\fP T} T{ Module for gathering and managing network information T} _ T{ \fBwin_ntp\fP T} T{ Management of NTP servers on Windows T} _ T{ \fBwin_path\fP T} T{ Manage the Windows System PATH T} _ T{ \fBwin_pkg\fP T} T{ A module to manage software on Windows T} _ T{ \fBwin_pki\fP T} T{ Microsoft certificate management via the PKI Client PowerShell module. T} _ T{ \fBwin_powercfg\fP T} T{ This module allows you to control the power settings of a windows minion via powercfg. T} _ T{ \fBwin_psget\fP T} T{ Module for managing PowerShell through PowerShellGet (PSGet) T} _ T{ \fBwin_servermanager\fP T} T{ Manage Windows features via the ServerManager powershell module. T} _ T{ \fBwin_service\fP T} T{ Windows Service module. T} _ T{ \fBwin_shadow\fP T} T{ Manage the shadow file T} _ T{ \fBwin_smtp_server\fP T} T{ Module for managing IIS SMTP server configuration on Windows servers. T} _ T{ \fBwin_snmp\fP T} T{ Module for managing SNMP service settings on Windows servers. T} _ T{ \fBwin_status\fP T} T{ Module for returning various status data about a minion. T} _ T{ \fBwin_system\fP T} T{ Module for managing Windows systems and getting Windows system information. T} _ T{ \fBwin_task\fP T} T{ Windows Task Scheduler Module . T} _ T{ \fBwin_timezone\fP T} T{ Module for managing timezone on Windows systems. T} _ T{ \fBwin_useradd\fP T} T{ Module for managing Windows Users T} _ T{ \fBwin_wua\fP T} T{ Module for managing Windows Updates using the Windows Update Agent. T} _ T{ \fBwin_wusa\fP T} T{ Microsoft Update files management via wusa.exe T} _ T{ \fBwinrepo\fP T} T{ Module to manage Windows software repo on a Standalone Minion T} _ T{ \fBwordpress\fP T} T{ This module is used to manage Wordpress installations T} _ T{ \fBx509\fP T} T{ Manage X509 certificates T} _ T{ \fBxapi_virt\fP T} T{ This module (mostly) uses the XenAPI to manage Xen virtual machines. T} _ T{ \fBxbpspkg\fP T} T{ Package support for XBPS package manager (used by VoidLinux) T} _ T{ \fBxfs\fP T} T{ Module for managing XFS file systems. T} _ T{ \fBxml\fP T} T{ XML file manager T} _ T{ \fBxmpp\fP T} T{ Module for Sending Messages via XMPP (a.k.a. T} _ T{ \fByumpkg\fP T} T{ Support for YUM/DNF T} _ T{ \fBzabbix\fP T} T{ Support for Zabbix T} _ T{ \fBzcbuildout\fP T} T{ Management of zc.buildout T} _ T{ \fBzenoss\fP T} T{ Module for working with the Zenoss API T} _ T{ \fBzfs\fP T} T{ Module for running ZFS command T} _ T{ \fBzk_concurrency\fP T} T{ Concurrency controls in zookeeper T} _ T{ \fBznc\fP T} T{ znc \- An advanced IRC bouncer T} _ T{ \fBzoneadm\fP T} T{ Module for Solaris 10\(aqs zoneadm T} _ T{ \fBzonecfg\fP T} T{ Module for Solaris 10\(aqs zonecfg T} _ T{ \fBzookeeper\fP T} T{ Zookeeper Module T} _ T{ \fBzpool\fP T} T{ Module for running ZFS zpool command T} _ T{ \fBzypperpkg\fP T} T{ Package support for openSUSE via the zypper package manager T} _ .TE .SS salt.modules.acme module .SS ACME / Let\(aqs Encrypt module .sp This module currently looks for certbot script in the $PATH as \- certbot, \- lestsencrypt, \- certbot\-auto, \- letsencrypt\-auto eventually falls back to /opt/letsencrypt/letsencrypt\-auto .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 Installation & configuration of the Let\(aqs Encrypt client can for example be done using \fI\%https://github.com/saltstack\-formulas/letsencrypt\-formula\fP .UNINDENT .UNINDENT .sp \fBWARNING:\fP .INDENT 0.0 .INDENT 3.5 Be sure to set at least accept\-tos = True in cli.ini! .UNINDENT .UNINDENT .sp Most parameters will fall back to cli.ini defaults if None is given. .SS DNS plugins .sp This module currently supports the CloudFlare certbot DNS plugin. The DNS plugin credentials file needs to be passed in using the \fBdns_plugin_credentials\fP argument. .sp Make sure the appropriate certbot plugin for the wanted DNS provider is installed before using this module. .INDENT 0.0 .TP .B salt.modules.acme.cert(name, aliases=None, email=None, webroot=None, test_cert=False, renew=None, keysize=None, server=None, owner=\(aqroot\(aq, group=\(aqroot\(aq, mode=\(aq0640\(aq, certname=None, preferred_challenges=None, tls_sni_01_port=None, tls_sni_01_address=None, http_01_port=None, http_01_address=None, dns_plugin=None, dns_plugin_credentials=None) Obtain/renew a certificate from an ACME CA, probably Let\(aqs Encrypt. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBname\fP \-\- Common Name of the certificate (DNS name of certificate) .IP \(bu 2 \fBaliases\fP \-\- subjectAltNames (Additional DNS names on certificate) .IP \(bu 2 \fBemail\fP \-\- e\-mail address for interaction with ACME provider .IP \(bu 2 \fBwebroot\fP \-\- True or a full path to use to use webroot. Otherwise use standalone mode .IP \(bu 2 \fBtest_cert\fP \-\- Request a certificate from the Happy Hacker Fake CA (mutually exclusive with \(aqserver\(aq) .IP \(bu 2 \fBrenew\fP \-\- True/\(aqforce\(aq to force a renewal, or a window of renewal before expiry in days .IP \(bu 2 \fBkeysize\fP \-\- RSA key bits .IP \(bu 2 \fBserver\fP \-\- API endpoint to talk to .IP \(bu 2 \fBowner\fP \-\- owner of the private key file .IP \(bu 2 \fBgroup\fP \-\- group of the private key file .IP \(bu 2 \fBmode\fP \-\- mode of the private key file .IP \(bu 2 \fBcertname\fP \-\- Name of the certificate to save .IP \(bu 2 \fBpreferred_challenges\fP \-\- A sorted, comma delimited list of the preferred challenge to use during authorization with the most preferred challenge listed first. .IP \(bu 2 \fBtls_sni_01_port\fP \-\- Port used during tls\-sni\-01 challenge. This only affects the port Certbot listens on. A conforming ACME server will still attempt to connect on port 443. .IP \(bu 2 \fBtls_sni_01_address\fP \-\- The address the server listens to during tls\-sni\-01 challenge. .IP \(bu 2 \fBhttp_01_port\fP \-\- Port used in the http\-01 challenge. This only affects the port Certbot listens on. A conforming ACME server will still attempt to connect on port 80. .IP \(bu 2 \fBhttps_01_address\fP \-\- The address the server listens to during http\-01 challenge. .IP \(bu 2 \fBdns_plugin\fP \-\- Name of a DNS plugin to use (currently only \(aqcloudflare\(aq or \(aqdigitalocean\(aq) .IP \(bu 2 \fBdns_plugin_credentials\fP \-\- Path to the credentials file if required by the specified DNS plugin .IP \(bu 2 \fBdns_plugin_propagate_seconds\fP \-\- Number of seconds to wait for DNS propogations before asking ACME servers to verify the DNS record. (default 10) .UNINDENT .TP .B Return type \fI\%dict\fP .TP .B Returns Dictionary with \(aqresult\(aq True/False/None, \(aqcomment\(aq and certificate\(aqs expiry date (\(aqnot_after\(aq) .UNINDENT .sp CLI example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aqgitlab.example.com\(aq acme.cert dev.example.com "[gitlab.example.com]" test_cert=True renew=14 webroot=/opt/gitlab/embedded/service/gitlab\-rails/public .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.acme.certs() Return a list of active certificates .sp CLI example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aqvhost.example.com\(aq acme.certs .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.acme.expires(name) The expiry date of a certificate in ISO format .INDENT 7.0 .TP .B Parameters \fBname\fP (\fI\%str\fP) \-\- Name of certificate .TP .B Return type \fI\%str\fP .TP .B Returns Expiry date in ISO format. .UNINDENT .sp CLI example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aqgitlab.example.com\(aq acme.expires dev.example.com .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.acme.has(name) Test if a certificate is in the Let\(aqs Encrypt Live directory .INDENT 7.0 .TP .B Parameters \fBname\fP (\fI\%str\fP) \-\- Name of certificate .TP .B Return type \fI\%bool\fP .UNINDENT .sp Code example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C if __salt__[\(aqacme.has\(aq](\(aqdev.example.com\(aq): log.info(\(aqThat is one nice certificate you have there!\(aq) .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.acme.info(name) Return information about a certificate .INDENT 7.0 .TP .B Parameters \fBname\fP (\fI\%str\fP) \-\- Name of certificate .TP .B Return type \fI\%dict\fP .TP .B Returns Dictionary with information about the certificate. If neither the \fBtls\fP nor the \fBx509\fP module can be used to determine the certificate information, the information will be retrieved as one big text block under the key \fBtext\fP using the openssl cli. .UNINDENT .sp CLI example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aqgitlab.example.com\(aq acme.info dev.example.com .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.acme.needs_renewal(name, window=None) Check if a certificate needs renewal .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBname\fP (\fI\%str\fP) \-\- Name of certificate .IP \(bu 2 \fBwindow\fP (\fIbool/str/int\fP) \-\- Window in days to renew earlier or True/force to just return True .UNINDENT .TP .B Return type \fI\%bool\fP .TP .B Returns Whether or not the certificate needs to be renewed. .UNINDENT .sp Code example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C if __salt__[\(aqacme.needs_renewal\(aq](\(aqdev.example.com\(aq): __salt__[\(aqacme.cert\(aq](\(aqdev.example.com\(aq, **kwargs) else: log.info(\(aqYour certificate is still good\(aq) .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.acme.renew_by(name, window=None) Date in ISO format when a certificate should first be renewed .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBname\fP (\fI\%str\fP) \-\- Name of certificate .IP \(bu 2 \fBwindow\fP (\fI\%int\fP) \-\- number of days before expiry when renewal should take place .UNINDENT .TP .B Return type \fI\%str\fP .TP .B Returns Date of certificate renewal in ISO format. .UNINDENT .UNINDENT .SS salt.modules.aix_group module .sp Manage groups on Solaris .sp \fBIMPORTANT:\fP .INDENT 0.0 .INDENT 3.5 If you feel that Salt should be using this module to manage groups on a minion, and it is using a different module (or gives an error similar to \fI\(aqgroup.info\(aq is not available\fP), see here\&. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.aix_group.add(name, gid=None, system=False, root=None) Add the specified group .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq group.add foo 3456 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.aix_group.adduser(name, username, root=None) Add a user in the group. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq group.adduser foo bar .ft P .fi .UNINDENT .UNINDENT .sp Verifies if a valid username \(aqbar\(aq as a member of an existing group \(aqfoo\(aq, if not then adds it. .UNINDENT .INDENT 0.0 .TP .B salt.modules.aix_group.chgid(name, gid) Change the gid for a named group .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq group.chgid foo 4376 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.aix_group.delete(name) Remove the named group .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq group.delete foo .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.aix_group.deluser(name, username, root=None) Remove a user from the group. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq group.deluser foo bar .ft P .fi .UNINDENT .UNINDENT .sp Removes a member user \(aqbar\(aq from a group \(aqfoo\(aq. If group is not present then returns True. .UNINDENT .INDENT 0.0 .TP .B salt.modules.aix_group.getent(refresh=False) Return info on all groups .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq group.getent .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.aix_group.info(name) Return information about a group .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq group.info foo .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.aix_group.members(name, members_list, root=None) Replaces members of the group with a provided list. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 salt \(aq*\(aq group.members foo \(aquser1,user2,user3,...\(aq .UNINDENT .UNINDENT .INDENT 7.0 .TP .B Replaces a membership list for a local group \(aqfoo\(aq. foo:x:1234:user1,user2,user3,... .UNINDENT .UNINDENT .SS salt.modules.aix_shadow module .sp Manage account locks on AIX systems .sp New in version 2018.3.0. .INDENT 0.0 .TP .B depends none .UNINDENT .INDENT 0.0 .TP .B salt.modules.aix_shadow.locked(user) Query for all accounts which are flagged as locked. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt shadow.locked ALL .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.aix_shadow.login_failures(user) Query for all accounts which have 3 or more login failures. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt shadow.login_failures ALL .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.aix_shadow.unlock(user) Unlock user for locked account .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt shadow.unlock user .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.aixpkg .sp Package support for AIX .sp \fBIMPORTANT:\fP .INDENT 0.0 .INDENT 3.5 If you feel that Salt should be using this module to manage filesets or rpm 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 .INDENT 0.0 .TP .B salt.modules.aixpkg.available_version(*names, **kwargs) This function is an alias of \fBlatest_version\fP\&. .INDENT 7.0 .INDENT 3.5 Return the latest version of the named fileset/rpm package available for upgrade or installation. If more than one fileset/rpm package name is specified, a dict of name/version pairs is returned. .sp If the latest version of a given fileset/rpm package is already installed, an empty string will be returned for that package. .sp CLI Example: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.latest_version salt \(aq*\(aq pkg.latest_version ... .ft P .fi .UNINDENT .UNINDENT .sp NOTE: Repositories are not presently supported for AIX. This function will always return an empty string for a given fileset/rpm package. .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.aixpkg.install(name=None, refresh=False, pkgs=None, version=None, test=False, **kwargs) Install the named fileset(s)/rpm package(s). .INDENT 7.0 .TP .B name The name of the fileset or rpm package to be installed. .TP .B refresh Whether or not to update the yum database before executing. .UNINDENT .sp Multiple Package Installation Options: .INDENT 7.0 .TP .B pkgs A list of filesets and/or rpm packages to install. Must be passed as a python list. The \fBname\fP parameter will be ignored if this option is passed. .TP .B version Install a specific version of a fileset/rpm package. (Unused at present). .TP .B test Verify that command functions correctly: .UNINDENT .sp Returns a dict containing the new fileset(s)/rpm package(s) names and versions: .INDENT 7.0 .INDENT 3.5 .INDENT 0.0 .TP .B {\(aq\(aq: {\(aqold\(aq: \(aq\(aq, \(aqnew\(aq: \(aq\(aq}} .UNINDENT .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.install /stage/middleware/AIX/bash\-4.2\-3.aix6.1.ppc.rpm salt \(aq*\(aq pkg.install /stage/middleware/AIX/bash\-4.2\-3.aix6.1.ppc.rpm refresh=True salt \(aq*\(aq pkg.install /stage/middleware/AIX/VIOS2211_update/tpc_4.1.1.85.bff salt \(aq*\(aq pkg.install /stage/middleware/AIX/Xlc/usr/sys/inst.images/xlC.rte salt \(aq*\(aq pkg.install /stage/middleware/AIX/Firefox/ppc\-AIX53/Firefox.base salt \(aq*\(aq pkg.install pkgs=\(aq["foo", "bar"]\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.aixpkg.latest_version(*names, **kwargs) Return the latest version of the named fileset/rpm package available for upgrade or installation. If more than one fileset/rpm package name is specified, a dict of name/version pairs is returned. .sp If the latest version of a given fileset/rpm package is already installed, an empty string will be returned for that package. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.latest_version salt \(aq*\(aq pkg.latest_version ... .ft P .fi .UNINDENT .UNINDENT .sp NOTE: Repositories are not presently supported for AIX. This function will always return an empty string for a given fileset/rpm package. .UNINDENT .INDENT 0.0 .TP .B salt.modules.aixpkg.list_pkgs(versions_as_list=False, **kwargs) List the filesets/rpm packages currently installed as a dict: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C {\(aq\(aq: \(aq\(aq} .ft P .fi .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.list_pkgs .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.aixpkg.remove(name=None, pkgs=None, **kwargs) Remove specified fileset(s)/rpm package(s). .INDENT 7.0 .TP .B name The name of the fileset or rpm package to be deleted. .UNINDENT .sp Multiple Package Options: .INDENT 7.0 .TP .B pkgs A list of filesets and/or rpm packages to delete. Must be passed as a python list. The \fBname\fP parameter will be ignored if this option is passed. .UNINDENT .sp Returns a list containing the removed packages. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.remove salt \(aq*\(aq pkg.remove tcsh salt \(aq*\(aq pkg.remove xlC.rte salt \(aq*\(aq pkg.remove Firefox.base.adt salt \(aq*\(aq pkg.remove pkgs=\(aq["foo", "bar"]\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.aixpkg.upgrade_available(name, **kwargs) 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.aixpkg.version(*names, **kwargs) Common interface for obtaining the version of installed fileset/rpm package. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.version vim salt \(aq*\(aq pkg.version foo bar baz .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.aliases .sp Manage the information in the aliases file .INDENT 0.0 .TP .B salt.modules.aliases.get_target(alias) Return the target associated with an alias .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq aliases.get_target alias .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.aliases.has_target(alias, target) Return true if the alias/target is set .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq aliases.has_target alias target .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.aliases.list_aliases() Return the aliases found in the aliases file in this format: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C {\(aqalias\(aq: \(aqtarget\(aq} .ft P .fi .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq aliases.list_aliases .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.aliases.rm_alias(alias) Remove an entry from the aliases file .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq aliases.rm_alias alias .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.aliases.set_target(alias, target) Set the entry in the aliases file for the given alias, this will overwrite any previous entry for the given alias or create a new one if it does not exist. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq aliases.set_target alias target .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.alternatives .sp Support for Alternatives system .INDENT 0.0 .TP .B codeauthor Radek Rada <\fI\%radek.rada@gmail.com\fP> .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.ansiblegate .SS Ansible Support .sp This module can have an optional minion\-level configuration in /etc/salt/minion.d/ as follows: .INDENT 0.0 .INDENT 3.5 ansible_timeout: 1200 .UNINDENT .UNINDENT .sp The timeout is how many seconds Salt should wait for any Ansible module to respond. .INDENT 0.0 .TP .B class salt.modules.ansiblegate.AnsibleModuleCaller(resolver) .INDENT 7.0 .TP .B DEFAULT_TIMEOUT = 1200 .UNINDENT .INDENT 7.0 .TP .B OPT_TIMEOUT_KEY = \(aqansible_timeout\(aq .UNINDENT .INDENT 7.0 .TP .B call(module, *args, **kwargs) Call an Ansible module by invoking it. :param module: the name of the module. :param args: Arguments to the module :param kwargs: keywords to the module :return: .UNINDENT .UNINDENT .INDENT 0.0 .TP .B class salt.modules.ansiblegate.AnsibleModuleResolver(opts) This class is to resolve all available modules in Ansible. .INDENT 7.0 .TP .B get_modules_list(pattern=None) Return module map references. :return: .UNINDENT .INDENT 7.0 .TP .B install() .UNINDENT .INDENT 7.0 .TP .B load_module(module) Introspect Ansible module. .INDENT 7.0 .TP .B Parameters \fBmodule\fP \-\- .TP .B Returns .UNINDENT .UNINDENT .INDENT 7.0 .TP .B resolve() .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.ansiblegate.help(module=None, *args) Display help on Ansible standard module. .INDENT 7.0 .TP .B Parameters \fBmodule\fP \-\- .TP .B Returns .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.ansiblegate.list_(pattern=None) Lists available modules. :return: .UNINDENT .INDENT 0.0 .TP .B salt.modules.ansiblegate.playbooks(playbook, rundir=None, check=False, diff=False, extra_vars=None, flush_cache=False, forks=5, inventory=None, limit=None, list_hosts=False, list_tags=False, list_tasks=False, module_path=None, skip_tags=None, start_at_task=None, syntax_check=False, tags=None, playbook_kwargs=None) Run Ansible Playbooks .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBplaybook\fP \-\- Which playbook to run. .IP \(bu 2 \fBrundir\fP \-\- Directory to run \fIansible\-playbook\fP in. (Default: None) .IP \(bu 2 \fBcheck\fP \-\- don\(aqt make any changes; instead, try to predict some of the changes that may occur (Default: False) .IP \(bu 2 \fBdiff\fP \-\- when changing (small) files and templates, show the differences in those files; works great with \-\-check (default: False) .IP \(bu 2 \fBextra_vars\fP \-\- set additional variables as key=value or YAML/JSON, if filename prepend with @, (default: None) .IP \(bu 2 \fBflush_cache\fP \-\- clear the fact cache for every host in inventory (default: False) .IP \(bu 2 \fBforks\fP \-\- specify number of parallel processes to use (Default: 5) .IP \(bu 2 \fBinventory\fP \-\- specify inventory host path or comma separated host list. (Default: None) (Ansible\(aqs default is /etc/ansible/hosts) .IP \(bu 2 \fBlimit\fP \-\- further limit selected hosts to an additional pattern (Default: None) .IP \(bu 2 \fBlist_hosts\fP \-\- outputs a list of matching hosts; does not execute anything else (Default: False) .IP \(bu 2 \fBlist_tags\fP \-\- list all available tags (Default: False) .IP \(bu 2 \fBlist_tasks\fP \-\- list all tasks that would be executed (Default: False) .IP \(bu 2 \fBmodule_path\fP \-\- prepend colon\-separated path(s) to module library. (Default: None) .IP \(bu 2 \fBskip_tags\fP \-\- only run plays and tasks whose tags do not match these values (Default: False) .IP \(bu 2 \fBstart_at_task\fP \-\- start the playbook at the task matching this name (Default: None) .IP \(bu 2 \fBtags\fP \-\- only run plays and tasks tagged with these values (Default: None) .UNINDENT .TP .B Param syntax_check: perform a syntax check on the playbook, but do not execute it (Default: False) .TP .B Returns Playbook return .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aqansiblehost\(aq ansible.playbook playbook=/srv/playbooks/play.yml .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.apkpkg .sp Support for apk .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 .INDENT 0.0 .TP .B salt.modules.apkpkg.file_dict(*packages, **kwargs) List the files that belong to a package, grouped by package. Not specifying any packages will return a list of _every_ file on the system\(aqs package database (not generally recommended). .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.file_list httpd salt \(aq*\(aq pkg.file_list httpd postfix salt \(aq*\(aq pkg.file_list .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.apkpkg.file_list(*packages, **kwargs) 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.apkpkg.install(name=None, refresh=False, pkgs=None, sources=None, **kwargs) Install the passed package, add refresh=True to update the apk 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 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 Multiple Package Installation Options: .INDENT 7.0 .TP .B pkgs A list of packages to install from a software repository. Must be passed as a python list. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.install pkgs=\(aq["foo", "bar"]\(aq .ft P .fi .UNINDENT .UNINDENT .TP .B sources A list of IPK 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 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 install_recommends Whether to install the packages marked as recommended. Default is True. .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.apkpkg.latest_version(*names, **kwargs) Return the latest version of the named package available for upgrade or installation. If more than one package name is specified, a dict of name/version pairs is returned. .sp If the latest version of a given package is already installed, an empty string will be returned for that package. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.latest_version salt \(aq*\(aq pkg.latest_version salt \(aq*\(aq pkg.latest_version ... .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.apkpkg.list_pkgs(versions_as_list=False, **kwargs) List the packages currently installed in a dict: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C {\(aq\(aq: \(aq\(aq} .ft P .fi .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.list_pkgs salt \(aq*\(aq pkg.list_pkgs versions_as_list=True .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.apkpkg.list_upgrades(refresh=True, **kwargs) List all available package upgrades. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.list_upgrades .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.apkpkg.owner(*paths, **kwargs) Return the name of the package that owns the file. Multiple file paths can be passed. Like \fBpkg.version 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.apkpkg.upgrade(name=None, pkgs=None, refresh=True, **kwargs) Upgrades all packages via \fBapk upgrade\fP or a specific package if name or pkgs is specified. Name is ignored if pkgs is specified .sp Returns a dict containing the changes. .INDENT 7.0 .INDENT 3.5 .INDENT 0.0 .TP .B {\(aq\(aq: {\(aqold\(aq: \(aq\(aq, \(aqnew\(aq: \(aq\(aq}} .UNINDENT .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.upgrade .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.apkpkg.version(*names, **kwargs) Returns a string representing the package version or an empty string if not installed. If more than one package name is specified, a dict of name/version pairs is returned. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.version salt \(aq*\(aq pkg.version ... .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.aptly module .sp Aptly Debian repository manager. .sp New in version 2018.3.0. .INDENT 0.0 .TP .B salt.modules.aptly.cleanup_db(config_path=\(aq/etc/aptly.conf\(aq, dry_run=False) .INDENT 7.0 .TP .B Remove data regarding unreferenced packages and delete files in the package pool that are no longer being used by packages. .UNINDENT .INDENT 7.0 .TP .B Parameters \fBdry_run\fP (\fI\%bool\fP) \-\- Report potential changes without making any changes. .TP .B Returns A dictionary of the package keys and files that were removed. .TP .B Return type \fI\%dict\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq aptly.cleanup_db .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.aptly.delete_repo(name, config_path=\(aq/etc/aptly.conf\(aq, force=False) Remove the repository. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBname\fP (\fI\%str\fP) \-\- The name of the repository. .IP \(bu 2 \fBconfig_path\fP (\fI\%str\fP) \-\- The path to the configuration file for the aptly instance. .IP \(bu 2 \fBforce\fP (\fI\%bool\fP) \-\- Whether to remove the repository even if it is used as the source of an existing snapshot. .UNINDENT .TP .B Returns A boolean representing whether all changes succeeded. .TP .B Return type \fI\%bool\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq aptly.delete_repo name="test\-repo" .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.aptly.get_config(config_path=\(aq/etc/aptly.conf\(aq) Get the configuration data. .INDENT 7.0 .TP .B Parameters \fBconfig_path\fP (\fI\%str\fP) \-\- The path to the configuration file for the aptly instance. .TP .B Returns A dictionary containing the configuration data. .TP .B Return type \fI\%dict\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq aptly.get_config .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.aptly.get_repo(name, config_path=\(aq/etc/aptly.conf\(aq, with_packages=False) Get the details of the repository. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBname\fP (\fI\%str\fP) \-\- The name of the repository. .IP \(bu 2 \fBconfig_path\fP (\fI\%str\fP) \-\- The path to the configuration file for the aptly instance. .IP \(bu 2 \fBwith_packages\fP (\fI\%bool\fP) \-\- Return a list of packages in the repo. .UNINDENT .TP .B Returns A dictionary containing information about the repository. .TP .B Return type \fI\%dict\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq aptly.get_repo name="test\-repo" .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.aptly.list_mirrors(config_path=\(aq/etc/aptly.conf\(aq) Get a list of all the mirrors. .INDENT 7.0 .TP .B Parameters \fBconfig_path\fP (\fI\%str\fP) \-\- The path to the configuration file for the aptly instance. .TP .B Returns A list of the mirror names. .TP .B Return type \fI\%list\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq aptly.list_mirrors .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.aptly.list_published(config_path=\(aq/etc/aptly.conf\(aq) Get a list of all the published repositories. .INDENT 7.0 .TP .B Parameters \fBconfig_path\fP (\fI\%str\fP) \-\- The path to the configuration file for the aptly instance. .TP .B Returns A list of the published repository names. .TP .B Return type \fI\%list\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq aptly.list_published .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.aptly.list_repos(config_path=\(aq/etc/aptly.conf\(aq, with_packages=False) List all of the repos. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBconfig_path\fP (\fI\%str\fP) \-\- The path to the configuration file for the aptly instance. .IP \(bu 2 \fBwith_packages\fP (\fI\%bool\fP) \-\- Return a list of packages in the repo. .UNINDENT .TP .B Returns A dictionary of the repositories. .TP .B Return type \fI\%dict\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq aptly.list_repos .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.aptly.list_snapshots(config_path=\(aq/etc/aptly.conf\(aq, sort_by_time=False) Get a list of all the snapshots. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBconfig_path\fP (\fI\%str\fP) \-\- The path to the configuration file for the aptly instance. .IP \(bu 2 \fBsort_by_time\fP (\fI\%bool\fP) \-\- Whether to sort by creation time instead of by name. .UNINDENT .TP .B Returns A list of the snapshot names. .TP .B Return type \fI\%list\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq aptly.list_snapshots .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.aptly.new_repo(name, config_path=\(aq/etc/aptly.conf\(aq, comment=None, component=None, distribution=None, uploaders_file=None, from_snapshot=None, saltenv=\(aqbase\(aq) Create the new repository. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBname\fP (\fI\%str\fP) \-\- The name of the repository. .IP \(bu 2 \fBconfig_path\fP (\fI\%str\fP) \-\- The path to the configuration file for the aptly instance. .IP \(bu 2 \fBcomment\fP (\fI\%str\fP) \-\- The description of the repository. .IP \(bu 2 \fBcomponent\fP (\fI\%str\fP) \-\- The default component to use when publishing. .IP \(bu 2 \fBdistribution\fP (\fI\%str\fP) \-\- The default distribution to use when publishing. .IP \(bu 2 \fBuploaders_file\fP (\fI\%str\fP) \-\- The repository upload restrictions config. .IP \(bu 2 \fBfrom_snapshot\fP (\fI\%str\fP) \-\- The snapshot to initialize the repository contents from. .IP \(bu 2 \fBsaltenv\fP (\fI\%str\fP) \-\- The environment the file resides in. .UNINDENT .TP .B Returns A boolean representing whether all changes succeeded. .TP .B Return type \fI\%bool\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq aptly.new_repo name="test\-repo" comment="Test main repo" component="main" distribution="trusty" .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.aptly.set_repo(name, config_path=\(aq/etc/aptly.conf\(aq, comment=None, component=None, distribution=None, uploaders_file=None, saltenv=\(aqbase\(aq) Configure the repository settings. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBname\fP (\fI\%str\fP) \-\- The name of the repository. .IP \(bu 2 \fBconfig_path\fP (\fI\%str\fP) \-\- The path to the configuration file for the aptly instance. .IP \(bu 2 \fBcomment\fP (\fI\%str\fP) \-\- The description of the repository. .IP \(bu 2 \fBcomponent\fP (\fI\%str\fP) \-\- The default component to use when publishing. .IP \(bu 2 \fBdistribution\fP (\fI\%str\fP) \-\- The default distribution to use when publishing. .IP \(bu 2 \fBuploaders_file\fP (\fI\%str\fP) \-\- The repository upload restrictions config. .IP \(bu 2 \fBfrom_snapshot\fP (\fI\%str\fP) \-\- The snapshot to initialize the repository contents from. .IP \(bu 2 \fBsaltenv\fP (\fI\%str\fP) \-\- The environment the file resides in. .UNINDENT .TP .B Returns A boolean representing whether all changes succeeded. .TP .B Return type \fI\%bool\fP .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq aptly.set_repo name="test\-repo" comment="Test universe repo" component="universe" distribution="xenial" .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\&. .sp For repository management, the \fBpython\-apt\fP package must be installed. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.aptpkg.add_repo_key(path=None, text=None, keyserver=None, keyid=None, saltenv=\(aqbase\(aq) New in version 2017.7.0. .sp Add a repo key using \fBapt\-key add\fP\&. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBpath\fP (\fI\%str\fP) \-\- The path of the key file to import. .IP \(bu 2 \fBtext\fP (\fI\%str\fP) \-\- The key data to import, in string form. .IP \(bu 2 \fBkeyserver\fP (\fI\%str\fP) \-\- The server to download the repo key specified by the keyid. .IP \(bu 2 \fBkeyid\fP (\fI\%str\fP) \-\- The key id of the repo key to add. .IP \(bu 2 \fBsaltenv\fP (\fI\%str\fP) \-\- The environment the key file resides in. .UNINDENT .TP .B Returns A boolean representing whether the repo key was added. .TP .B Return type \fI\%bool\fP .UNINDENT .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.add_repo_key \(aqsalt://apt/sources/test.key\(aq salt \(aq*\(aq pkg.add_repo_key text="\(aq$KEY1\(aq" salt \(aq*\(aq pkg.add_repo_key keyserver=\(aqkeyserver.example\(aq keyid=\(aq0000AAAA\(aq .ft P .fi .UNINDENT .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.available_version(*names, **kwargs) This function is an alias of \fBlatest_version\fP\&. .INDENT 7.0 .INDENT 3.5 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 0.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 0.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 .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, **kwargs) 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, **kwargs) 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_repo_keys() New in version 2017.7.0. .sp List known repo key details. .INDENT 7.0 .TP .B Returns A dictionary containing the repo keys. .TP .B Return type \fI\%dict\fP .UNINDENT .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.get_repo_keys .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, **kwargs) 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. .TP .B failhard Whether to throw an exception if none of the packages are installed. Defaults to True. .sp New in version 2016.11.3. .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 ... salt \(aq*\(aq pkg.info_installed failhard=false .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, downloadonly=False, ignore_epoch=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. .sp Changed in version 2018.3.0: version can now contain comparison operators (e.g. \fB>1.2.3\fP, \fB<=2.0\fP, etc.) .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. .TP .B ignore_epoch False Only used when the version of a package is specified using a comparison operator (e.g. \fB>4.1\fP). If set to \fBTrue\fP, then the epoch will be ignored when comparing the currently\-installed version to the desired version. .sp New in version 2018.3.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_downloaded(root=None, **kwargs) New in version 3000?. .sp List prefetched packages downloaded by apt in the local disk. .INDENT 7.0 .TP .B root operate on a different root directory. .UNINDENT .sp CLI example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.list_downloaded .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 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_repo_pkgs(*args, **kwargs) New in version 2017.7.0. .sp Returns all available packages. Optionally, package names (and name globs) can be passed and the results will be filtered to packages matching those names. .sp This function can be helpful in discovering the version or repo to specify in a \fBpkg.installed\fP state. .sp The return data will be a dictionary mapping package names to a list of version numbers, ordered from newest to oldest. For example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C { \(aqbash\(aq: [\(aq4.3\-14ubuntu1.1\(aq, \(aq4.3\-14ubuntu1\(aq], \(aqnginx\(aq: [\(aq1.10.0\-0ubuntu0.16.04.4\(aq, \(aq1.9.15\-0ubuntu1\(aq] } .ft P .fi .UNINDENT .UNINDENT .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.list_repo_pkgs salt \(aq*\(aq pkg.list_repo_pkgs foo bar baz .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.aptpkg.list_repos(**kwargs) 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 .TP .B architectures A comma\-separated list of supported architectures, e.g. \fBamd64\fP If this option is not set, all architectures (configured in the system) will be used. .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 or a list of key IDs to load with the \fBkeyserver\fP argument .TP .B key_url URL to a GPG key to add to the APT GPG keyring .TP .B key_text GPG key in string form to add to the APT GPG keyring .sp New in version 2018.3.0. .TP .B consolidate False If \fBTrue\fP, will attempt to de\-duplicate and consolidate sources .TP .B comments Sometimes you want to supply additional information, but not as enabled configuration. All comments provided here will be joined into a single string and appended to the repo configuration with a comment marker (#) before it. .sp New in version 2015.8.9. .TP .B refresh True Enable or disable (True or False) refreshing of the apt package database. The previous \fBrefresh_db\fP argument was deprecated in favor of \fBrefresh\(ga\fP\&. The \fBrefresh_db\fP argument will still continue to work to ensure backwards compatibility, but please change to using the preferred \fBrefresh\fP\&. .UNINDENT .sp \fBNOTE:\fP .INDENT 7.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 .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.normalize_name(name) Strips the architecture from the specified package name, if necessary. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.normalize_name zsh:amd64 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.aptpkg.owner(*paths, **kwargs) 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.parse_arch(name) Parse name and architecture from the specified package name. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pkg.parse_arch zsh:amd64 .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, failhard=False, **kwargs) 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 failhard .INDENT 7.0 .INDENT 3.5 If False, return results of Err lines as \fBFalse\fP for the package database that encountered the error. If True, raise an error with a list of the package databases that encountered errors. .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.show(*names, **kwargs) New in version 2019.2.0. .sp Runs an \fBapt\-cache show\fP on the passed package names, and returns the results in a nested dictionary. The top level of the return data will be the package name, with each package name mapping to a dictionary of version numbers to any additional information returned by \fBapt\-cache show\fP\&. .INDENT 7.0 .TP .B filter An optional comma\-separated list (or quoted Python list) of case\-insensitive keys on which to filter. This allows one to restrict the information returned for each package to a smaller selection of pertinent items. .TP .B refresh False If \fBTrue\fP, the apt cache will be refreshed first. By default, no refresh is performed. .UNINDENT .sp CLI Examples: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion pkg.show gawk salt myminion pkg.show \(aqnginx\-*\(aq salt myminion pkg.show \(aqnginx\-*\(aq filter=description,provides .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 unhold. 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. .TP .B refresh True If \fBTrue\fP, the apt cache will be refreshed first. By default, this is \fBTrue\fP and a refresh is performed. .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 download_only (or downloadonly) Only download the packages, don\(aqt unpack or install them. Use downloadonly to be in line with yum and zypper module. .sp New in version 2018.3.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, **kwargs) 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, **kwargs) 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 existing 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. .sp Changed in version 2017.7.0: Globbing is now supported for this argument .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 # Globbing for sources (2017.7.0 and later) salt \(aq*\(aq archive.cmd_zip /tmp/zipfile.zip \(aq/tmp/sourcefile*\(aq .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, source_hash=None) 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 .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. .TP .B source_hash If \fBname\fP is an http(s)/ftp URL and the file exists in the minion\(aqs file cache, this option can be passed to keep the minion from re\-downloading the archive if the cached copy matches the specified hash. .sp New in version 2018.3.0. .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 https://domain.tld/myfile.zip source_hash=f1d2d2f924e986ac86fdf7b36c94bcdf32beec15 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, source_hash=None) 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. .TP .B source_hash If \fBname\fP is an http(s)/ftp URL and the file exists in the minion\(aqs file cache, this option can be passed to keep the minion from re\-downloading the archive if the cached copy matches the specified hash. .sp New in version 2018.3.0. .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 https://domain.tld/myfile.zip source_hash=f1d2d2f924e986ac86fdf7b36c94bcdf32beec15 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. .sp Changed in version 2017.7.0: Globbing is now supported for this argument .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 # Globbing for sources (2017.7.0 and later) salt \(aq*\(aq archive.rar /tmp/rarfile.rar \(aq/tmp/sourcefile*\(aq .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. .sp Changed in version 2017.7.0: Globbing is now supported for this argument .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 # Create a tarfile using globbing (2017.7.0 and later) salt \(aq*\(aq archive.tar cjvf /tmp/tarfile.tar.bz2 \(aq/tmp/file_*\(aq # 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 permission 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, zip64=False) 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. .sp Changed in version 2017.7.0: Globbing is now supported for this argument .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. .TP .B zip64 False Used to enable ZIP64 support, necessary to create archives larger than 4 GByte in size. If true, will create ZIP file with the ZIPp64 extension when the zipfile is larger than 2 GB. ZIP64 extension is disabled by default in the Python native zip support because the default zip and unzip commands on Unix (the InfoZIP utilities) don\(aqt support these extensions. .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 # Globbing for sources (2017.7.0 and later) salt \(aq*\(aq archive.zip /tmp/zipfile.zip \(aq/tmp/sourcefile*\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.arista_pyeapi .SS Arista pyeapi .sp New in version 2019.2.0. .sp Execution module to interface the connection with Arista switches, connecting to the remote network device using the \fI\%pyeapi\fP library. It is flexible enough to execute the commands both when running under an Arista Proxy Minion, as well as running under a Regular Minion by specifying the connection arguments, i.e., \fBdevice_type\fP, \fBhost\fP, \fBusername\fP, \fBpassword\fP etc. .INDENT 0.0 .TP .B codeauthor Mircea Ulinic <\fI\%ping@mirceaulinic.net\fP> .TP .B maturity new .TP .B depends pyeapi .TP .B platform unix .UNINDENT .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 To understand how to correctly enable the eAPI on your switch, please check \fI\%https://eos.arista.com/arista\-eapi\-101/\fP\&. .UNINDENT .UNINDENT .SS Dependencies .sp The \fBpyeapi\fP Execution module requires the Python Client for eAPI (pyeapi) to be installed: \fBpip install pyeapi\fP\&. .SS Usage .sp This module can equally be used via the \fBpyeapi\fP Proxy module or directly from an arbitrary (Proxy) Minion that is running on a machine having access to the network device API, and the \fBpyeapi\fP library is installed. .sp When running outside of the \fBpyeapi Proxy\fP (i.e., from another Proxy Minion type, or regular Minion), the pyeapi connection arguments can be either specified from the CLI when executing the command, or in a configuration block under the \fBpyeapi\fP key in the configuration opts (i.e., (Proxy) Minion configuration file), or Pillar. The module supports these simultaneously. These fields are the exact same supported by the \fBpyeapi\fP Proxy Module: .INDENT 0.0 .TP .B transport: \fBhttps\fP Specifies the type of connection transport to use. Valid values for the connection are \fBsocket\fP, \fBhttp_local\fP, \fBhttp\fP, and \fBhttps\fP\&. .TP .B host: \fBlocalhost\fP The IP address or DNS host name of the connection device. .TP .B username: \fBadmin\fP The username to pass to the device to authenticate the eAPI connection. .TP .B password The password to pass to the device to authenticate the eAPI connection. .TP .B port The TCP port of the endpoint for the eAPI connection. If this keyword is not specified, the default value is automatically determined by the transport type (\fB80\fP for \fBhttp\fP, or \fB443\fP for \fBhttps\fP). .TP .B enablepwd The enable mode password if required by the destination node. .UNINDENT .sp Example (when not running in a \fBpyeapi\fP Proxy Minion): .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C pyeapi: username: test password: test .ft P .fi .UNINDENT .UNINDENT .sp In case the \fBusername\fP and \fBpassword\fP are the same on any device you are targeting, the block above (besides other parameters specific to your environment you might need) should suffice to be able to execute commands from outside a \fBpyeapi\fP Proxy, e.g.: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pyeapi.run_commands \(aqshow version\(aq \(aqshow interfaces\(aq salt \(aq*\(aq pyeapi.config \(aqntp server 1.2.3.4\(aq .ft P .fi .UNINDENT .UNINDENT .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 Remember that the above applies only when not running in a \fBpyeapi\fP Proxy Minion. If you want to use the \fBpyeapi Proxy\fP, please follow the documentation notes for a proper setup. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.arista_pyeapi.call(method, *args, **kwargs) Invoke an arbitrary pyeapi method. .INDENT 7.0 .TP .B method The name of the pyeapi method to invoke. .TP .B args A list of arguments to send to the method invoked. .TP .B kwargs Key\-value dictionary to send to the method invoked. .TP .B transport: \fBhttps\fP Specifies the type of connection transport to use. Valid values for the connection are \fBsocket\fP, \fBhttp_local\fP, \fBhttp\fP, and \fBhttps\fP\&. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 This argument does not need to be specified when running in a \fBpyeapi\fP Proxy Minion. .UNINDENT .UNINDENT .TP .B host: \fBlocalhost\fP The IP address or DNS host name of the connection device. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 This argument does not need to be specified when running in a \fBpyeapi\fP Proxy Minion. .UNINDENT .UNINDENT .TP .B username: \fBadmin\fP The username to pass to the device to authenticate the eAPI connection. .INDENT 7.0 .INDENT 3.5 .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 This argument does not need to be specified when running in a \fBpyeapi\fP Proxy Minion. .UNINDENT .UNINDENT .UNINDENT .UNINDENT .TP .B password The password to pass to the device to authenticate the eAPI connection. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 This argument does not need to be specified when running in a \fBpyeapi\fP Proxy Minion. .UNINDENT .UNINDENT .TP .B port The TCP port of the endpoint for the eAPI connection. If this keyword is not specified, the default value is automatically determined by the transport type (\fB80\fP for \fBhttp\fP, or \fB443\fP for \fBhttps\fP). .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 This argument does not need to be specified when running in a \fBpyeapi\fP Proxy Minion. .UNINDENT .UNINDENT .TP .B enablepwd The enable mode password if required by the destination node. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 This argument does not need to be specified when running in a \fBpyeapi\fP Proxy Minion. .UNINDENT .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pyeapi.call run_commands "[\(aqshow version\(aq]" .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.arista_pyeapi.config(commands=None, config_file=None, template_engine=\(aqjinja\(aq, context=None, defaults=None, saltenv=\(aqbase\(aq, **kwargs) Configures the node with the specified commands. .sp This method is used to send configuration commands to the node. It will take either a string or a list and prepend the necessary commands to put the session into config mode. .sp Returns the diff after the configuration commands are loaded. .INDENT 7.0 .TP .B config_file The source file with the configuration commands to be sent to the device. .sp The file can also be a template that can be rendered using the template engine of choice. .sp This can be specified using the absolute path to the file, or using one of the following URL schemes: .INDENT 7.0 .IP \(bu 2 \fBsalt://\fP, to fetch the file from the Salt fileserver. .IP \(bu 2 \fBhttp://\fP or \fBhttps://\fP .IP \(bu 2 \fBftp://\fP .IP \(bu 2 \fBs3://\fP .IP \(bu 2 \fBswift://\fP .UNINDENT .TP .B commands The commands to send to the node in config mode. If the commands argument is a string it will be cast to a list. The list of commands will also be prepended with the necessary commands to put the session in config mode. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 This argument is ignored when \fBconfig_file\fP is specified. .UNINDENT .UNINDENT .TP .B template_engine: \fBjinja\fP The template engine to use when rendering the source file. Default: \fBjinja\fP\&. To simply fetch the file without attempting to render, set this argument to \fBNone\fP\&. .TP .B context Variables to add to the template context. .TP .B defaults Default values of the \fBcontext\fP dict. .TP .B transport: \fBhttps\fP Specifies the type of connection transport to use. Valid values for the connection are \fBsocket\fP, \fBhttp_local\fP, \fBhttp\fP, and \fBhttps\fP\&. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 This argument does not need to be specified when running in a \fBpyeapi\fP Proxy Minion. .UNINDENT .UNINDENT .TP .B host: \fBlocalhost\fP The IP address or DNS host name of the connection device. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 This argument does not need to be specified when running in a \fBpyeapi\fP Proxy Minion. .UNINDENT .UNINDENT .TP .B username: \fBadmin\fP The username to pass to the device to authenticate the eAPI connection. .INDENT 7.0 .INDENT 3.5 .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 This argument does not need to be specified when running in a \fBpyeapi\fP Proxy Minion. .UNINDENT .UNINDENT .UNINDENT .UNINDENT .TP .B password The password to pass to the device to authenticate the eAPI connection. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 This argument does not need to be specified when running in a \fBpyeapi\fP Proxy Minion. .UNINDENT .UNINDENT .TP .B port The TCP port of the endpoint for the eAPI connection. If this keyword is not specified, the default value is automatically determined by the transport type (\fB80\fP for \fBhttp\fP, or \fB443\fP for \fBhttps\fP). .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 This argument does not need to be specified when running in a \fBpyeapi\fP Proxy Minion. .UNINDENT .UNINDENT .TP .B enablepwd The enable mode password if required by the destination node. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 This argument does not need to be specified when running in a \fBpyeapi\fP Proxy Minion. .UNINDENT .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pyeapi.config commands="[\(aqntp server 1.2.3.4\(aq, \(aqntp server 5.6.7.8\(aq]" salt \(aq*\(aq pyeapi.config config_file=salt://config.txt salt \(aq*\(aq pyeapi.config config_file=https://bit.ly/2LGLcDy context="{\(aqservers\(aq: [\(aq1.2.3.4\(aq]}" .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.arista_pyeapi.get_config(config=\(aqrunning\-config\(aq, params=None, as_string=False, **kwargs) Retrieves the config from the device. .sp This method will retrieve the config from the node as either a string or a list object. The config to retrieve can be specified as either the startup\-config or the running\-config. .INDENT 7.0 .TP .B config: \fBrunning\-config\fP Specifies to return either the nodes \fBstartup\-config\fP or \fBrunning\-config\fP\&. The default value is the \fBrunning\-config\fP\&. .TP .B params A string of keywords to append to the command for retrieving the config. .TP .B as_string: \fBFalse\fP Flag that determines the response. If \fBTrue\fP, then the configuration is returned as a raw string. If \fBFalse\fP, then the configuration is returned as a list. The default value is \fBFalse\fP\&. .TP .B transport: \fBhttps\fP Specifies the type of connection transport to use. Valid values for the connection are \fBsocket\fP, \fBhttp_local\fP, \fBhttp\fP, and \fBhttps\fP\&. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 This argument does not need to be specified when running in a \fBpyeapi\fP Proxy Minion. .UNINDENT .UNINDENT .TP .B host: \fBlocalhost\fP The IP address or DNS host name of the connection device. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 This argument does not need to be specified when running in a \fBpyeapi\fP Proxy Minion. .UNINDENT .UNINDENT .TP .B username: \fBadmin\fP The username to pass to the device to authenticate the eAPI connection. .INDENT 7.0 .INDENT 3.5 .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 This argument does not need to be specified when running in a \fBpyeapi\fP Proxy Minion. .UNINDENT .UNINDENT .UNINDENT .UNINDENT .TP .B password The password to pass to the device to authenticate the eAPI connection. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 This argument does not need to be specified when running in a \fBpyeapi\fP Proxy Minion. .UNINDENT .UNINDENT .TP .B port The TCP port of the endpoint for the eAPI connection. If this keyword is not specified, the default value is automatically determined by the transport type (\fB80\fP for \fBhttp\fP, or \fB443\fP for \fBhttps\fP). .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 This argument does not need to be specified when running in a \fBpyeapi\fP Proxy Minion. .UNINDENT .UNINDENT .TP .B enablepwd The enable mode password if required by the destination node. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 This argument does not need to be specified when running in a \fBpyeapi\fP Proxy Minion. .UNINDENT .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pyeapi.get_config salt \(aq*\(aq pyeapi.get_config params=\(aqsection snmp\-server\(aq salt \(aq*\(aq pyeapi.get_config config=\(aqstartup\-config\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.arista_pyeapi.get_connection(**kwargs) Return the connection object to the pyeapi Node. .sp \fBWARNING:\fP .INDENT 7.0 .INDENT 3.5 This function returns an unserializable object, hence it is not meant to be used on the CLI. This should mainly be used when invoked from other modules for the low level connection with the network device. .UNINDENT .UNINDENT .INDENT 7.0 .TP .B kwargs Key\-value dictionary with the authentication details. .UNINDENT .sp USAGE Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C conn = __salt__[\(aqpyeapi.get_connection\(aq](host=\(aqrouter1.example.com\(aq, username=\(aqexample\(aq, password=\(aqexample\(aq) show_ver = conn.run_commands([\(aqshow version\(aq, \(aqshow interfaces\(aq]) .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.arista_pyeapi.run_commands(*commands, **kwargs) Sends the commands over the transport to the device. .sp This function sends the commands to the device using the nodes transport. This is a lower layer function that shouldn\(aqt normally need to be used, preferring instead to use \fBconfig()\fP or \fBenable()\fP\&. .INDENT 7.0 .TP .B transport: \fBhttps\fP Specifies the type of connection transport to use. Valid values for the connection are \fBsocket\fP, \fBhttp_local\fP, \fBhttp\fP, and \fBhttps\fP\&. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 This argument does not need to be specified when running in a \fBpyeapi\fP Proxy Minion. .UNINDENT .UNINDENT .TP .B host: \fBlocalhost\fP The IP address or DNS host name of the connection device. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 This argument does not need to be specified when running in a \fBpyeapi\fP Proxy Minion. .UNINDENT .UNINDENT .TP .B username: \fBadmin\fP The username to pass to the device to authenticate the eAPI connection. .INDENT 7.0 .INDENT 3.5 .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 This argument does not need to be specified when running in a \fBpyeapi\fP Proxy Minion. .UNINDENT .UNINDENT .UNINDENT .UNINDENT .TP .B password The password to pass to the device to authenticate the eAPI connection. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 This argument does not need to be specified when running in a \fBpyeapi\fP Proxy Minion. .UNINDENT .UNINDENT .TP .B port The TCP port of the endpoint for the eAPI connection. If this keyword is not specified, the default value is automatically determined by the transport type (\fB80\fP for \fBhttp\fP, or \fB443\fP for \fBhttps\fP). .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 This argument does not need to be specified when running in a \fBpyeapi\fP Proxy Minion. .UNINDENT .UNINDENT .TP .B enablepwd The enable mode password if required by the destination node. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 This argument does not need to be specified when running in a \fBpyeapi\fP Proxy Minion. .UNINDENT .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq pyeapi.run_commands \(aqshow version\(aq salt \(aq*\(aq pyeapi.run_commands \(aqshow version\(aq encoding=text salt \(aq*\(aq pyeapi.run_commands \(aqshow version\(aq encoding=text host=cr1.thn.lon username=example password=weak .ft P .fi .UNINDENT .UNINDENT .sp Output example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C veos1: |_ \-\-\-\-\-\-\-\-\-\- architecture: i386 bootupTimestamp: 1527541728.53 hardwareRevision: internalBuildId: 63d2e89a\-220d\-4b8a\-a9b3\-0524fa8f9c5f internalVersion: 4.18.1F\-4591672.4181F isIntlVersion: False memFree: 501468 memTotal: 1893316 modelName: vEOS serialNumber: systemMacAddress: 52:54:00:3f:e6:d0 version: 4.18.1F .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.arista_pyeapi.section(regex, config=\(aqrunning\-config\(aq, **kwargs) Return a section of the config. .INDENT 7.0 .TP .B regex A valid regular expression used to select sections of configuration to return. .TP .B config: \fBrunning\-config\fP The configuration to return. Valid values for config are \fBrunning\-config\fP or \fBstartup\-config\fP\&. The default value is \fBrunning\-config\fP\&. .TP .B transport: \fBhttps\fP Specifies the type of connection transport to use. Valid values for the connection are \fBsocket\fP, \fBhttp_local\fP, \fBhttp\fP, and \fBhttps\fP\&. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 This argument does not need to be specified when running in a \fBpyeapi\fP Proxy Minion. .UNINDENT .UNINDENT .TP .B host: \fBlocalhost\fP The IP address or DNS host name of the connection device. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 This argument does not need to be specified when running in a \fBpyeapi\fP Proxy Minion. .UNINDENT .UNINDENT .TP .B username: \fBadmin\fP The username to pass to the device to authenticate the eAPI connection. .INDENT 7.0 .INDENT 3.5 .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 This argument does not need to be specified when running in a \fBpyeapi\fP Proxy Minion. .UNINDENT .UNINDENT .UNINDENT .UNINDENT .TP .B password The password to pass to the device to authenticate the eAPI connection. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 This argument does not need to be specified when running in a \fBpyeapi\fP Proxy Minion. .UNINDENT .UNINDENT .TP .B port The TCP port of the endpoint for the eAPI connection. If this keyword is not specified, the default value is automatically determined by the transport type (\fB80\fP for \fBhttp\fP, or \fB443\fP for \fBhttps\fP). .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 This argument does not need to be specified when running in a \fBpyeapi\fP Proxy Minion. .UNINDENT .UNINDENT .TP .B enablepwd The enable mode password if required by the destination node. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 This argument does not need to be specified when running in a \fBpyeapi\fP Proxy Minion. .UNINDENT .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.artifactory .sp Module for fetching artifacts from Artifactory .INDENT 0.0 .TP .B exception salt.modules.artifactory.ArtifactoryError(value) .UNINDENT .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, use_literal_group_id=False) 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, use_literal_group_id=False) 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, use_literal_group_id=False) 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, use_literal_group_id=False) 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 platform linux,openbsd,freebsd .UNINDENT .sp Changed in version 2017.7.0. .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.at_solaris .sp Wrapper for at(1) on Solaris\-like systems .sp \fBNOTE:\fP .INDENT 0.0 .INDENT 3.5 we try to mirror the generic at module where possible .UNINDENT .UNINDENT .INDENT 0.0 .TP .B maintainer jorge schrauwen <\fI\%sjorge@blackdot.be\fP> .TP .B maturity new .TP .B platform solaris,illumos,smartso .UNINDENT .sp New in version 2017.7.0. .INDENT 0.0 .TP .B salt.modules.at_solaris.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_solaris.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_solaris.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_solaris.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_solaris.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.azurearm_compute .sp Azure (ARM) Compute Execution Module .sp New in version 2019.2.0. .INDENT 0.0 .TP .B maintainer <\fI\%devops@decisionlab.io\fP> .TP .B maturity new .TP .B depends .INDENT 7.0 .IP \(bu 2 \fI\%azure\fP >= 2.0.0 .IP \(bu 2 \fI\%azure\-common\fP >= 1.1.8 .IP \(bu 2 \fI\%azure\-mgmt\fP >= 1.0.0 .IP \(bu 2 \fI\%azure\-mgmt\-compute\fP >= 1.0.0 .IP \(bu 2 \fI\%azure\-mgmt\-network\fP >= 1.7.1 .IP \(bu 2 \fI\%azure\-mgmt\-resource\fP >= 1.1.0 .IP \(bu 2 \fI\%azure\-mgmt\-storage\fP >= 1.0.0 .IP \(bu 2 \fI\%azure\-mgmt\-web\fP >= 0.32.0 .IP \(bu 2 \fI\%azure\-storage\fP >= 0.34.3 .IP \(bu 2 \fI\%msrestazure\fP >= 0.4.21 .UNINDENT .TP .B platform linux .TP .B configuration This module requires Azure Resource Manager credentials to be passed as keyword arguments to every function in order to work properly. .sp Required provider parameters: .INDENT 7.0 .TP .B if using username and password: .INDENT 7.0 .IP \(bu 2 \fBsubscription_id\fP .IP \(bu 2 \fBusername\fP .IP \(bu 2 \fBpassword\fP .UNINDENT .TP .B if using a service principal: .INDENT 7.0 .IP \(bu 2 \fBsubscription_id\fP .IP \(bu 2 \fBtenant\fP .IP \(bu 2 \fBclient_id\fP .IP \(bu 2 \fBsecret\fP .UNINDENT .UNINDENT .sp Optional provider parameters: .UNINDENT .INDENT 0.0 .TP \fBcloud_environment\fP: Used to point the cloud driver to different API endpoints, such as Azure GovCloud. .INDENT 7.0 .TP .B Possible values: .INDENT 7.0 .IP \(bu 2 \fBAZURE_PUBLIC_CLOUD\fP (default) .IP \(bu 2 \fBAZURE_CHINA_CLOUD\fP .IP \(bu 2 \fBAZURE_US_GOV_CLOUD\fP .IP \(bu 2 \fBAZURE_GERMAN_CLOUD\fP .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.azurearm_compute.availability_set_create_or_update(name, resource_group, **kwargs) New in version 2019.2.0. .sp Create or update an availability set. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBname\fP \-\- The availability set to create. .IP \(bu 2 \fBresource_group\fP \-\- The resource group name assigned to the availability set. .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-call azurearm_compute.availability_set_create_or_update testset testgroup .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.azurearm_compute.availability_set_delete(name, resource_group, **kwargs) New in version 2019.2.0. .sp Delete an availability set. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBname\fP \-\- The availability set to delete. .IP \(bu 2 \fBresource_group\fP \-\- The resource group name assigned to the availability set. .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-call azurearm_compute.availability_set_delete testset testgroup .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.azurearm_compute.availability_set_get(name, resource_group, **kwargs) New in version 2019.2.0. .sp Get a dictionary representing an availability set\(aqs properties. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBname\fP \-\- The availability set to get. .IP \(bu 2 \fBresource_group\fP \-\- The resource group name assigned to the availability set. .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-call azurearm_compute.availability_set_get testset testgroup .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.azurearm_compute.availability_sets_list(resource_group, **kwargs) New in version 2019.2.0. .sp List all availability sets within a resource group. .INDENT 7.0 .TP .B Parameters \fBresource_group\fP \-\- The resource group name to list availability sets within. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-call azurearm_compute.availability_sets_list testgroup .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.azurearm_compute.availability_sets_list_available_sizes(name, resource_group, **kwargs) New in version 2019.2.0. .sp List all available virtual machine sizes that can be used to to create a new virtual machine in an existing availability set. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBname\fP \-\- The availability set name to list available virtual machine sizes within. .IP \(bu 2 \fBresource_group\fP \-\- The resource group name to list available availability set sizes within. .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-call azurearm_compute.availability_sets_list_available_sizes testset testgroup .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.azurearm_compute.virtual_machine_capture(name, destination_name, resource_group, prefix=\(aqcapture\-\(aq, overwrite=False, **kwargs) New in version 2019.2.0. .sp Captures the VM by copying virtual hard disks of the VM and outputs a template that can be used to create similar VMs. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBname\fP \-\- The name of the virtual machine. .IP \(bu 2 \fBdestination_name\fP \-\- The destination container name. .IP \(bu 2 \fBresource_group\fP \-\- The resource group name assigned to the virtual machine. .IP \(bu 2 \fBprefix\fP \-\- (Default: \(aqcapture\-\(aq) The captured virtual hard disk\(aqs name prefix. .IP \(bu 2 \fBoverwrite\fP \-\- (Default: False) Overwrite the destination disk in case of conflict. .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-call azurearm_compute.virtual_machine_capture testvm testcontainer testgroup .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.azurearm_compute.virtual_machine_convert_to_managed_disks(name, resource_group, **kwargs) New in version 2019.2.0. .sp Converts virtual machine disks from blob\-based to managed disks. Virtual machine must be stop\-deallocated before invoking this operation. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBname\fP \-\- The name of the virtual machine to convert. .IP \(bu 2 \fBresource_group\fP \-\- The resource group name assigned to the virtual machine. .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-call azurearm_compute.virtual_machine_convert_to_managed_disks testvm testgroup .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.azurearm_compute.virtual_machine_deallocate(name, resource_group, **kwargs) New in version 2019.2.0. .sp Power off a virtual machine and deallocate compute resources. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBname\fP \-\- The name of the virtual machine to deallocate. .IP \(bu 2 \fBresource_group\fP \-\- The resource group name assigned to the virtual machine. .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-call azurearm_compute.virtual_machine_deallocate testvm testgroup .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.azurearm_compute.virtual_machine_generalize(name, resource_group, **kwargs) New in version 2019.2.0. .sp Set the state of a virtual machine to \(aqgeneralized\(aq. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBname\fP \-\- The name of the virtual machine. .IP \(bu 2 \fBresource_group\fP \-\- The resource group name assigned to the virtual machine. .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-call azurearm_compute.virtual_machine_generalize testvm testgroup .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.azurearm_compute.virtual_machine_get(name, resource_group, **kwargs) New in version 2019.2.0. .sp Retrieves information about the model view or the instance view of a virtual machine. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBname\fP \-\- The name of the virtual machine. .IP \(bu 2 \fBresource_group\fP \-\- The resource group name assigned to the virtual machine. .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-call azurearm_compute.virtual_machine_get testvm testgroup .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.azurearm_compute.virtual_machine_power_off(name, resource_group, **kwargs) New in version 2019.2.0. .sp Power off (stop) a virtual machine. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBname\fP \-\- The name of the virtual machine to stop. .IP \(bu 2 \fBresource_group\fP \-\- The resource group name assigned to the virtual machine. .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-call azurearm_compute.virtual_machine_power_off testvm testgroup .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.azurearm_compute.virtual_machine_redeploy(name, resource_group, **kwargs) New in version 2019.2.0. .sp Redeploy a virtual machine. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBname\fP \-\- The name of the virtual machine to redeploy. .IP \(bu 2 \fBresource_group\fP \-\- The resource group name assigned to the virtual machine. .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-call azurearm_compute.virtual_machine_redeploy testvm testgroup .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.azurearm_compute.virtual_machine_restart(name, resource_group, **kwargs) New in version 2019.2.0. .sp Restart a virtual machine. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBname\fP \-\- The name of the virtual machine to restart. .IP \(bu 2 \fBresource_group\fP \-\- The resource group name assigned to the virtual machine. .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-call azurearm_compute.virtual_machine_restart testvm testgroup .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.azurearm_compute.virtual_machine_start(name, resource_group, **kwargs) New in version 2019.2.0. .sp Power on (start) a virtual machine. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBname\fP \-\- The name of the virtual machine to start. .IP \(bu 2 \fBresource_group\fP \-\- The resource group name assigned to the virtual machine. .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-call azurearm_compute.virtual_machine_start testvm testgroup .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.azurearm_compute.virtual_machines_list(resource_group, **kwargs) New in version 2019.2.0. .sp List all virtual machines within a resource group. .INDENT 7.0 .TP .B Parameters \fBresource_group\fP \-\- The resource group name to list virtual machines within. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-call azurearm_compute.virtual_machines_list testgroup .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.azurearm_compute.virtual_machines_list_all(**kwargs) New in version 2019.2.0. .sp List all virtual machines within a subscription. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-call azurearm_compute.virtual_machines_list_all .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.azurearm_compute.virtual_machines_list_available_sizes(name, resource_group, **kwargs) New in version 2019.2.0. .sp Lists all available virtual machine sizes to which the specified virtual machine can be resized. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBname\fP \-\- The name of the virtual machine. .IP \(bu 2 \fBresource_group\fP \-\- The resource group name assigned to the virtual machine. .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-call azurearm_compute.virtual_machines_list_available_sizes testvm testgroup .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.azurearm_dns module .sp Azure (ARM) DNS Execution Module .sp New in version 3000. .INDENT 0.0 .TP .B maintainer <\fI\%devops@eitr.tech\fP> .TP .B maturity new .TP .B depends .INDENT 7.0 .IP \(bu 2 \fI\%azure\fP >= 2.0.0 .IP \(bu 2 \fI\%azure\-common\fP >= 1.1.8 .IP \(bu 2 \fI\%azure\-mgmt\fP >= 1.0.0 .IP \(bu 2 \fI\%azure\-mgmt\-compute\fP >= 1.0.0 .IP \(bu 2 \fI\%azure\-mgmt\-dns\fP >= 2.0.0rc1 .IP \(bu 2 \fI\%azure\-mgmt\-network\fP >= 1.7.1 .IP \(bu 2 \fI\%azure\-mgmt\-resource\fP >= 1.1.0 .IP \(bu 2 \fI\%azure\-mgmt\-storage\fP >= 1.0.0 .IP \(bu 2 \fI\%azure\-mgmt\-web\fP >= 0.32.0 .IP \(bu 2 \fI\%azure\-storage\fP >= 0.34.3 .IP \(bu 2 \fI\%msrestazure\fP >= 0.4.21 .UNINDENT .TP .B platform linux .TP .B configuration This module requires Azure Resource Manager credentials to be passed as keyword arguments to every function in order to work properly. .UNINDENT .sp Required provider parameters: .INDENT 0.0 .INDENT 3.5 if using username and password: .INDENT 0.0 .INDENT 3.5 .INDENT 0.0 .IP \(bu 2 \fBsubscription_id\fP .IP \(bu 2 \fBusername\fP .IP \(bu 2 \fBpassword\fP .UNINDENT .UNINDENT .UNINDENT .sp if using a service principal: .INDENT 0.0 .INDENT 3.5 .INDENT 0.0 .IP \(bu 2 \fBsubscription_id\fP .IP \(bu 2 \fBtenant\fP .IP \(bu 2 \fBclient_id\fP .IP \(bu 2 \fBsecret\fP .UNINDENT .UNINDENT .UNINDENT .UNINDENT .UNINDENT .sp Optional provider parameters: .INDENT 0.0 .INDENT 3.5 \fBcloud_environment\fP: Used to point the cloud driver to different API endpoints, such as Azure GovCloud. .sp Possible values: .INDENT 0.0 .INDENT 3.5 .INDENT 0.0 .IP \(bu 2 \fBAZURE_PUBLIC_CLOUD\fP (default) .IP \(bu 2 \fBAZURE_CHINA_CLOUD\fP .IP \(bu 2 \fBAZURE_US_GOV_CLOUD\fP .IP \(bu 2 \fBAZURE_GERMAN_CLOUD\fP .UNINDENT .UNINDENT .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.azurearm_dns.record_set_create_or_update(name, zone_name, resource_group, record_type, **kwargs) New in version 3000. .sp Creates or updates a record set within a DNS zone. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBname\fP \-\- The name of the record set, relative to the name of the zone. .IP \(bu 2 \fBzone_name\fP \-\- The name of the DNS zone (without a terminating dot). .IP \(bu 2 \fBresource_group\fP \-\- The name of the resource group. .IP \(bu 2 \fBrecord_type\fP \-\- The type of DNS record in this record set. Record sets of type SOA can be updated but not created (they are created when the DNS zone is created). Possible values include: \(aqA\(aq, \(aqAAAA\(aq, \(aqCAA\(aq, \(aqCNAME\(aq, \(aqMX\(aq, \(aqNS\(aq, \(aqPTR\(aq, \(aqSOA\(aq, \(aqSRV\(aq, \(aqTXT\(aq .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-call azurearm_dns.record_set_create_or_update myhost myzone testgroup A arecords=\(aq[{ipv4_address: 10.0.0.1}]\(aq ttl=300 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.azurearm_dns.record_set_delete(name, zone_name, resource_group, record_type, **kwargs) New in version 3000. .sp Deletes a record set from a DNS zone. This operation cannot be undone. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBname\fP \-\- The name of the record set, relative to the name of the zone. .IP \(bu 2 \fBzone_name\fP \-\- The name of the DNS zone (without a terminating dot). .IP \(bu 2 \fBresource_group\fP \-\- The name of the resource group. .IP \(bu 2 \fBrecord_type\fP \-\- The type of DNS record in this record set. Record sets of type SOA cannot be deleted (they are deleted when the DNS zone is deleted). Possible values include: \(aqA\(aq, \(aqAAAA\(aq, \(aqCAA\(aq, \(aqCNAME\(aq, \(aqMX\(aq, \(aqNS\(aq, \(aqPTR\(aq, \(aqSOA\(aq, \(aqSRV\(aq, \(aqTXT\(aq .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-call azurearm_dns.record_set_delete myhost myzone testgroup A .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.azurearm_dns.record_set_get(name, zone_name, resource_group, record_type, **kwargs) New in version 3000. .sp Get a dictionary representing a record set\(aqs properties. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBname\fP \-\- The name of the record set, relative to the name of the zone. .IP \(bu 2 \fBzone_name\fP \-\- The name of the DNS zone (without a terminating dot). .IP \(bu 2 \fBresource_group\fP \-\- The name of the resource group. .IP \(bu 2 \fBrecord_type\fP \-\- The type of DNS record in this record set. Possible values include: \(aqA\(aq, \(aqAAAA\(aq, \(aqCAA\(aq, \(aqCNAME\(aq, \(aqMX\(aq, \(aqNS\(aq, \(aqPTR\(aq, \(aqSOA\(aq, \(aqSRV\(aq, \(aqTXT\(aq .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-call azurearm_dns.record_set_get \(aq@\(aq myzone testgroup SOA .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.azurearm_dns.record_sets_list_by_dns_zone(zone_name, resource_group, top=None, recordsetnamesuffix=None, **kwargs) New in version 3000. .sp Lists all record sets in a DNS zone. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBzone_name\fP \-\- The name of the DNS zone (without a terminating dot). .IP \(bu 2 \fBresource_group\fP \-\- The name of the resource group. .IP \(bu 2 \fBtop\fP \-\- The maximum number of record sets to return. If not specified, returns up to 100 record sets. .IP \(bu 2 \fBrecordsetnamesuffix\fP \-\- The suffix label of the record set name that has to be used to filter the record set enumerations. .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-call azurearm_dns.record_sets_list_by_dns_zone myzone testgroup .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.azurearm_dns.record_sets_list_by_type(zone_name, resource_group, record_type, top=None, recordsetnamesuffix=None, **kwargs) New in version 3000. .sp Lists the record sets of a specified type in a DNS zone. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBzone_name\fP \-\- The name of the DNS zone (without a terminating dot). .IP \(bu 2 \fBresource_group\fP \-\- The name of the resource group. .IP \(bu 2 \fBrecord_type\fP \-\- The type of record sets to enumerate. Possible values include: \(aqA\(aq, \(aqAAAA\(aq, \(aqCAA\(aq, \(aqCNAME\(aq, \(aqMX\(aq, \(aqNS\(aq, \(aqPTR\(aq, \(aqSOA\(aq, \(aqSRV\(aq, \(aqTXT\(aq .IP \(bu 2 \fBtop\fP \-\- The maximum number of record sets to return. If not specified, returns up to 100 record sets. .IP \(bu 2 \fBrecordsetnamesuffix\fP \-\- The suffix label of the record set name that has to be used to filter the record set enumerations. .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-call azurearm_dns.record_sets_list_by_type myzone testgroup SOA .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.azurearm_dns.zone_create_or_update(name, resource_group, **kwargs) New in version 3000. .sp Creates or updates a DNS zone. Does not modify DNS records within the zone. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBname\fP \-\- The name of the DNS zone to create (without a terminating dot). .IP \(bu 2 \fBresource_group\fP \-\- The name of the resource group. .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-call azurearm_dns.zone_create_or_update myzone testgroup .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.azurearm_dns.zone_delete(name, resource_group, **kwargs) New in version 3000. .sp Delete a DNS zone within a resource group. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBname\fP \-\- The name of the DNS zone to delete. .IP \(bu 2 \fBresource_group\fP \-\- The name of the resource group. .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-call azurearm_dns.zone_delete myzone testgroup .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.azurearm_dns.zone_get(name, resource_group, **kwargs) New in version 3000. .sp Get a dictionary representing a DNS zone\(aqs properties, but not the record sets within the zone. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBname\fP \-\- The DNS zone to get. .IP \(bu 2 \fBresource_group\fP \-\- The name of the resource group. .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-call azurearm_dns.zone_get myzone testgroup .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.azurearm_dns.zones_list(top=None, **kwargs) New in version 3000. .sp Lists the DNS zones in all resource groups in a subscription. .INDENT 7.0 .TP .B Parameters \fBtop\fP \-\- The maximum number of DNS zones to return. If not specified, eturns up to 100 zones. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-call azurearm_dns.zones_list .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.azurearm_dns.zones_list_by_resource_group(resource_group, top=None, **kwargs) New in version 3000. .sp Lists the DNS zones in a resource group. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBresource_group\fP \-\- The name of the resource group. .IP \(bu 2 \fBtop\fP \-\- The maximum number of DNS zones to return. If not specified, returns up to 100 zones. .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-call azurearm_dns.zones_list_by_resource_group testgroup .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.azurearm_network .sp Azure (ARM) Network Execution Module .sp New in version 2019.2.0. .INDENT 0.0 .TP .B maintainer <\fI\%devops@decisionlab.io\fP> .TP .B maturity new .TP .B depends .INDENT 7.0 .IP \(bu 2 \fI\%azure\fP >= 2.0.0 .IP \(bu 2 \fI\%azure\-common\fP >= 1.1.8 .IP \(bu 2 \fI\%azure\-mgmt\fP >= 1.0.0 .IP \(bu 2 \fI\%azure\-mgmt\-compute\fP >= 1.0.0 .IP \(bu 2 \fI\%azure\-mgmt\-network\fP >= 1.7.1 .IP \(bu 2 \fI\%azure\-mgmt\-resource\fP >= 1.1.0 .IP \(bu 2 \fI\%azure\-mgmt\-storage\fP >= 1.0.0 .IP \(bu 2 \fI\%azure\-mgmt\-web\fP >= 0.32.0 .IP \(bu 2 \fI\%azure\-storage\fP >= 0.34.3 .IP \(bu 2 \fI\%msrestazure\fP >= 0.4.21 .UNINDENT .TP .B platform linux .TP .B configuration This module requires Azure Resource Manager credentials to be passed as keyword arguments to every function in order to work properly. .sp Required provider parameters: .INDENT 7.0 .TP .B if using username and password: .INDENT 7.0 .IP \(bu 2 \fBsubscription_id\fP .IP \(bu 2 \fBusername\fP .IP \(bu 2 \fBpassword\fP .UNINDENT .TP .B if using a service principal: .INDENT 7.0 .IP \(bu 2 \fBsubscription_id\fP .IP \(bu 2 \fBtenant\fP .IP \(bu 2 \fBclient_id\fP .IP \(bu 2 \fBsecret\fP .UNINDENT .UNINDENT .sp Optional provider parameters: .UNINDENT .INDENT 0.0 .TP \fBcloud_environment\fP: Used to point the cloud driver to different API endpoints, such as Azure GovCloud. .INDENT 7.0 .TP .B Possible values: .INDENT 7.0 .IP \(bu 2 \fBAZURE_PUBLIC_CLOUD\fP (default) .IP \(bu 2 \fBAZURE_CHINA_CLOUD\fP .IP \(bu 2 \fBAZURE_US_GOV_CLOUD\fP .IP \(bu 2 \fBAZURE_GERMAN_CLOUD\fP .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.azurearm_network.check_dns_name_availability(name, region, **kwargs) New in version 2019.2.0. .sp Check whether a domain name in the current zone is available for use. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBname\fP \-\- The DNS name to query. .IP \(bu 2 \fBregion\fP \-\- The region to query for the DNS name in question. .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-call azurearm_network.check_dns_name_availability testdnsname westus .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.azurearm_network.check_ip_address_availability(ip_address, virtual_network, resource_group, **kwargs) New in version 2019.2.0. .sp Check that a private ip address is available within the specified virtual network. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBip_address\fP \-\- The ip_address to query. .IP \(bu 2 \fBvirtual_network\fP \-\- The virtual network to query for the IP address in question. .IP \(bu 2 \fBresource_group\fP \-\- The resource group name assigned to the virtual network. .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-call azurearm_network.check_ip_address_availability 10.0.0.4 testnet testgroup .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.azurearm_network.default_security_rule_get(name, security_group, resource_group, **kwargs) New in version 2019.2.0. .sp Get details about a default security rule within a security group. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBname\fP \-\- The name of the security rule to query. .IP \(bu 2 \fBsecurity_group\fP \-\- The network security group containing the security rule. .IP \(bu 2 \fBresource_group\fP \-\- The resource group name assigned to the network security group. .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-call azurearm_network.default_security_rule_get DenyAllOutBound testnsg testgroup .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.azurearm_network.default_security_rules_list(security_group, resource_group, **kwargs) New in version 2019.2.0. .sp List default security rules within a security group. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBsecurity_group\fP \-\- The network security group to query. .IP \(bu 2 \fBresource_group\fP \-\- The resource group name assigned to the network security group. .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-call azurearm_network.default_security_rules_list testnsg testgroup .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.azurearm_network.get_virtual_machine_scale_set_network_interface(name, scale_set, vm_index, resource_group, **kwargs) New in version 2019.2.0. .sp Get information about a specific network interface within a scale set. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBname\fP \-\- The name of the network interface to query. .IP \(bu 2 \fBscale_set\fP \-\- The name of the scale set containing the interface. .IP \(bu 2 \fBvm_index\fP \-\- The virtual machine index. .IP \(bu 2 \fBresource_group\fP \-\- The resource group name assigned to the scale set. .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-call azurearm_network.get_virtual_machine_scale_set_network_interface test\-iface0 testset testvm testgroup .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.azurearm_network.list_virtual_machine_scale_set_network_interfaces(scale_set, resource_group, **kwargs) New in version 2019.2.0. .sp Get information about all network interfaces within a scale set. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBscale_set\fP \-\- The name of the scale set to query. .IP \(bu 2 \fBresource_group\fP \-\- The resource group name assigned to the scale set. .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-call azurearm_network.list_virtual_machine_scale_set_vm_network_interfaces testset testgroup .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.azurearm_network.list_virtual_machine_scale_set_vm_network_interfaces(scale_set, vm_index, resource_group, **kwargs) New in version 2019.2.0. .sp Get information about all network interfaces in a specific virtual machine within a scale set. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBscale_set\fP \-\- The name of the scale set to query. .IP \(bu 2 \fBvm_index\fP \-\- The virtual machine index. .IP \(bu 2 \fBresource_group\fP \-\- The resource group name assigned to the scale set. .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-call azurearm_network.list_virtual_machine_scale_set_vm_network_interfaces testset testvm testgroup .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.azurearm_network.load_balancer_create_or_update(name, resource_group, **kwargs) New in version 2019.2.0. .sp Create or update a load balancer within a specified resource group. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBname\fP \-\- The name of the load balancer to create. .IP \(bu 2 \fBresource_group\fP \-\- The resource group name assigned to the load balancer. .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-call azurearm_network.load_balancer_create_or_update testlb testgroup .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.azurearm_network.load_balancer_delete(name, resource_group, **kwargs) New in version 2019.2.0. .sp Delete a load balancer. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBname\fP \-\- The name of the load balancer to delete. .IP \(bu 2 \fBresource_group\fP \-\- The resource group name assigned to the load balancer. .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-call azurearm_network.load_balancer_delete testlb testgroup .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.azurearm_network.load_balancer_get(name, resource_group, **kwargs) New in version 2019.2.0. .sp Get details about a specific load balancer. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBname\fP \-\- The name of the load balancer to query. .IP \(bu 2 \fBresource_group\fP \-\- The resource group name assigned to the load balancer. .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-call azurearm_network.load_balancer_get testlb testgroup .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.azurearm_network.load_balancers_list(resource_group, **kwargs) New in version 2019.2.0. .sp List all load balancers within a resource group. .INDENT 7.0 .TP .B Parameters \fBresource_group\fP \-\- The resource group name to list load balancers within. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-call azurearm_network.load_balancers_list testgroup .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.azurearm_network.load_balancers_list_all(**kwargs) New in version 2019.2.0. .sp List all load balancers within a subscription. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-call azurearm_network.load_balancers_list_all .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.azurearm_network.network_interface_create_or_update(name, ip_configurations, subnet, virtual_network, resource_group, **kwargs) New in version 2019.2.0. .sp Create or update a network interface within a specified resource group. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBname\fP \-\- The name of the network interface to create. .IP \(bu 2 \fBip_configurations\fP \-\- A list of dictionaries representing valid NetworkInterfaceIPConfiguration objects. The \(aqname\(aq key is required at minimum. At least one IP Configuration must be present. .IP \(bu 2 \fBsubnet\fP \-\- The name of the subnet assigned to the network interface. .IP \(bu 2 \fBvirtual_network\fP \-\- The name of the virtual network assigned to the subnet. .IP \(bu 2 \fBresource_group\fP \-\- The resource group name assigned to the virtual network. .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-call azurearm_network.network_interface_create_or_update test\-iface0 [{\(aqname\(aq: \(aqtestipconfig1\(aq}] testsubnet testnet testgroup .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.azurearm_network.network_interface_delete(name, resource_group, **kwargs) New in version 2019.2.0. .sp Delete a network interface. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBname\fP \-\- The name of the network interface to delete. .IP \(bu 2 \fBresource_group\fP \-\- The resource group name assigned to the network interface. .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-call azurearm_network.network_interface_delete test\-iface0 testgroup .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.azurearm_network.network_interface_get(name, resource_group, **kwargs) New in version 2019.2.0. .sp Get details about a specific network interface. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBname\fP \-\- The name of the network interface to query. .IP \(bu 2 \fBresource_group\fP \-\- The resource group name assigned to the network interface. .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-call azurearm_network.network_interface_get test\-iface0 testgroup .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.azurearm_network.network_interface_get_effective_route_table(name, resource_group, **kwargs) New in version 2019.2.0. .sp Get all route tables for a specific network interface. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBname\fP \-\- The name of the network interface to query. .IP \(bu 2 \fBresource_group\fP \-\- The resource group name assigned to the network interface. .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-call azurearm_network.network_interface_get_effective_route_table test\-iface0 testgroup .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.azurearm_network.network_interface_list_effective_network_security_groups(name, resource_group, **kwargs) New in version 2019.2.0. .sp Get all network security groups applied to a specific network interface. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBname\fP \-\- The name of the network interface to query. .IP \(bu 2 \fBresource_group\fP \-\- The resource group name assigned to the network interface. .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-call azurearm_network.network_interface_list_effective_network_security_groups test\-iface0 testgroup .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.azurearm_network.network_interfaces_list(resource_group, **kwargs) New in version 2019.2.0. .sp List all network interfaces within a resource group. .INDENT 7.0 .TP .B Parameters \fBresource_group\fP \-\- The resource group name to list network interfaces within. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-call azurearm_network.network_interfaces_list testgroup .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.azurearm_network.network_interfaces_list_all(**kwargs) New in version 2019.2.0. .sp List all network interfaces within a subscription. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-call azurearm_network.network_interfaces_list_all .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.azurearm_network.network_security_group_create_or_update(name, resource_group, **kwargs) New in version 2019.2.0. .sp Create or update a network security group. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBname\fP \-\- The name of the network security group to create. .IP \(bu 2 \fBresource_group\fP \-\- The resource group name assigned to the network security group. .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-call azurearm_network.network_security_group_create_or_update testnsg testgroup .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.azurearm_network.network_security_group_delete(name, resource_group, **kwargs) New in version 2019.2.0. .sp Delete a network security group within a resource group. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBname\fP \-\- The name of the network security group to delete. .IP \(bu 2 \fBresource_group\fP \-\- The resource group name assigned to the network security group. .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-call azurearm_network.network_security_group_delete testnsg testgroup .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.azurearm_network.network_security_group_get(name, resource_group, **kwargs) New in version 2019.2.0. .sp Get details about a network security group within a resource group. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBname\fP \-\- The name of the network security group to query. .IP \(bu 2 \fBresource_group\fP \-\- The resource group name assigned to the network security group. .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-call azurearm_network.network_security_group_get testnsg testgroup .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.azurearm_network.network_security_groups_list(resource_group, **kwargs) New in version 2019.2.0. .sp List all network security groups within a resource group. .INDENT 7.0 .TP .B Parameters \fBresource_group\fP \-\- The resource group name to list network security groups within. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-call azurearm_network.network_security_groups_list testgroup .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.azurearm_network.network_security_groups_list_all(**kwargs) New in version 2019.2.0. .sp List all network security groups within a subscription. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-call azurearm_network.network_security_groups_list_all .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.azurearm_network.public_ip_address_create_or_update(name, resource_group, **kwargs) New in version 2019.2.0. .sp Create or update a public IP address within a specified resource group. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBname\fP \-\- The name of the public IP address to create. .IP \(bu 2 \fBresource_group\fP \-\- The resource group name assigned to the public IP address. .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-call azurearm_network.public_ip_address_create_or_update test\-ip\-0 testgroup .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.azurearm_network.public_ip_address_delete(name, resource_group, **kwargs) New in version 2019.2.0. .sp Delete a public IP address. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBname\fP \-\- The name of the public IP address to delete. .IP \(bu 2 \fBresource_group\fP \-\- The resource group name assigned to the public IP address. .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-call azurearm_network.public_ip_address_delete test\-pub\-ip testgroup .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.azurearm_network.public_ip_address_get(name, resource_group, **kwargs) New in version 2019.2.0. .sp Get details about a specific public IP address. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBname\fP \-\- The name of the public IP address to query. .IP \(bu 2 \fBresource_group\fP \-\- The resource group name assigned to the public IP address. .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-call azurearm_network.public_ip_address_get test\-pub\-ip testgroup .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.azurearm_network.public_ip_addresses_list(resource_group, **kwargs) New in version 2019.2.0. .sp List all public IP addresses within a resource group. .INDENT 7.0 .TP .B Parameters \fBresource_group\fP \-\- The resource group name to list public IP addresses within. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-call azurearm_network.public_ip_addresses_list testgroup .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.azurearm_network.public_ip_addresses_list_all(**kwargs) New in version 2019.2.0. .sp List all public IP addresses within a subscription. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-call azurearm_network.public_ip_addresses_list_all .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.azurearm_network.route_create_or_update(name, address_prefix, next_hop_type, route_table, resource_group, next_hop_ip_address=None, **kwargs) New in version 2019.2.0. .sp Create or update a route within a specified route table. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBname\fP \-\- The name of the route to create. .IP \(bu 2 \fBaddress_prefix\fP \-\- The destination CIDR to which the route applies. .IP \(bu 2 \fBnext_hop_type\fP \-\- The type of Azure hop the packet should be sent to. Possible values are: \(aqVirtualNetworkGateway\(aq, \(aqVnetLocal\(aq, \(aqInternet\(aq, \(aqVirtualAppliance\(aq, and \(aqNone\(aq. .IP \(bu 2 \fBnext_hop_ip_address\fP \-\- Optional IP address to which packets should be forwarded. Next hop values are only allowed in routes where the next_hop_type is \(aqVirtualAppliance\(aq. .IP \(bu 2 \fBroute_table\fP \-\- The name of the route table containing the route. .IP \(bu 2 \fBresource_group\fP \-\- The resource group name assigned to the route table. .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-call azurearm_network.route_create_or_update test\-rt \(aq10.0.0.0/8\(aq test\-rt\-table testgroup .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.azurearm_network.route_delete(name, route_table, resource_group, **kwargs) New in version 2019.2.0. .sp Delete a route from a route table. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBname\fP \-\- The route to delete. .IP \(bu 2 \fBroute_table\fP \-\- The route table containing the route. .IP \(bu 2 \fBresource_group\fP \-\- The resource group name assigned to the route table. .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-call azurearm_network.route_delete test\-rt test\-rt\-table testgroup .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.azurearm_network.route_filter_create_or_update(name, resource_group, **kwargs) New in version 2019.2.0. .sp Create or update a route filter within a specified resource group. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBname\fP \-\- The name of the route filter to create. .IP \(bu 2 \fBresource_group\fP \-\- The resource group name assigned to the route filter. .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-call azurearm_network.route_filter_create_or_update test\-filter testgroup .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.azurearm_network.route_filter_delete(name, resource_group, **kwargs) New in version 2019.2.0. .sp Delete a route filter. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBname\fP \-\- The name of the route filter to delete. .IP \(bu 2 \fBresource_group\fP \-\- The resource group name assigned to the route filter. .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-call azurearm_network.route_filter_delete test\-filter testgroup .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.azurearm_network.route_filter_get(name, resource_group, **kwargs) New in version 2019.2.0. .sp Get details about a specific route filter. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBname\fP \-\- The name of the route table to query. .IP \(bu 2 \fBresource_group\fP \-\- The resource group name assigned to the route filter. .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-call azurearm_network.route_filter_get test\-filter testgroup .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.azurearm_network.route_filter_rule_create_or_update(name, access, communities, route_filter, resource_group, **kwargs) New in version 2019.2.0. .sp Create or update a rule within a specified route filter. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBname\fP \-\- The name of the rule to create. .IP \(bu 2 \fBaccess\fP \-\- The access type of the rule. Valid values are \(aqAllow\(aq and \(aqDeny\(aq. .IP \(bu 2 \fBcommunities\fP \-\- A list of BGP communities to filter on. .IP \(bu 2 \fBroute_filter\fP \-\- The name of the route filter containing the rule. .IP \(bu 2 \fBresource_group\fP \-\- The resource group name assigned to the route filter. .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-call azurearm_network.route_filter_rule_create_or_update test\-rule allow "[\(aq12076:51006\(aq]" test\-filter testgroup .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.azurearm_network.route_filter_rule_delete(name, route_filter, resource_group, **kwargs) New in version 2019.2.0. .sp Delete a route filter rule. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBname\fP \-\- The route filter rule to delete. .IP \(bu 2 \fBroute_filter\fP \-\- The route filter containing the rule. .IP \(bu 2 \fBresource_group\fP \-\- The resource group name assigned to the route filter. .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-call azurearm_network.route_filter_rule_delete test\-rule test\-filter testgroup .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.azurearm_network.route_filter_rule_get(name, route_filter, resource_group, **kwargs) New in version 2019.2.0. .sp Get details about a specific route filter rule. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBname\fP \-\- The route filter rule to query. .IP \(bu 2 \fBroute_filter\fP \-\- The route filter containing the rule. .IP \(bu 2 \fBresource_group\fP \-\- The resource group name assigned to the route filter. .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-call azurearm_network.route_filter_rule_get test\-rule test\-filter testgroup .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.azurearm_network.route_filter_rules_list(route_filter, resource_group, **kwargs) New in version 2019.2.0. .sp List all routes within a route filter. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBroute_filter\fP \-\- The route filter to query. .IP \(bu 2 \fBresource_group\fP \-\- The resource group name assigned to the route filter. .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-call azurearm_network.route_filter_rules_list test\-filter testgroup .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.azurearm_network.route_filters_list(resource_group, **kwargs) New in version 2019.2.0. .sp List all route filters within a resource group. .INDENT 7.0 .TP .B Parameters \fBresource_group\fP \-\- The resource group name to list route filters within. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-call azurearm_network.route_filters_list testgroup .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.azurearm_network.route_filters_list_all(**kwargs) New in version 2019.2.0. .sp List all route filters within a subscription. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-call azurearm_network.route_filters_list_all .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.azurearm_network.route_get(name, route_table, resource_group, **kwargs) New in version 2019.2.0. .sp Get details about a specific route. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBname\fP \-\- The route to query. .IP \(bu 2 \fBroute_table\fP \-\- The route table containing the route. .IP \(bu 2 \fBresource_group\fP \-\- The resource group name assigned to the route table. .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-call azurearm_network.route_get test\-rt test\-rt\-table testgroup .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.azurearm_network.route_table_create_or_update(name, resource_group, **kwargs) New in version 2019.2.0. .sp Create or update a route table within a specified resource group. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBname\fP \-\- The name of the route table to create. .IP \(bu 2 \fBresource_group\fP \-\- The resource group name assigned to the route table. .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-call azurearm_network.route_table_create_or_update test\-rt\-table testgroup .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.azurearm_network.route_table_delete(name, resource_group, **kwargs) New in version 2019.2.0. .sp Delete a route table. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBname\fP \-\- The name of the route table to delete. .IP \(bu 2 \fBresource_group\fP \-\- The resource group name assigned to the route table. .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-call azurearm_network.route_table_delete test\-rt\-table testgroup .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.azurearm_network.route_table_get(name, resource_group, **kwargs) New in version 2019.2.0. .sp Get details about a specific route table. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBname\fP \-\- The name of the route table to query. .IP \(bu 2 \fBresource_group\fP \-\- The resource group name assigned to the route table. .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-call azurearm_network.route_table_get test\-rt\-table testgroup .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.azurearm_network.route_tables_list(resource_group, **kwargs) New in version 2019.2.0. .sp List all route tables within a resource group. .INDENT 7.0 .TP .B Parameters \fBresource_group\fP \-\- The resource group name to list route tables within. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-call azurearm_network.route_tables_list testgroup .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.azurearm_network.route_tables_list_all(**kwargs) New in version 2019.2.0. .sp List all route tables within a subscription. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-call azurearm_network.route_tables_list_all .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.azurearm_network.routes_list(route_table, resource_group, **kwargs) New in version 2019.2.0. .sp List all routes within a route table. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBroute_table\fP \-\- The route table to query. .IP \(bu 2 \fBresource_group\fP \-\- The resource group name assigned to the route table. .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-call azurearm_network.routes_list test\-rt\-table testgroup .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.azurearm_network.security_rule_create_or_update(name, access, direction, priority, protocol, security_group, resource_group, source_address_prefix=None, destination_address_prefix=None, source_port_range=None, destination_port_range=None, source_address_prefixes=None, destination_address_prefixes=None, source_port_ranges=None, destination_port_ranges=None, **kwargs) New in version 2019.2.0. .sp Create or update a security rule within a specified network security group. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBname\fP \-\- The name of the security rule to create. .IP \(bu 2 \fBaccess\fP \-\- \(aqallow\(aq or \(aqdeny\(aq .IP \(bu 2 \fBdirection\fP \-\- \(aqinbound\(aq or \(aqoutbound\(aq .IP \(bu 2 \fBpriority\fP \-\- Integer between 100 and 4096 used for ordering rule application. .IP \(bu 2 \fBprotocol\fP \-\- \(aqtcp\(aq, \(aqudp\(aq, or \(aq*\(aq .IP \(bu 2 \fBdestination_address_prefix\fP \-\- The CIDR or destination IP range. Asterix \(aq*\(aq can also be used to match all destination IPs. Default tags such as \(aqVirtualNetwork\(aq, \(aqAzureLoadBalancer\(aq and \(aqInternet\(aq can also be used. If this is an ingress rule, specifies where network traffic originates from. .IP \(bu 2 \fBdestination_port_range\fP \-\- The destination port or range. Integer or range between 0 and 65535. Asterix \(aq*\(aq can also be used to match all ports. .IP \(bu 2 \fBsource_address_prefix\fP \-\- The CIDR or source IP range. Asterix \(aq*\(aq can also be used to match all source IPs. Default tags such as \(aqVirtualNetwork\(aq, \(aqAzureLoadBalancer\(aq and \(aqInternet\(aq can also be used. If this is an ingress rule, specifies where network traffic originates from. .IP \(bu 2 \fBsource_port_range\fP \-\- The source port or range. Integer or range between 0 and 65535. Asterix \(aq*\(aq can also be used to match all ports. .IP \(bu 2 \fBdestination_address_prefixes\fP \-\- A list of destination_address_prefix values. This parameter overrides destination_address_prefix and will cause any value entered there to be ignored. .IP \(bu 2 \fBdestination_port_ranges\fP \-\- A list of destination_port_range values. This parameter overrides destination_port_range and will cause any value entered there to be ignored. .IP \(bu 2 \fBsource_address_prefixes\fP \-\- A list of source_address_prefix values. This parameter overrides source_address_prefix and will cause any value entered there to be ignored. .IP \(bu 2 \fBsource_port_ranges\fP \-\- A list of source_port_range values. This parameter overrides source_port_range and will cause any value entered there to be ignored. .IP \(bu 2 \fBsecurity_group\fP \-\- The network security group containing the security rule. .IP \(bu 2 \fBresource_group\fP \-\- The resource group name assigned to the network security group. .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-call azurearm_network.security_rule_create_or_update testrule1 allow outbound 101 tcp testnsg testgroup source_address_prefix=\(aq*\(aq destination_address_prefix=internet source_port_range=\(aq*\(aq destination_port_range=\(aq1\-1024\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.azurearm_network.security_rule_delete(security_rule, security_group, resource_group, **kwargs) New in version 2019.2.0. .sp Delete a security rule within a specified security group. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBname\fP \-\- The name of the security rule to delete. .IP \(bu 2 \fBsecurity_group\fP \-\- The network security group containing the security rule. .IP \(bu 2 \fBresource_group\fP \-\- The resource group name assigned to the network security group. .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-call azurearm_network.security_rule_delete testrule1 testnsg testgroup .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.azurearm_network.security_rule_get(security_rule, security_group, resource_group, **kwargs) New in version 2019.2.0. .sp Get a security rule within a specified network security group. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBname\fP \-\- The name of the security rule to query. .IP \(bu 2 \fBsecurity_group\fP \-\- The network security group containing the security rule. .IP \(bu 2 \fBresource_group\fP \-\- The resource group name assigned to the network security group. .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-call azurearm_network.security_rule_get testrule1 testnsg testgroup .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.azurearm_network.security_rules_list(security_group, resource_group, **kwargs) New in version 2019.2.0. .sp List security rules within a network security group. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBsecurity_group\fP \-\- The network security group to query. .IP \(bu 2 \fBresource_group\fP \-\- The resource group name assigned to the network security group. .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-call azurearm_network.security_rules_list testnsg testgroup .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.azurearm_network.subnet_create_or_update(name, address_prefix, virtual_network, resource_group, **kwargs) New in version 2019.2.0. .sp Create or update a subnet. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBname\fP \-\- The name assigned to the subnet being created or updated. .IP \(bu 2 \fBaddress_prefix\fP \-\- A valid CIDR block within the virtual network. .IP \(bu 2 \fBvirtual_network\fP \-\- The virtual network name containing the subnet. .IP \(bu 2 \fBresource_group\fP \-\- The resource group name assigned to the virtual network. .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-call azurearm_network.subnet_create_or_update testsubnet \(aq10.0.0.0/24\(aq testnet testgroup .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.azurearm_network.subnet_delete(name, virtual_network, resource_group, **kwargs) New in version 2019.2.0. .sp Delete a subnet. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBname\fP \-\- The name of the subnet to delete. .IP \(bu 2 \fBvirtual_network\fP \-\- The virtual network name containing the subnet. .IP \(bu 2 \fBresource_group\fP \-\- The resource group name assigned to the virtual network. .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-call azurearm_network.subnet_delete testsubnet testnet testgroup .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.azurearm_network.subnet_get(name, virtual_network, resource_group, **kwargs) New in version 2019.2.0. .sp Get details about a specific subnet. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBname\fP \-\- The name of the subnet to query. .IP \(bu 2 \fBvirtual_network\fP \-\- The virtual network name containing the subnet. .IP \(bu 2 \fBresource_group\fP \-\- The resource group name assigned to the virtual network. .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-call azurearm_network.subnet_get testsubnet testnet testgroup .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.azurearm_network.subnets_list(virtual_network, resource_group, **kwargs) New in version 2019.2.0. .sp List all subnets within a virtual network. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBvirtual_network\fP \-\- The virtual network name to list subnets within. .IP \(bu 2 \fBresource_group\fP \-\- The resource group name assigned to the virtual network. .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-call azurearm_network.subnets_list testnet testgroup .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.azurearm_network.usages_list(location, **kwargs) New in version 2019.2.0. .sp List subscription network usage for a location. .INDENT 7.0 .TP .B Parameters \fBlocation\fP \-\- The Azure location to query for network usage. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-call azurearm_network.usages_list westus .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.azurearm_network.virtual_network_create_or_update(name, address_prefixes, resource_group, **kwargs) New in version 2019.2.0. .sp Create or update a virtual network. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBname\fP \-\- The name assigned to the virtual network being created or updated. .IP \(bu 2 \fBaddress_prefixes\fP \-\- A list of CIDR blocks which can be used by subnets within the virtual network. .IP \(bu 2 \fBresource_group\fP \-\- The resource group name assigned to the virtual network. .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-call azurearm_network.virtual_network_create_or_update testnet [\(aq10.0.0.0/16\(aq] testgroup .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.azurearm_network.virtual_network_delete(name, resource_group, **kwargs) New in version 2019.2.0. .sp Delete a virtual network. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBname\fP \-\- The name of the virtual network to delete. .IP \(bu 2 \fBresource_group\fP \-\- The resource group name assigned to the virtual network .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-call azurearm_network.virtual_network_delete testnet testgroup .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.azurearm_network.virtual_network_get(name, resource_group, **kwargs) New in version 2019.2.0. .sp Get details about a specific virtual network. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBname\fP \-\- The name of the virtual network to query. .IP \(bu 2 \fBresource_group\fP \-\- The resource group name assigned to the virtual network. .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-call azurearm_network.virtual_network_get testnet testgroup .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.azurearm_network.virtual_networks_list(resource_group, **kwargs) New in version 2019.2.0. .sp List all virtual networks within a resource group. .INDENT 7.0 .TP .B Parameters \fBresource_group\fP \-\- The resource group name to list virtual networks within. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-call azurearm_network.virtual_networks_list testgroup .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.azurearm_network.virtual_networks_list_all(**kwargs) New in version 2019.2.0. .sp List all virtual networks within a subscription. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-call azurearm_network.virtual_networks_list_all .ft P .fi .UNINDENT .UNINDENT .UNINDENT .SS salt.modules.azurearm_resource .sp Azure (ARM) Resource Execution Module .sp New in version 2019.2.0. .INDENT 0.0 .TP .B maintainer <\fI\%devops@decisionlab.io\fP> .TP .B maturity new .TP .B depends .INDENT 7.0 .IP \(bu 2 \fI\%azure\fP >= 2.0.0 .IP \(bu 2 \fI\%azure\-common\fP >= 1.1.8 .IP \(bu 2 \fI\%azure\-mgmt\fP >= 1.0.0 .IP \(bu 2 \fI\%azure\-mgmt\-compute\fP >= 1.0.0 .IP \(bu 2 \fI\%azure\-mgmt\-network\fP >= 1.7.1 .IP \(bu 2 \fI\%azure\-mgmt\-resource\fP >= 1.1.0 .IP \(bu 2 \fI\%azure\-mgmt\-storage\fP >= 1.0.0 .IP \(bu 2 \fI\%azure\-mgmt\-web\fP >= 0.32.0 .IP \(bu 2 \fI\%azure\-storage\fP >= 0.34.3 .IP \(bu 2 \fI\%msrestazure\fP >= 0.4.21 .UNINDENT .TP .B platform linux .TP .B configuration This module requires Azure Resource Manager credentials to be passed as keyword arguments to every function in order to work properly. .sp Required provider parameters: .INDENT 7.0 .TP .B if using username and password: .INDENT 7.0 .IP \(bu 2 \fBsubscription_id\fP .IP \(bu 2 \fBusername\fP .IP \(bu 2 \fBpassword\fP .UNINDENT .TP .B if using a service principal: .INDENT 7.0 .IP \(bu 2 \fBsubscription_id\fP .IP \(bu 2 \fBtenant\fP .IP \(bu 2 \fBclient_id\fP .IP \(bu 2 \fBsecret\fP .UNINDENT .UNINDENT .sp Optional provider parameters: .UNINDENT .INDENT 0.0 .TP \fBcloud_environment\fP: Used to point the cloud driver to different API endpoints, such as Azure GovCloud. .INDENT 7.0 .TP .B Possible values: .INDENT 7.0 .IP \(bu 2 \fBAZURE_PUBLIC_CLOUD\fP (default) .IP \(bu 2 \fBAZURE_CHINA_CLOUD\fP .IP \(bu 2 \fBAZURE_US_GOV_CLOUD\fP .IP \(bu 2 \fBAZURE_GERMAN_CLOUD\fP .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.azurearm_resource.deployment_cancel(name, resource_group, **kwargs) New in version 2019.2.0. .sp Cancel a deployment if in \(aqAccepted\(aq or \(aqRunning\(aq state. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBname\fP \-\- The name of the deployment to cancel. .IP \(bu 2 \fBresource_group\fP \-\- The resource group name assigned to the deployment. .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-call azurearm_resource.deployment_cancel testdeploy testgroup .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.azurearm_resource.deployment_check_existence(name, resource_group, **kwargs) New in version 2019.2.0. .sp Check the existence of a deployment. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBname\fP \-\- The name of the deployment to query. .IP \(bu 2 \fBresource_group\fP \-\- The resource group name assigned to the deployment. .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-call azurearm_resource.deployment_check_existence testdeploy testgroup .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.azurearm_resource.deployment_create_or_update(name, resource_group, deploy_mode=\(aqincremental\(aq, debug_setting=\(aqnone\(aq, deploy_params=None, parameters_link=None, deploy_template=None, template_link=None, **kwargs) New in version 2019.2.0. .sp Deploys resources to a resource group. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBname\fP \-\- The name of the deployment to create or update. .IP \(bu 2 \fBresource_group\fP \-\- The resource group name assigned to the deployment. .IP \(bu 2 \fBdeploy_mode\fP \-\- The mode that is used to deploy resources. This value can be either \(aqincremental\(aq or \(aqcomplete\(aq. In Incremental mode, resources are deployed without deleting existing resources that are not included in the template. In Complete mode, resources are deployed and existing resources in the resource group that are not included in the template are deleted. Be careful when using Complete mode as you may unintentionally delete resources. .IP \(bu 2 \fBdebug_setting\fP \-\- The debug setting of the deployment. The permitted values are \(aqnone\(aq, \(aqrequestContent\(aq, \(aqresponseContent\(aq, or \(aqrequestContent,responseContent\(aq. By logging information about the request or response, you could potentially expose sensitive data that is retrieved through the deployment operations. .IP \(bu 2 \fBdeploy_params\fP \-\- JSON string containing name and value pairs that define the deployment parameters for the template. You use this element when you want to provide the parameter values directly in the request rather than link to an existing parameter file. Use either the parameters_link property or the deploy_params property, but not both. .IP \(bu 2 \fBparameters_link\fP \-\- The URI of a parameters file. You use this element to link to an existing parameters file. Use either the parameters_link property or the deploy_params property, but not both. .IP \(bu 2 \fBdeploy_template\fP \-\- JSON string of template content. You use this element when you want to pass the template syntax directly in the request rather than link to an existing template. Use either the template_link property or the deploy_template property, but not both. .IP \(bu 2 \fBtemplate_link\fP \-\- The URI of the template. Use either the template_link property or the deploy_template property, but not both. .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-call azurearm_resource.deployment_create_or_update testdeploy testgroup .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.azurearm_resource.deployment_delete(name, resource_group, **kwargs) New in version 2019.2.0. .sp Delete a deployment. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBname\fP \-\- The name of the deployment to delete. .IP \(bu 2 \fBresource_group\fP \-\- The resource group name assigned to the deployment. .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-call azurearm_resource.deployment_delete testdeploy testgroup .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.azurearm_resource.deployment_export_template(name, resource_group, **kwargs) New in version 2019.2.0. .sp Exports the template used for the specified deployment. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBname\fP \-\- The name of the deployment to query. .IP \(bu 2 \fBresource_group\fP \-\- The resource group name assigned to the deployment. .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-call azurearm_resource.deployment_export_template testdeploy testgroup .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.azurearm_resource.deployment_get(name, resource_group, **kwargs) New in version 2019.2.0. .sp Get details about a specific deployment. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBname\fP \-\- The name of the deployment to query. .IP \(bu 2 \fBresource_group\fP \-\- The resource group name assigned to the deployment. .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-call azurearm_resource.deployment_get testdeploy testgroup .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.azurearm_resource.deployment_operation_get(operation, deployment, resource_group, **kwargs) New in version 2019.2.0. .sp Get a deployment operation within a deployment. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBoperation\fP \-\- The operation ID of the operation within the deployment. .IP \(bu 2 \fBdeployment\fP \-\- The name of the deployment containing the operation. .IP \(bu 2 \fBresource_group\fP \-\- The resource group name assigned to the deployment. .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-call azurearm_resource.deployment_operation_get XXXXX testdeploy testgroup .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.azurearm_resource.deployment_operations_list(name, resource_group, result_limit=10, **kwargs) New in version 2019.2.0. .sp List all deployment operations within a deployment. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBname\fP \-\- The name of the deployment to query. .IP \(bu 2 \fBresource_group\fP \-\- The resource group name assigned to the deployment. .IP \(bu 2 \fBresult_limit\fP \-\- (Default: 10) The limit on the list of deployment operations. .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-call azurearm_resource.deployment_operations_list testdeploy testgroup .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.azurearm_resource.deployment_validate(name, resource_group, deploy_mode=None, debug_setting=None, deploy_params=None, parameters_link=None, deploy_template=None, template_link=None, **kwargs) New in version 2019.2.0. .sp Validates whether the specified template is syntactically correct and will be accepted by Azure Resource Manager. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBname\fP \-\- The name of the deployment to validate. .IP \(bu 2 \fBresource_group\fP \-\- The resource group name assigned to the deployment. .IP \(bu 2 \fBdeploy_mode\fP \-\- The mode that is used to deploy resources. This value can be either \(aqincremental\(aq or \(aqcomplete\(aq. In Incremental mode, resources are deployed without deleting existing resources that are not included in the template. In Complete mode, resources are deployed and existing resources in the resource group that are not included in the template are deleted. Be careful when using Complete mode as you may unintentionally delete resources. .IP \(bu 2 \fBdebug_setting\fP \-\- The debug setting of the deployment. The permitted values are \(aqnone\(aq, \(aqrequestContent\(aq, \(aqresponseContent\(aq, or \(aqrequestContent,responseContent\(aq. By logging information about the request or response, you could potentially expose sensitive data that is retrieved through the deployment operations. .IP \(bu 2 \fBdeploy_params\fP \-\- JSON string containing name and value pairs that define the deployment parameters for the template. You use this element when you want to provide the parameter values directly in the request rather than link to an existing parameter file. Use either the parameters_link property or the deploy_params property, but not both. .IP \(bu 2 \fBparameters_link\fP \-\- The URI of a parameters file. You use this element to link to an existing parameters file. Use either the parameters_link property or the deploy_params property, but not both. .IP \(bu 2 \fBdeploy_template\fP \-\- JSON string of template content. You use this element when you want to pass the template syntax directly in the request rather than link to an existing template. Use either the template_link property or the deploy_template property, but not both. .IP \(bu 2 \fBtemplate_link\fP \-\- The URI of the template. Use either the template_link property or the deploy_template property, but not both. .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-call azurearm_resource.deployment_validate testdeploy testgroup .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.azurearm_resource.deployments_list(resource_group, **kwargs) New in version 2019.2.0. .sp List all deployments within a resource group. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-call azurearm_resource.deployments_list testgroup .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.azurearm_resource.policy_assignment_create(name, scope, definition_name, **kwargs) New in version 2019.2.0. .sp Create a policy assignment. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBname\fP \-\- The name of the policy assignment to create. .IP \(bu 2 \fBscope\fP \-\- The scope of the policy assignment. .IP \(bu 2 \fBdefinition_name\fP \-\- The name of the policy definition to assign. .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-call azurearm_resource.policy_assignment_create testassign /subscriptions/bc75htn\-a0fhsi\-349b\-56gh\-4fghti\-f84852 testpolicy .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.azurearm_resource.policy_assignment_delete(name, scope, **kwargs) New in version 2019.2.0. .sp Delete a policy assignment. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBname\fP \-\- The name of the policy assignment to delete. .IP \(bu 2 \fBscope\fP \-\- The scope of the policy assignment. .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-call azurearm_resource.policy_assignment_delete testassign /subscriptions/bc75htn\-a0fhsi\-349b\-56gh\-4fghti\-f84852 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.azurearm_resource.policy_assignment_get(name, scope, **kwargs) New in version 2019.2.0. .sp Get details about a specific policy assignment. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBname\fP \-\- The name of the policy assignment to query. .IP \(bu 2 \fBscope\fP \-\- The scope of the policy assignment. .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-call azurearm_resource.policy_assignment_get testassign /subscriptions/bc75htn\-a0fhsi\-349b\-56gh\-4fghti\-f84852 .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.azurearm_resource.policy_assignments_list(**kwargs) New in version 2019.2.0. .sp List all policy assignments for a subscription. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-call azurearm_resource.policy_assignments_list .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.azurearm_resource.policy_assignments_list_for_resource_group(resource_group, **kwargs) New in version 2019.2.0. .sp List all policy assignments for a resource group. .INDENT 7.0 .TP .B Parameters \fBresource_group\fP \-\- The resource group name to list policy assignments within. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-call azurearm_resource.policy_assignments_list_for_resource_group testgroup .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.azurearm_resource.policy_definition_create_or_update(name, policy_rule, **kwargs) New in version 2019.2.0. .sp Create or update a policy definition. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBname\fP \-\- The name of the policy definition to create or update. .IP \(bu 2 \fBpolicy_rule\fP \-\- A dictionary defining the \fI\%policy rule\fP\&. .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-call azurearm_resource.policy_definition_create_or_update testpolicy \(aq{...rule definition..}\(aq .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.azurearm_resource.policy_definition_delete(name, **kwargs) New in version 2019.2.0. .sp Delete a policy definition. .INDENT 7.0 .TP .B Parameters \fBname\fP \-\- The name of the policy definition to delete. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-call azurearm_resource.policy_definition_delete testpolicy .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.azurearm_resource.policy_definition_get(name, **kwargs) New in version 2019.2.0. .sp Get details about a specific policy definition. .INDENT 7.0 .TP .B Parameters \fBname\fP \-\- The name of the policy definition to query. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-call azurearm_resource.policy_definition_get testpolicy .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.azurearm_resource.policy_definitions_list(hide_builtin=False, **kwargs) New in version 2019.2.0. .sp List all policy definitions for a subscription. .INDENT 7.0 .TP .B Parameters \fBhide_builtin\fP \-\- Boolean which will filter out BuiltIn policy definitions from the result. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-call azurearm_resource.policy_definitions_list .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.azurearm_resource.resource_group_check_existence(name, **kwargs) New in version 2019.2.0. .sp Check for the existence of a named resource group in the current subscription. .INDENT 7.0 .TP .B Parameters \fBname\fP \-\- The resource group name to check. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-call azurearm_resource.resource_group_check_existence testgroup .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.azurearm_resource.resource_group_create_or_update(name, location, **kwargs) New in version 2019.2.0. .sp Create or update a resource group in a given location. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBname\fP \-\- The name of the resource group to create or update. .IP \(bu 2 \fBlocation\fP \-\- The location of the resource group. This value is not able to be updated once the resource group is created. .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-call azurearm_resource.resource_group_create_or_update testgroup westus .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.azurearm_resource.resource_group_delete(name, **kwargs) New in version 2019.2.0. .sp Delete a resource group from the subscription. .INDENT 7.0 .TP .B Parameters \fBname\fP \-\- The resource group name to delete. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-call azurearm_resource.resource_group_delete testgroup .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.azurearm_resource.resource_group_get(name, **kwargs) New in version 2019.2.0. .sp Get a dictionary representing a resource group\(aqs properties. .INDENT 7.0 .TP .B Parameters \fBname\fP \-\- The resource group name to get. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-call azurearm_resource.resource_group_get testgroup .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.azurearm_resource.resource_groups_list(**kwargs) New in version 2019.2.0. .sp List all resource groups within a subscription. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-call azurearm_resource.resource_groups_list .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.azurearm_resource.subscription_get(subscription_id=None, **kwargs) New in version 2019.2.0. .sp Get details about a subscription. .INDENT 7.0 .TP .B Parameters \fBsubscription_id\fP \-\- The ID of the subscription to query. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-call azurearm_resource.subscription_get XXXXXXXX .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.azurearm_resource.subscriptions_list(**kwargs) New in version 2019.2.0. .sp List all subscriptions for a tenant. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-call azurearm_resource.subscriptions_list .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.azurearm_resource.subscriptions_list_locations(subscription_id=None, **kwargs) New in version 2019.2.0. .sp List all locations for a subscription. .INDENT 7.0 .TP .B Parameters \fBsubscription_id\fP \-\- The ID of the subscription to query. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-call azurearm_resource.subscriptions_list_locations XXXXXXXX .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.azurearm_resource.tenants_list(**kwargs) New in version 2019.2.0. .sp List all tenants for your account. .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt\-call azurearm_resource.tenants_list .ft P .fi .UNINDENT .UNINDENT .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 .INDENT 3.5 .sp .nf .ft C bamboohr: apikey: 012345678901234567890 subdomain: mycompany .ft P .fi .UNINDENT .UNINDENT .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.baredoc module .sp Baredoc walks the installed module and state directories and generates dictionaries and lists of the function names and their arguments. .sp New in version 3001. .INDENT 0.0 .TP .B salt.modules.baredoc.list_modules(name=False, names_only=False) Walk the Salt install tree for execution modules and return a dictionary or a list of their functions as well as their arguments. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBname\fP \-\- specify a specific module to list. If not specified, all modules will be listed. .IP \(bu 2 \fBnames_only\fP \-\- Return only a list of the callable functions instead of a dictionary with arguments .UNINDENT .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion baredoc.list_modules myminion: \-\-\-\-\-\-\-\-\-\- [...] at: \- atq: tag: null \- atrm: args: args \- at: args: args kwargs: kwargs \- atc: jobid: null \- jobcheck: kwargs: kwargs [...] .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.baredoc.list_states(name=False, names_only=False) Walk the Salt install tree for state modules and return a dictionary or a list of their functions as well as their arguments. .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBname\fP \-\- specify a specific module to list. If not specified, all modules will be listed. .IP \(bu 2 \fBnames_only\fP \-\- Return only a list of the callable functions instead of a dictionary with arguments .UNINDENT .UNINDENT .sp CLI Example: (example truncated for brevity) .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion baredoc.list_states myminion: \-\-\-\-\-\-\-\-\-\- [...] at: \- present: name: null timespec: null tag: null user: null job: null unique_tag: false \- absent: name: null jobid: null kwargs: kwargs \- watch: name: null timespec: null tag: null user: null job: null unique_tag: false \- mod_watch: name: null kwargs: kwargs [...] .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.baredoc.module_docs(*names) Return the docstrings for all modules. Optionally, specify a module or a function to narrow the selection. .INDENT 7.0 .TP .B Parameters \fBname\fP \-\- specify a specific module to list. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion baredoc.module_docs .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.baredoc.state_docs(*names) Return the docstrings for all state modules. Optionally, specify a state module or a function to narrow the selection. .INDENT 7.0 .TP .B Parameters \fBname\fP \-\- specify a specific module to list. .UNINDENT .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt myminion baredoc.state_docs at .ft P .fi .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 its 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 its 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 "[{\(aqprocesses\(aq: {\(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 beacons 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 a 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. .TP .B Return type \fI\%bool\fP .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, include_pillar=True, include_opts=True, **kwargs) List the beacons currently configured on the minion .INDENT 7.0 .TP .B Parameters .INDENT 7.0 .IP \(bu 2 \fBreturn_yaml\fP \-\- Whether to return YAML formatted output, default \fBTrue\fP .IP \(bu 2 \fBinclude_pillar\fP \-\- Whether to include beacons that are configured in pillar, default is \fBTrue\fP\&. .IP \(bu 2 \fBinclude_opts\fP \-\- Whether to include beacons that are configured in opts, default is \fBTrue\fP\&. .UNINDENT .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.list_available(return_yaml=True, **kwargs) List the beacons currently available on the minion .INDENT 7.0 .TP .B Parameters \fBreturn_yaml\fP \-\- Whether to return YAML formatted output, default \fBTrue\fP .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_available .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.reset(**kwargs) Resest beacon configuration on the minion .sp CLI Example: .INDENT 7.0 .INDENT 3.5 .sp .nf .ft C salt \(aq*\(aq beacons.reset .ft P .fi .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B salt.modules.beacons.save(**kwargs) Save all configured beacons to the minion config .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: